Obtener una dispersión con su historia de transiciones

GET/payments/{id}Probar

URL base

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

Parámetros de ruta

idstringobligatorio

Enviar peticiónCopiar como curl

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}

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

• Pruebas (sandbox)
• Producción

Scope payments:read. Devuelve events: cada transición de estado, con quién la provocó (actor) y por qué.

El ejemplo muestra el recorrido típico: el asiento se confirma (ledger_committed), el riel acepta de forma asíncrona (rail_accepted_async, sigue en submitted) y nuestro proceso de resolución cierra al consultar al riel (resolved_by_reaper). Entre el segundo y el tercer evento pasan segundos o minutos.

Authorizations

• ApiKeyAuth

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

Pago

Media typeapplication/json

object

id

string format: uuid

customer_id

string format: uuid

nullable

beneficiary_id

Presente en dispersiones a terceros

string format: uuid

nullable

status

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

unknown = el riel no confirmó y no sabemos si pagó. NO reintentar: se resuelve consultando al proveedor y notificamos por webhook.

string

Allowed values: created pending submitted unknown settled failed returned reversed

status_reason

string

nullable

source_asset

string

Allowed values: BS USD USDC VESC

source_amount

string

payout_asset

string

Allowed values: BS USD 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

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

events

Historia de transiciones

Array<object>

object

from_status

string

nullable

to_status

string

reason

string

nullable

actor

string

Allowed values: api provider_event 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": "rail_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

Media typeapplication/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 provider_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"
  }
}