Tu primera dispersión

Cinco llamadas para entregar 50.000,00 Bs por pago móvil, ejecutables contra el entorno de pruebas tal como están.

Variables que usan todos los ejemplos

BASE=http://localhost:3000      # o https://api.tu-dominio.com
KEY=sk_test_...                 # tu API key, en el header x-api-key

1. Confirma con qué key estás llamando

   curl -s $BASE/v1/tenant/me -H "x-api-key: $KEY"

   200 OK

   {
     "tenantId": "3f1a0c22-9b41-4a77-8f0e-6d2c5b7a1e34", "name": "Fintech Ejemplo",
     "mode": "test",
     "scopes": ["quotes:write", "beneficiaries:write", "beneficiaries:read",
                "payments:write", "payments:read", "treasury:read",
                "events:read", "events:write"],
     "apiKeyId": "5c9d2b70-1f44-4c8e-9a3b-2e7f0d5a6b18", "isPlatform": false
   }

   mode dice si mueves dinero real. Ver autenticación.

2. Pide el catálogo de bancos del instrumento que vas a usar

   curl -s "$BASE/v1/payouts/banks?method=pago_movil" -H "x-api-key: $KEY"

   200 OK (recortado)

   {
     "method": "pago_movil",
     "data": [
       { "code": "0102", "name": "Banco de Venezuela S.A.C.A. Banco Universal", "shortName": "Banco de Venezuela" },
       { "code": "0105", "name": "Banco Mercantil, C.A. Banco Universal",       "shortName": "Mercantil" },
       { "code": "0108", "name": "Banco Provincial, S.A. Banco Universal",      "shortName": "Banco Provincial - BBVA" },
       { "code": "0134", "name": "Banesco Banco Universal S.A.C.A.",            "shortName": "Banesco" }
     ]
   }

   `method` es obligatorio, y las dos listas no coinciden

   31 bancos alcanzables por pago móvil y 24 por transferencia. Sin method, 400 validation_failed. Ver beneficiarios.

3. Cotiza el importe exacto en bolívares

   curl -s $BASE/v1/quotes \
     -H "x-api-key: $KEY" -H 'content-type: application/json' \
     -d '{"deliver":{"asset":"BS","amount":5000000}}'

   201 Created

   {
     "id": "70ec44b5-c1df-45b1-86fe-8f92c3959689", "fixed": "deliver",
     "spend":   { "asset": "BS", "amount": "5050000" },
     "deliver": { "asset": "BS", "amount": "5000000" },
     "fee":     { "asset": "BS", "amount":   "50000" },
     "rate": null, "status": "open",
     "expires_at": "2026-08-31T20:22:36.022Z", "created_at": "2026-08-31T20:21:36.022Z"
   }

   deliver son los 50.000,00 Bs que recibe el beneficiario, fee los 500,00 Bs de comisión y spend los 50.500,00 Bs que se te debitan. Los montos van en unidades menores: BS tiene 2 decimales, así que 5000000 = 50.000,00 Bs. Ver importes.

   Si fondeas en divisa, fijas spend en vez de deliver y la respuesta trae los mismos campos con rate rellena. Ver cotizar.

   La cotización caduca en ~60 segundos

   Es de un solo uso. Cotiza justo antes de dispersar. Usarla dos veces da 409 quote_already_consumed; pasarla caducada, 422 quote_expired. Cotizar es gratis: cotiza tantas veces como quieras y consume la última.

