Payout statement

GET/paymentsProbar

URL base

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

Parámetros de consulta

fromstringDesde este día, INCLUSIVE. Filtra por `settled_at`.tostringHasta este día, INCLUSIVE. Filtra por `settled_at`.statusFiltra por desenlace. `settled` para cuadrar; `unknown` y `failed` para vigilar.beneficiaryIdstringTodas las dispersiones que ha recibido una personacustomerIdstringTu usuario, si lo mandaste al dispersarlimitintegercursorstring`next_cursor` de la página anterior

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

curl --request GET \
  --url 'http://localhost:3000/v1/payments?from=2026-08-30&to=2026-08-30&status=created&limit=25' \
  --header 'x-api-key: <x-api-key>'

• Pruebas (sandbox)
• Producción

Scope payments:read. The statement: filter by date range, status, beneficiary or user, and page by cursor. It is what you reconcile a day with.

from and to filter by settled_at, not by created_at: a payout created at 23:58 and settled at 00:03 belongs to the next day. The page order, on the other hand, is created_at descending, which is what keeps the cursor stable.

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

from

string format: date

Example

2026-08-30

Desde este día, INCLUSIVE. Filtra por settled_at.

to

string format: date

Example

2026-08-30

Hasta este día, INCLUSIVE. Filtra por settled_at.

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

Filtra por desenlace. settled para cuadrar; unknown y failed para vigilar.

beneficiaryId

string format: uuid

Todas las dispersiones que ha recibido una persona

customerId

string format: uuid

Tu usuario, si lo mandaste al dispersar

limit

integer

default: 25 >= 1 <= 100

cursor

string

next_cursor de la página anterior

Responses

200

Página del extracto

Media typeapplication/json

object

data

Array<object>

object

has_more

boolean

next_cursor

string

nullable

data

Array<object>

Fila del extracto (GET /payments). Trae lo necesario para cuadrar un día sin abrir cada pago: a quién, cuánto, cuándo liquidó y con qué comprobante. Para la historia de transiciones, GET /payments/{id}.

object

id

string format: uuid

customer_id

string format: uuid

nullable

beneficiary_id

A quién se le entregó

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

Motivo del estado. En un failed, el reason de la red de pago

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

Lo que recibió el beneficiario

string

fee_amount

Nuestra comisión. 0 en un pago failed

string

method

string

nullable

bank_reference

El comprobante que ve el beneficiario en su banco. Es el número que te va a citar cuando pregunte «¿con qué referencia me pagaste?». Es el único identificador del envío que publicamos. null hasta que el envío se completa. En el entorno de pruebas es simulado y tiene la forma SIM- + 12 caracteres hexadecimales.

string

nullable

reference

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

string

nullable

settled_at

Cuándo salió el dinero de verdad. Es la fecha por la que filtran from y to, y la que decide a qué cierre pertenece el pago.

string format: date-time

nullable

created_at

Cuándo lo pediste

string format: date-time

Example

{
  "data": [
    {
      "id": "89920401-26da-4f69-b57d-bc20e0366ce2",
      "customer_id": null,
      "beneficiary_id": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
      "status": "settled",
      "status_reason": null,
      "payout_asset": "BS",
      "payout_amount": "5000000",
      "fee_amount": "50000",
      "method": "pago_movil",
      "bank_reference": "012345678901",
      "settled_at": "2026-08-30T19:06:44.120Z",
      "created_at": "2026-08-30T19:04:01.812Z"
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOC0zMFQxOTowNDowMS44MTJafDg5OTIwNDAx"
}

400

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 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"
  }
}