Extracto de dispersiones

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. El extracto: filtra por rango de fechas, estado, beneficiario o usuario, y pagina por cursor. Es con lo que se cuadra una jornada.

from y to filtran por settled_at, no por created_at: una dispersión creada a las 23:58 y liquidada a las 00:03 pertenece al día siguiente. El orden de la página, en cambio, es created_at descendente, que es lo que hace estable el cursor.

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 = 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

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 = 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

Motivo del estado. En un failed, el reason del riel

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

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.

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