4. Dispersa

   curl -s $BASE/v1/payouts \
     -H "x-api-key: $KEY" -H 'content-type: application/json' \
     -H 'Idempotency-Key: payout-2026-0001' \
     -d '{"quoteId":"70ec44b5-c1df-45b1-86fe-8f92c3959689","method":"pago_movil",
          "beneficiary":{"fullName":"María Gómez","nationalId":"V12345678",
                         "bankCode":"0138","phone":"04141234567"},
          "sender":{"nationalId":"V18234112","firstName":"Ana","lastName":"Pérez",
                    "phone":"04241234567","email":"ana@example.com"}}'

   201 Created

   {
     "id": "89920401-26da-4f69-b57d-bc20e0366ce2", "status": "submitted",
     "message": "El riel aceptó el envío y todavía no lo ha liquidado. Se confirmará por webhook (payment.settled); no lo reintentes con otra Idempotency-Key.",
     "bankReference": null, "asset": "BS", "amount": "5000000",
     "feeAmount": "50000", "totalDebited": "5050000",
     "method": "pago_movil", "methodRequested": "pago_movil", "methodChanged": false,
     "beneficiaryId": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
     "beneficiary": { "fullName": "María Gómez", "nationalId": "V12345678",
                      "bankCode": "0138", "instrument": "pago_movil" }
   }

   Cuatro campos que rompen integraciones si se pasan por alto:

   • Idempotency-Key. Un reintento de red sin ella paga dos veces. Ver idempotencia.
   • beneficiary.phone. Obligatorio también en transferencia.
   • beneficiary.fullName. Nombre y apellido con pinta de reales: un marcador de posición acaba en failed. Los beneficiarios de prueba vienen sin titular, y el sandbox no comprueba la titularidad; producción sí.
   • sender. Quién ordena el envío. Si no lo mandas, se deriva del customerId o del remitente por defecto de tu programa; sin ninguno, el pago falla antes de salir.

   Fíjate en el estado: `submitted`, no `settled`

   El riel es asíncrono: submitted es el desenlace normal. Si tu código exige settled aquí, funciona en el sandbox y se rompe en producción. Ver estados de un pago.

5. Recibe el desenlace

   El resultado llega por webhook, una sola vez:

   POST a tu webhookUrl

   { "id": "40545", "eventType": "payment.settled", "attempt": 1,
     "payload": { "paymentId": "89920401-26da-4f69-b57d-bc20e0366ce2",
                  "asset": "BS", "amount": "5000000", "method": "pago_movil",
                  "bankReference": "012345678901" } }

   Verifica la firma HMAC y deduplica por id: la entrega es at-least-once. Ver webhooks. También puedes consultarlo:

   curl -s $BASE/v1/payments/89920401-26da-4f69-b57d-bc20e0366ce2 -H "x-api-key: $KEY"

   200 OK (recortado)

   {
     "id": "89920401-26da-4f69-b57d-bc20e0366ce2", "status": "settled",
     "payout_asset": "BS", "payout_amount": "5000000", "fee_amount": "50000",
     "method": "pago_movil", "bank_reference": "012345678901",
     "settled_at": "2026-08-31T19:06:44.120Z",
     "events": [
       { "to_status": "submitted", "reason": "ledger_committed",    "actor": "api" },
       { "to_status": "submitted", "reason": "rail_accepted_async", "actor": "api" },
       { "to_status": "settled",   "reason": "resolved_by_reaper",  "actor": "reaper" }
     ]
   }

   bank_reference es el comprobante que ve el beneficiario en su banco.

Qué leer después

Si vas a…	Lee
ver estas llamadas ejecutadas de verdad	El flujo, paso a paso
entender qué objetos maneja la API	Cómo funciona
pagar a cuenta en vez de a teléfono	Registrar un beneficiario
montar la pantalla de tu usuario	Seguir el pago
cuadrar la jornada	Cuadrar un día
poner esto en producción	Antes de ir a producción

Convenciones de la API

Tema	En una línea
Base URL	https://api.tu-dominio.com/v1 · pruebas: http://localhost:3000/v1
Autenticación	Header x-api-key. Las keys sk_test_… no mueven dinero real
Importes	Enteros en unidades menores. 50.000,00 Bs es 5000000. Número en la petición, string en la respuesta
Idempotencia	Idempotency-Key en toda dispersión, siempre
Paginación	Por cursor (limit + cursor), nunca por offset. Máximo 100
Errores	Programa contra error.code, nunca contra el mensaje
Webhooks	Firmados con HMAC-SHA256. Entrega at-least-once: deduplica por id
Mínimo por operación	~925 Bs. Detalle
Tope por operación	Pago móvil: 100.000,00 Bs. Transferencia: 500.000,00 Bs