Reconciliation

Reconciliation is the process of proving that every payment your system intended matches what actually happened to the money. The API supports it with three tools: your own identifiers on every object, a complete snapshot in every event, and lists you can filter by date.

Tag objects with your identifiers

Set reference and metadata when you create payouts, at the batch level, the item level or both:

curl "$BASE/payouts" \
  -H "Authorization: Bearer $INFINITY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-1042" \
  -d '{
    "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
    "reference": "run-2026-10",
    "items": [
      {
        "payee_id": "payee_c8pnahcrxqzd3z8d",
        "amount": "500.00",
        "currency": "eur",
        "reference": "inv-1042",
        "metadata": { "ledger_entry": "LE-88231", "cost_center": "design" }
      }
    ]
  }'

Both fields are returned on every read and every event, so you can match an Infinity object to your record without a lookup table. Store Infinity’s IDs alongside your own as well; they’re the fastest way to retrieve an object later.

Record what was charged

Book these payout fields in your ledger:

Field	Ledger treatment
`debit_amount`, `debit_currency`	The total debited from the wallet, fee included.
`fee`	Infinity’s fee, part of `debit_amount`.
`payee_amount`, `payee_currency`	The amount delivered. Final once the payout is `paid`.
`rate`	The conversion rate applied.
`wallet_id`, `batch_id`	The wallet that paid, and the run the payout belongs to.

For INR payouts, rate and payee_amount are populated at settlement; read them from the payout.paid event.

Follow funds through events

Event	Effect on funds
`deposit.created`	Funds were credited to a wallet.
`payout.created`	Funds were reserved for a payout.
`payout.paid`	Funds were delivered to the payee’s bank.
`payout.failed`	The payout wasn’t delivered; its funds are released back to the wallet.
`payout.returned`	A delivered payout came back from the payee’s bank; its funds are credited back to the wallet.
`payout.canceled`, `payout.expired`	A payout on hold was released before it was sent.

Each event carries the object as it was at that moment, including your reference and metadata. Delivery is at-least-once and unordered, so deduplicate on the event ID and rely on the object’s status.

Close a period

List the payouts paid in the period:

curl "$BASE/payouts?status=paid&created[gte]=2026-10-01T00:00:00Z&created[lte]=2026-10-31T23:59:59Z&limit=100" \
  -H "Authorization: Bearer $INFINITY_KEY"

Repeat for failed and returned, and list GET /deposits for the same dates.
Match each object to your records by reference.
Check that, per wallet, deposits minus the debit_amount of sent payouts, plus funds returned, explain the change in the wallet’s total.

created filters on creation time. A payout created on 31 October may be paid on 1 November, so at period boundaries check status and updated_at as well.

Recover missed events

Events are retained for 30 days. After downtime, list the events since the start of the outage and process the ones you haven’t recorded:

curl "$BASE/events?created[gte]=2026-10-25T00:00:00Z&limit=100" -H "Authorization: Bearer $INFINITY_KEY"

Get started

Concepts

Build reliably

Tag objects with your identifiers

Record what was charged

Follow funds through events

Close a period

Recover missed events