Reconcile a day

GET /v1/payments is the statement: what settled on a given day, to add it up and compare it with your records.

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",
      "reference": "Nómina octubre 0007",
      "settled_at": "2026-08-30T19:06:44.120Z",
      "created_at": "2026-08-30T19:04:01.812Z" }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOC0zMFQxOTowNDowMS44MTJafDg5OTIwNDAx"
}

Filters

Parameter	Format	What it does
from	YYYY-MM-DD	From this day, inclusive
to	YYYY-MM-DD	Up to this day, inclusive
status	settled, submitted, unknown, failed, reversed…	Filters by outcome
beneficiaryId	uuid	All payouts to one person
customerId	uuid	Those of one of your users, if you sent it when paying out
limit · cursor	int (max. 100) · string	Cursor pagination

`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. It is the same rule our close uses.

The order of the page, on the other hand, is created_at descending: that is what keeps the cursor stable while you keep paying out.

The fields that make the statement reconcilable

Field	What for
settled_at	The date that decides which day the payment belongs to
beneficiary_id	Links the row to the person, without opening each payment
bank_reference	The receipt the beneficiary sees. Assigned by the bank, it is null until the transfer completes, and it is the only transfer identifier in the statement
reference	The payment concept you sent when paying out. null if you sent none. Useful to tie the row to your payroll

Reconciling a day

1. Request the whole day, filtering by settled.

2. Add up payout_amount and fee_amount for all rows, in minor units and with integers; never with floating point.

3. Follow next_cursor while has_more is true. The cursor is a keyset: there are no duplicated or skipped rows even if you keep paying out.

4. Compare with your outstanding debt, GET /v1/treasury/position?asset=BS.

Total settled and fees for one day

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

while :; do
  RESP=$(curl -s "$BASE/v1/payments?from=$DAY&to=$DAY&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 payouts · delivered $TOTAL · fees $FEES (minor units)"

What counts for the day and what does not

State at cut-off	Counts?	Why
settled	Yes	The money went out
failed	No	The entry was already reversed: you owe nothing, and fee_amount is 0
submitted	No	It moves to the day it settles
unknown	No	It moves to the day it is resolved
reversed	Not on the day it was sent	The bank returned it; the funds went back to your balance

If your count does not reconcile, first check how you mark payments

The usual mismatch is marking the payout as paid when POST /payouts responds. The usual response is submitted, not settled. Mark it with the payment.settled webhook. See tracking.

Other questions the statement answers

# Everything we have paid to one person
curl -s "$BASE/v1/payments?beneficiaryId=8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2&limit=100" \
  -H "x-api-key: $KEY"

# What failed this month, to retry it
curl -s "$BASE/v1/payments?from=2026-08-01&to=2026-08-31&status=failed&limit=100" \
  -H "x-api-key: $KEY"

# What is still in doubt
curl -s "$BASE/v1/payments?status=unknown&limit=100" -H "x-api-key: $KEY"

For the detail of a row —including the transition history— GET /v1/payments/{id}. See tracking.