Ir al contenido
Bolívar Connect

El flujo, paso a paso

Captura de una dispersión ejecutada de punta a punta contra el entorno de pruebas del disperador. Salieron 1.100,00 Bs por pago móvil y 1.871,60 Bs por transferencia, a bancos venezolanos distintos, y el dinero se descontó del saldo. Los cuerpos son los que viajaron por el cable, sólo con los identificadores cambiados por sus equivalentes de prueba; las latencias son las de esa ejecución.

Son diez llamadas en el orden en que las hace una fintech ya conectada: consultar bancos, cotizar, dispersar, comprobar en el banco, reintentar sin pagar dos veces, cotizar en divisa, dispersar por otro instrumento, consultar el pago, listar el día y mirar el saldo.

Traza real·10 llamadas·3393 ms de reloj
Pago móvil
1.100,00 Bs submitted
Transferencia
1.871,60 Bs submitted
Saldo al cerrar
499.996.998,50 Bs
Capturada
1 de septiembre de 2026 a las 16:18 UTC

Paso 1 de 10

GET/v1/payouts/banks?method=pago_movil342 ms

1. Consulta los bancos que acepta el instrumento

Devuelve 31 bancos para pago móvil. Abajo se muestran los cuatro primeros; el resto viene en la misma lista.

Respuesta

{
  "method": "pago_movil",
  "data": [
    {
      "code": "0001",
      "name": "Banco Central de Venezuela",
      "shortName": "BCV"
    },
    {
      "code": "0102",
      "name": "Banco de Venezuela S.A.C.A. Banco Universal",
      "shortName": "Banco de Venezuela"
    },
    {
      "code": "0104",
      "name": "Venezolano de Crédito, S.A. Banco Universal",
      "shortName": "Venezolano de Crédito"
    },
    {
      "code": "0105",
      "name": "Banco Mercantil, C.A. Banco Universal",
      "shortName": "Mercantil"
    }
  ]
}

La lista de transferencia es más corta. Por eso `method` es obligatorio.

POST/v1/quotes9 ms

2. Cotiza un importe exacto en bolívares

Fijas `deliver` y el beneficiario cobra ese importe exacto; la comisión se suma en `spend`. Sin conversión, `rate` viene a null.

Cuerpo enviado

{
  "deliver": {
    "asset": "BS",
    "amount": 110000
  }
}

Respuesta

{
  "id": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "fixed": "deliver",
  "spend": {
    "asset": "BS",
    "amount": "111100"
  },
  "deliver": {
    "asset": "BS",
    "amount": "110000"
  },
  "fee": {
    "asset": "BS",
    "amount": "1100"
  },
  "rate": null,
  "status": "open",
  "expires_at": "2026-09-01T16:18:59.096Z",
  "created_at": "2026-09-01T16:17:59.096Z"
}
POST/v1/payouts1331 ms

3. Dispersa por pago móvil

Los datos del beneficiario van en la misma llamada: no hace falta darlo de alta antes. El teléfono es obligatorio.

Cabeceras

{
  "Idempotency-Key": "nomina-2026-09-01-0042"
}

Cuerpo enviado

{
  "quoteId": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "method": "pago_movil",
  "beneficiary": {
    "fullName": "Maria Rodriguez",
    "nationalId": "V12345678",
    "bankCode": "0102",
    "phone": "04241111111"
  },
  "sender": {
    "nationalId": "V34567890",
    "firstName": "Ana",
    "lastName": "Rivas",
    "phone": "04143333333",
    "email": "ana@ejemplo.com"
  }
}

Respuesta

{
  "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "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": "110000",
  "feeAmount": "1100",
  "totalDebited": "111100",
  "method": "pago_movil",
  "methodRequested": "pago_movil",
  "methodChanged": false,
  "beneficiaryId": "c8be416d-ceb1-4529-873c-74bce8606894",
  "beneficiary": {
    "fullName": "Maria Rodriguez",
    "nationalId": "V12345678",
    "bankCode": "0102",
    "instrument": "pago_movil"
  }
}

El estado es `submitted`, no `settled`: el banco aceptó la orden y entrega después.

GEThttps://api.disperador/api/v1/transactions/{externalId}210 ms

4. La transacción existe en el banco

Consultada en la API del disperador por NUESTRA referencia. Es la única comprobación del recorrido que no pasa por nuestro código.

Respuesta

