Entorno de pruebas

Una clave sk_test_… opera en modo test: no mueve dinero real. El contrato es idéntico al de producción —mismas rutas, campos, errores y firma de webhook—.

curl -s $BASE/v1/tenant/me -H "x-api-key: $KEY"
# { "mode": "test", ... }

Con prefondeo por ticket, tu cuenta de pruebas no tiene wallet: tu prefondeo de pruebas ya viene cargado con Bs simulados (GET /v1/prefondeos).

Dónde probar

En QA (https://qa.bolivarconnect.com) y con la key sk_test_ de tu cuenta de pruebas (environment: "sandbox" en GET /v1/tenant/me). Tus pagos salen por redes de pago simuladas: nunca tocan una red real ni el dinero de nadie. Para pasar a producción cambias la URL y la key; el contrato no cambia.

# Beneficiarios de prueba y, según tu modelo de fondeo, saldo simulado
curl -s -X POST $BASE/v1/test-helpers/seed -H "x-api-key: $KEY"

Beneficiarios de prueba

Ficticios: no son de nadie. POST /v1/test-helpers/seed los da de alta, o los mandas en línea en beneficiary.

Nombre	Cédula	Banco	Teléfono	Cuenta	Instrumento
Prueba Pago Movil	`V10000001`	`0102`	`04140000001`	—	Pago móvil
Prueba Transferencia	`V10000002`	`0134`	`04140000002`	`01340000000000000002`	Transferencia
Prueba Otro Banco	`V10000003`	`0105`	`04240000003`	`01050000000000000003`	Transferencia

Para un rechazo inmediato: banco 9999 (reason: bank_unreachable) o un fullName que empiece por NO TITULAR (reason: beneficiary_mismatch).

Provocar los escenarios difíciles

Se eligen pago por pago, en el reference (concepto) de POST /v1/payouts. No afectan a ningún otro pago, tuyo ni de otra cuenta, aunque los repitas muchas veces seguidas (los rechazos con 9999 y NO TITULAR tampoco).

`reference`	Respuesta	Qué deberías ver después
(ninguno) o `TEST:SETTLED`	`settled`	Webhook `payment.settled`
`TEST:SUBMITTED`	`submitted`	Nada hasta que lo resuelves: `settled` o `failed`
`TEST:UNKNOWN`	`unknown`	Nada hasta que lo resuelves: `settled` o `failed`. No reintentes
`TEST:TIMEOUT_AFTER_SUBMIT`	`unknown`	La red pagó y se cortó la respuesta: se resuelve solo a `settled` en menos de un minuto. El caso peligroso

Puede seguir más texto tras un espacio (TEST:UNKNOWN lote 7).

Para cerrar un pago en curso o devolver uno liquidado:

curl -s -X POST $BASE/v1/test-helpers/payments/<paymentId>/resolve -H "x-api-key: $KEY" \
  -H 'content-type: application/json' -d '{"outcome":"failed"}'

`outcome`	Sobre	Queda	Webhook
`settled`	`submitted` o `unknown`	`settled`	`payment.settled`
`failed`	`submitted` o `unknown` (no si la red ya pagó: 409)	`failed`, revertido	`payment.failed`
`returned`	`settled`	`reversed`, revertido con la comisión	`payment.reversed`

/v1/test-helpers/* sólo responde a una sk_test_ de una cuenta de pruebas (403 test_account_required con cualquier otra) y no existe en producción (404).

Con cuenta propia

Si tu modelo es own_account (funding.model en GET /v1/tenant/capabilities), tu cuenta de pruebas se comporta como la de producción:

El pago no liquida en el acto. Sin escenario (o con TEST:SETTLED) responde submitted y se liquida solo en unos 20 s, con el webhook payment.settled. TEST:SUBMITTED lo deja en curso hasta que lo resuelves; TEST:UNKNOWN y TEST:TIMEOUT_AFTER_SUBMIT funcionan como arriba.
Los mismos datos que en producción. El remitente (sender) es obligatorio, y el beneficiario lleva nombre y apellido. Pago móvil exige el móvil del beneficiario; en transferencia, si no lo traes, va el del remitente (si es venezolano).
Tope de USD 500 por operación, a la tasa del día, además del límite en Bs de tu cuenta. Por encima: failed con reason: amount_above_limit.
Tu saldo es tu inventario (GET /v1/treasury/inventory, no position). Cada pago lo baja por el importe más la comisión de la red de pago, que ves en networkFeeBs de GET /v1/treasury/volume. En el sandbox la comisión simulada de la red es 0,3 %; en real la fija la red de pago y te llega en el reporte. Si no alcanza, failed con reason: payout_insufficient_balance y el inventario queda igual. Si un pago en curso termina failed, vuelve el importe; la comisión no.
Para tener saldo: seed deja una tasa de venta USDT de ejemplo (1.000,00) y, si tu inventario está en cero, un cambio de 1.000.000,00 Bs a esa tasa. Para más, anota tus propios cambios de USD a Bs:

curl -s -X POST $BASE/v1/test-helpers/fundings -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"amountUsd":100000,"amountBs":100000000,"reference":"cambio-0001"}'

En producción ese cambio lo anota y lo aprueba nuestro equipo; aquí queda aprobado al momento y entra al costo promedio con el que se valora cada pago. Repetir la referencia con los mismos montos devuelve el mismo cambio; con otros, 409 funding_reference_reused. Pide payments:write.

Sólo en local: caos global

Si corres la plataforma en tu máquina con SANDBOX_ENABLED=true, además tienes /sandbox/*, que afecta a todos los pagos del servidor. No existe en QA ni en producción.

curl -s -X POST $BASE/sandbox/chaos -H 'content-type: application/json' \
  -d '{"mode":"timeout_after_submit","method":"pago_movil"}'

`mode`	Qué simula	Qué deberías ver
`reject`	La red de pago rechaza sin mover dinero	Sale por otro canal o red de pago, o `status: "failed"` con `reason`
`timeout`	No responde antes de ejecutar	`status: "unknown"`, sin compensar
`timeout_after_submit`	Paga y se corta la respuesta	`status: "unknown"`, sin compensar. El caso peligroso
`slow`	Añade latencia	Todo igual, pero lento
`off`	Normalidad

method es opcional: sin él, el escenario se aplica a los dos instrumentos. Con él reproduces «pago móvil caído, transferencia operativa» y ves el cambio de canal (methodChanged: true).

curl -s $BASE/sandbox/chaos             # escenario activo
curl -s -X POST $BASE/sandbox/chaos/reset

Simular al banco (sólo local)

Todas con content-type: application/json:

`POST`	Cuerpo	Qué simula
`/sandbox/bank/payout-settled`	`{"paymentId":"89920401-…"}`	La red de pago confirma tarde una dispersión en duda
`/sandbox/bank/payout-returned`	`{"paymentId":"89920401-…"}`	El banco devuelve, días después, una dispersión liquidada
`/sandbox/bank/prefunding-wire`	`{"amount":100000000,"asset":"BS"}`	Llega tu transferencia de fondeo

Probar tu receptor de webhooks (sólo local)

En QA, usa POST /v1/tenant/webhook/test contra tu URL.

Endpoint	Para qué
`GET /sandbox/webhooks`	Sink: lo que te hemos enviado, con firma y cabeceras
`POST /sandbox/webhooks/failing`	Receptor que siempre devuelve 500
`GET /sandbox/outbox`	La cola con intentos y estado
`GET /sandbox/canales`	Estado y escenario de caos de cada canal

Combínalo con la cola de fallidos real, GET /v1/events?status=dead y POST /v1/events/retry-dead. Ver webhooks.

Consola de demostración

/demo/consola ejecuta los escenarios de punta a punta con respuestas reales de la API: pago normal, canal caído, pago en duda, rechazo total, circuito abierto y control de permisos.