Get a payout with its transition history

GET/payments/{id}Probar

ServidorURL base

API key x-api-keyRecordar la clave en este navegador (localStorage, no sale de aquí)

Parámetros de rutaidstringobligatorio

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

GET

/payments/{id}

const url = 'http://localhost:3000/v1/payments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:3000/v1/payments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'x-api-key: <x-api-key>'

Scope payments:read. Returns events: each status transition, with who caused it (actor) and why.

The example shows the typical path: the ledger entry is committed (ledger_committed), the payment network accepts asynchronously (payout_accepted_async, still submitted) and our resolution process closes it when it checks with the payment network (resolved_by_reaper). Seconds or minutes pass between the second and third events.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

required

string format: uuid

Responses

200

Pago

application/json

object

string format: uuid

customer_id

string format: uuid

nullable

beneficiary_id

Presente en dispersiones a terceros

string format: uuid

nullable

status

submitted = la red de pago la aceptó y está liquidando. Es el estado HABITUAL justo después de dispersar, porque la red de pago de bolívares es asíncrona. No reintentar: se cierra por webhook.

unknown = la red de pago no confirmó y no sabemos si pagó. NO reintentar: se resuelve automáticamente y te notificamos por webhook.

string

Allowed values: created pending submitted unknown settled failed returned reversed

status_reason

string

nullable

source_asset

Decimales: BS y USD 2; USDT y USDC 6 (1000000 = 1 USDT).

string

Allowed values: BS USD USDT USDC VESC

source_amount

string

payout_asset

Decimales: BS y USD 2; USDT y USDC 6 (1000000 = 1 USDT).

string

Allowed values: BS USD USDT USDC VESC

payout_amount

string

fee_amount

string

method

string

nullable

bank_reference

El comprobante que ve el beneficiario en su banco. null hasta que el envío se completa.

string

nullable

reference

El concepto que mandaste al dispersar. null si no mandaste ninguno. No es bank_reference.

string

nullable

quote_id

string format: uuid

nullable

compensated

true si el asiento contable se revirtió

boolean

settled_at

string format: date-time

nullable

created_at

string format: date-time

updated_at

string format: date-time

prefondeo

Sólo con prefondeo por ticket: de qué tickets salió el pago (un tramo por ticket, del más viejo al más nuevo). Vacío en los demás modelos.

Array<object>

De qué ticket salió una parte de un pago

object

Id del ticket

string format: uuid

montoBs

string

tasa

string

costoUsdt

string

revertido

El pago falló o se devolvió y el tramo volvió a su ticket

boolean

events

Historia de transiciones

Array<object>

object

from_status

string

nullable

to_status

string

reason

string

nullable

actor

string

Allowed values: api network reaper system

metadata

Contexto de la transición. En una dispersión, methodRequested y methodUsed.

object

created_at

string format: date-time

Example

{
  "id": "89920401-26da-4f69-b57d-bc20e0366ce2",
  "customer_id": null,
  "beneficiary_id": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
  "status": "settled",
  "status_reason": null,
  "source_asset": "BS",
  "source_amount": "5050000",
  "payout_asset": "BS",
  "payout_amount": "5000000",
  "fee_amount": "50000",
  "method": "pago_movil",
  "bank_reference": "012345678901",
  "compensated": false,
  "settled_at": "2026-08-31T19:06:44.120Z",
  "events": [
    {
      "from_status": null,
      "to_status": "submitted",
      "reason": "ledger_committed",
      "actor": "api",
      "created_at": "2026-08-31T19:04:01.900Z"
    },
    {
      "from_status": "submitted",
      "to_status": "submitted",
      "reason": "payout_accepted_async",
      "actor": "api",
      "created_at": "2026-08-31T19:04:02.551Z"
    },
    {
      "from_status": "submitted",
      "to_status": "settled",
      "reason": "resolved_by_reaper",
      "actor": "reaper",
      "created_at": "2026-08-31T19:06:44.120Z"
    }
  ]
}

404

Error con código estable

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}