{
  "_id": "6a96fab84d4009d23974aa14",
  "token": {
    "name": "USDT-POLYGON",
    "symbol": "USDT"
  },
  "chain": "Polygon Mainnet",
  "transactionType": "pagoMovilWithdraw",
  "amount": 1.16629,
  "fiatAmount": 1100,
  "status": "en progreso",
  "exchangeRate": {
    "currencyFrom": {
      "name": "USDT",
      "symbol": "USDT"
    },
    "currencyTo": {
      "name": "Bolivar",
      "symbol": "VES"
    },
    "exchangeRateNumber": 943.162
  },
  "senderData": {
    "identificationNumber": "V34567890",
    "name": "Ana",
    "lastName": "Rivas",
    "phoneNumber": "04143333333",
    "email": "ana@ejemplo.com"
  },
  "externalId": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "createdAt": "2026-09-01T16:18:00.435Z",
  "updatedAt": "2026-09-01T16:18:00.585Z",
  "pagoMovilData": {
    "phoneNumber": "04241111111",
    "identificationNumber": "V12345678",
    "beneficiaryName": "Maria Rodriguez",
    "bank": {
      "name": "Banco de Venezuela",
      "code": "0102"
    }
  }
}

Entrega 1100 Bs exactos. El banco cobra en divisa (1.16629 USDT), pero eso es asunto nuestro.

POST/v1/payouts4 ms

5. Reenvía la misma petición tras un timeout

Con la misma Idempotency-Key. Devuelve el pago original en lugar de crear otro, así que un reintento de tu cola no paga dos veces.

Cabeceras

{
  "Idempotency-Key": "nomina-2026-09-01-0042"
}

Cuerpo enviado

{
  "quoteId": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "method": "pago_movil",
  "beneficiary": {
    "fullName": "Maria Rodriguez",
    "nationalId": "V12345678",
    "bankCode": "0102",
    "phone": "04241111111"
  },
  "sender": {
    "nationalId": "V34567890",
    "firstName": "Ana",
    "lastName": "Rivas",
    "phone": "04143333333",
    "email": "ana@ejemplo.com"
  }
}

Respuesta

{
  "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "asset": "BS",
  "amount": "110000",
  "method": "pago_movil",
  "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.",
  "feeAmount": "1100",
  "beneficiary": {
    "bankCode": "0102",
    "fullName": "Maria Rodriguez",
    "instrument": "pago_movil",
    "nationalId": "V12345678"
  },
  "totalDebited": "111100",
  "bankReference": null,
  "beneficiaryId": "c8be416d-ceb1-4529-873c-74bce8606894",
  "methodChanged": false,
  "methodRequested": "pago_movil"
}

Mismo `id` que la primera llamada.

POST/v1/quotes9 ms

6. O cotiza en dólares, si tu saldo está en divisa

Aquí fijas `spend` y te devolvemos lo que llega. MISMA forma de respuesta que arriba: sólo cambia qué lado fijaste (`fixed`) y que ahora `rate` viene rellena.

Cuerpo enviado

{
  "spend": {
    "asset": "USD",
    "amount": 5000
  },
  "deliver": {
    "asset": "BS"
  }
}

Respuesta

{
  "id": "477174b9-a9bb-4f31-8407-3661ae29bffe",
  "fixed": "spend",
  "spend": {
    "asset": "USD",
    "amount": "5000"
  },
  "deliver": {
    "asset": "BS",
    "amount": "187160"
  },
  "fee": {
    "asset": "BS",
    "amount": "1890"
  },
  "rate": {
    "value": "37.81",
    "market": "38",
    "spread_bps": 50
  },
  "status": "open",
  "expires_at": "2026-09-01T16:19:00.652Z",
  "created_at": "2026-09-01T16:18:00.652Z"
}

Para dispersar bolívares suele convenir fijar `deliver`: con ésta el importe entregado te sale de la tasa, no lo eliges tú.

POST/v1/payouts1477 ms

7. Dispersa por transferencia bancaria

Mismo endpoint, otro instrumento. Cambia lo que identifica al beneficiario: cuenta de 20 dígitos en vez de teléfono, aunque el teléfono sigue haciendo falta.

Cabeceras

{
  "Idempotency-Key": "nomina-2026-09-01-0043"
}

Cuerpo enviado

{
  "quoteId": "477174b9-a9bb-4f31-8407-3661ae29bffe",
  "method": "transferencia",
  "beneficiary": {
    "fullName": "Juan Perez",
    "nationalId": "V23456789",
    "bankCode": "0108",
    "accountNumber": "01080000000000000002",
    "phone": "04141111111"
  },
  "sender": {
    "nationalId": "V45678901",
    "firstName": "Ana",
    "lastName": "Rivas",
    "phone": "04142222222",
    "email": "ana@ejemplo.com"
  }
}

Respuesta

{
  "id": "a4f320a2-5964-49aa-8628-97a6aa418bd2",
  "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": "187160",
  "feeAmount": "1890",
  "totalDebited": "189050",
  "method": "transferencia",
  "methodRequested": "transferencia",
  "methodChanged": false,
  "beneficiaryId": "ae3c8182-d543-46e9-aad0-873da3eeb196",
  "beneficiary": {
    "fullName": "Juan Perez",
    "nationalId": "V23456789",
    "bankCode": "0108",
    "instrument": "transferencia"
  }
}
GET/v1/payments/71103d0a-4e59-4a9a-b3c1-de6917b8bbc15 ms

