● Balances and reconciliation · /v1

Balances and reconciliation

Balances, settlement batches and bulk exports, so your ERP and finance systems can pull the data themselves instead of someone exporting it from the console.

Get balances

GET /v1/finance/balances

Returned per provider account, never merged. Merging hides a shortfall on one provider, and that is where reconciliation breaks first.

available is settleable, pending is captured but not yet due, reserved is held against disputes and reserves.

Query parameters

currency string

Response 200

currency string
currency_exponent integer
available integer Settleable amount
pending integer Captured but not yet due for settlement
reserved integer Held against disputes and reserves
connector_code string Balances are kept per provider account and never merged — merging hides a shortfall on one provider
as_of string<date-time>
Request
curl -X GET https://api.baton.example/v1/finance/balances \
  -H "Authorization: Bearer sk_live_xxx"
Response · 200
[
  {
    "currency": "USD",
    "currency_exponent": 2,
    "available": 1842300,
    "pending": 390500,
    "reserved": 24000,
    "connector_code": "adyen",
    "as_of": "2026-11-16T09:00:00Z"
  }
]

List settlement batches

GET /v1/finance/settlements

net comes from the provider's settlement file, not from our own fee calculation. status=mismatched means our ledger and the provider's file disagree and it is queued for manual review.

Query parameters

connector_code string
status string
settled_from string<date-time>
settled_to string<date-time>
cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└uid string
└connector_code string
└currency string
└currency_exponent integer
└gross integer Gross transaction amount
└fee integer Provider fees, cross-border fees included
└net integer Amount actually received, taken from the provider's settlement file
└txn_count integer
└status pending | settled | reconciled | mismatched mismatched means our ledger and the provider's file disagree; it is already queued for manual review
└settled_at string<date-time>
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/finance/settlements \
  -H "Authorization: Bearer sk_live_xxx"

Settlement line items

GET /v1/finance/settlements/{uid}/transactions

Every entry in a batch — refunds, chargebacks and adjustments included. Book your ledger from this, not from payments.

Path parameters

uidrequired string

Query parameters

cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└payment_uid string
└refund_uid string
└type payment | refund | chargeback | fee | adjustment
└gross integer
└fee integer
└net integer
└provider_txn_id string
└occurred_at string<date-time>
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/finance/settlements/{uid}/transactions \
  -H "Authorization: Bearer sk_live_xxx"

Create an export job

POST /v1/finance/exports

Use this for bulk extraction rather than deep pagination: page ten thousand of a transactions table will take the database down, and we reject cursors beyond a certain depth outright.

When the job finishes you get a webhook, or you can poll.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

typerequired payments | refunds | settlements | disputes
format csv | jsonl
created_fromrequired string<date-time>
created_torequired string<date-time> At most 31 days per export

Response 202

uid string
type payments | refunds | settlements | disputes
status queued | running | ready | failed | expired
format csv | jsonl
row_count integer
download_url string Returned only when ready. The signed link is valid for 15 minutes — do not store it
expires_at string<date-time>
created_at string<date-time>

Errors

400Invalid parameters
Request
curl -X POST https://api.baton.example/v1/finance/exports \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "payments",
  "format": "csv",
  "created_from": "2026-11-01T00:00:00Z",
  "created_to": "2026-11-30T23:59:59Z"
}'

Retrieve an export job

GET /v1/finance/exports/{uid}

When status=ready a download_url is returned, signed and valid for 15 minutes. Do not store it — it expires; just query again.

Path parameters

uidrequired string

Response 200

uid string
type payments | refunds | settlements | disputes
status queued | running | ready | failed | expired
format csv | jsonl
row_count integer
download_url string Returned only when ready. The signed link is valid for 15 minutes — do not store it
expires_at string<date-time>
created_at string<date-time>

Errors

404The object does not exist, or belongs to another environment or merchant
Request
curl -X GET https://api.baton.example/v1/finance/exports/{uid} \
  -H "Authorization: Bearer sk_live_xxx"