Cuadrar un día

GET /v1/payments es el extracto: lo que se liquidó un día, para sumarlo y compararlo con tus registros.

curl -s "$BASE/v1/payments?from=2026-08-30&to=2026-08-30&status=settled&limit=100" \
  -H "x-api-key: $KEY"

200 OK

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

Filtros

Parámetro	Formato	Qué hace
from	YYYY-MM-DD	Desde este día, inclusive
to	YYYY-MM-DD	Hasta este día, inclusive
status	settled, submitted, unknown, failed, reversed…	Filtra por desenlace
beneficiaryId	uuid	Todas las dispersiones a una persona
customerId	uuid	Las de un usuario tuyo, si lo mandaste al dispersar
limit · cursor	int (máx. 100) · string	Paginación por cursor

`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. Es la misma regla que usa nuestro cierre.

El orden de la página, en cambio, es created_at descendente: es lo que hace estable el cursor mientras sigues dispersando.

Los tres campos que hacen cuadrable el extracto

Campo	Para qué
settled_at	La fecha que decide a qué día pertenece el pago
beneficiary_id	Enlaza la fila con la persona, sin abrir cada pago
bank_reference	El comprobante que ve el beneficiario. Lo asigna el banco, está a null hasta que el envío se completa, y es el único identificador de envío del extracto

Cuadrar una jornada

1. Pide el día completo, filtrando por liquidadas.

2. Suma payout_amount y fee_amount de todas las filas, en unidades menores y con enteros; nunca con coma flotante.

3. Sigue con next_cursor mientras has_more sea true. El cursor es un keyset: no hay filas duplicadas ni saltadas aunque sigas dispersando.

4. Compara con tu deuda viva, GET /v1/treasury/position?asset=BS.

Total liquidado y comisiones de un día

DIA=2026-08-30
CURSOR=""
TOTAL=0; FEES=0; N=0

while :; do
  RESP=$(curl -s "$BASE/v1/payments?from=$DIA&to=$DIA&status=settled&limit=100&cursor=$CURSOR" \
          -H "x-api-key: $KEY")
  TOTAL=$(( TOTAL + $(echo "$RESP" | jq '[.data[].payout_amount | tonumber] | add // 0') ))
  FEES=$((  FEES  + $(echo "$RESP" | jq '[.data[].fee_amount    | tonumber] | add // 0') ))
  N=$((     N     + $(echo "$RESP" | jq '.data | length') ))
  [ "$(echo "$RESP" | jq -r .has_more)" = "true" ] || break
  CURSOR=$(echo "$RESP" | jq -r .next_cursor)
done

echo "$N dispersiones · entregado $TOTAL · comisiones $FEES (unidades menores)"

Qué entra en el día y qué no

Estado al momento del corte	¿Entra?	Por qué
settled	Sí	El dinero salió
failed	No	El asiento ya se revirtió: no debes nada, y fee_amount es 0
submitted	No	Pasa al día en que liquide
unknown	No	Pasa al día en que se resuelva
reversed	No en el día del envío	El banco devolvió; los fondos volvieron a tu saldo

Si tu conteo no cuadra, mira primero cómo marcas los pagos

El descuadre habitual es marcar la dispersión como pagada cuando responde POST /payouts. La respuesta habitual es submitted, no settled. Marca con el webhook payment.settled. Ver seguimiento.

Otras consultas que resuelve el extracto

# Todo lo que le hemos pagado a una persona
curl -s "$BASE/v1/payments?beneficiaryId=8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2&limit=100" \
  -H "x-api-key: $KEY"

# Lo que se cayó este mes, para reintentarlo
curl -s "$BASE/v1/payments?from=2026-08-01&to=2026-08-31&status=failed&limit=100" \
  -H "x-api-key: $KEY"

# Lo que sigue en duda
curl -s "$BASE/v1/payments?status=unknown&limit=100" -H "x-api-key: $KEY"

Para el detalle de una fila —incluida la historia de transiciones— GET /v1/payments/{id}. Ver seguimiento.