8. Consulta un pago concreto

Con su historial de estados. `bank_reference` es el comprobante que reclama el beneficiario y aparece al liquidar.

Respuesta

{
  "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
  "tenant_id": "1254fc3f-fbe5-46cf-adcc-8428b5c397a7",
  "customer_id": null,
  "beneficiary_id": "c8be416d-ceb1-4529-873c-74bce8606894",
  "status": "submitted",
  "status_reason": "rail_accepted_async",
  "source_asset": "BS",
  "source_amount": "111100",
  "payout_asset": "BS",
  "payout_amount": "110000",
  "fee_amount": "1100",
  "method": "pago_movil",
  "counterparty": "04241111111",
  "bank_reference": null,
  "quote_id": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
  "ledger_transaction_id": "7d6ec749-c75a-48eb-af5c-9282bb5441d7",
  "compensated": false,
  "settled_at": null,
  "created_at": "2026-09-01T16:17:59.106Z",
  "updated_at": "2026-09-01T16:18:00.424Z",
  "events": [
    {
      "from_status": null,
      "to_status": "submitted",
      "reason": "ledger_committed",
      "actor": "api",
      "metadata": {
        "quoteId": "2f02beb0-dfbe-4f74-9ad2-b1b1737a7066",
        "beneficiaryId": "c8be416d-ceb1-4529-873c-74bce8606894",
        "ledgerTransactionId": "7d6ec749-c75a-48eb-af5c-9282bb5441d7"
      },
      "created_at": "2026-09-01T16:17:59.106Z"
    },
    {
      "from_status": "submitted",
      "to_status": "submitted",
      "reason": "rail_accepted_async",
      "actor": "api",
      "metadata": {
        "methodUsed": "pago_movil",
        "methodRequested": "pago_movil"
      },
      "created_at": "2026-09-01T16:18:00.424Z"
    }
  ]
}
GET/v1/payments?limit=52 ms

9. Lista sus transacciones

Acepta `from`, `to`, `status` y `beneficiaryId`. El rango de fechas mide LIQUIDACIÓN, no creación: un pago en vuelo no entra en el cierre de hoy.

Respuesta

{
  "data": [
    {
      "id": "a4f320a2-5964-49aa-8628-97a6aa418bd2",
      "customer_id": null,
      "beneficiary_id": "ae3c8182-d543-46e9-aad0-873da3eeb196",
      "status": "submitted",
      "status_reason": "rail_accepted_async",
      "source_asset": "USD",
      "source_amount": "5000",
      "payout_asset": "BS",
      "payout_amount": "187160",
      "fee_amount": "1890",
      "method": "transferencia",
      "bank_reference": null,
      "settled_at": null,
      "created_at": "2026-09-01T16:18:00.656Z"
    },
    {
      "id": "71103d0a-4e59-4a9a-b3c1-de6917b8bbc1",
      "customer_id": null,
      "beneficiary_id": "c8be416d-ceb1-4529-873c-74bce8606894",
      "status": "submitted",
      "status_reason": "rail_accepted_async",
      "source_asset": "BS",
      "source_amount": "111100",
      "payout_asset": "BS",
      "payout_amount": "110000",
      "fee_amount": "1100",
      "method": "pago_movil",
      "bank_reference": null,
      "settled_at": null,
      "created_at": "2026-09-01T16:17:59.106Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
GET/v1/treasury/position?asset=BS4 ms

10. Consulta cuánto saldo le queda

Cada dispersión descuenta el importe entregado más la comisión.

Respuesta

{
  "tenantId": "1254fc3f-fbe5-46cf-adcc-8428b5c397a7",
  "asset": "BS",
  "prefundingBalance": "49999699850",
  "platformRevenueFromTenant": "2990",
  "creditEnabled": true,
  "creditDrawn": "0",
  "creditLimit": null,
  "creditAvailable": null
}

Lo que conviene mirar dos veces

Sección titulada «Lo que conviene mirar dos veces»
  • El paso 3 devuelve submitted, no settled. Es el desenlace normal del riel. El paso 4 lo confirma desde la API del disperador, donde el estado es «en progreso». Ver estados de un pago.
  • El paso 5 repite el POST /v1/payouts con la misma Idempotency-Key y devuelve el pago original, con el mismo id, en 4 ms. Ver idempotencia.
  • Los pasos 2 y 6 son las dos formas de cotizar y devuelven la misma forma. El 2 fija deliver; el 6 fija spend. Entre los dos cuerpos cambian fixed y que en el 6 rate viene rellena; los nombres de los campos, no. Ver cotizar en bolívares.
  • La única referencia del envío es bank_reference, el comprobante que ve el beneficiario en su banco.

Reproducirlo

Sección titulada «Reproducirlo»

Son las llamadas que documenta tu primera dispersión, con una sk_test_… y los datos del entorno de pruebas.