> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infinityapp.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconciliation

> Match every payout and deposit to your own records using references, metadata, events and date-filtered lists.

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:

```bash theme={null}
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

1. List the payouts paid in the period:
   ```bash theme={null}
   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"
   ```
2. Repeat for `failed` and `returned`, and list `GET /deposits` for the same dates.
3. Match each object to your records by `reference`.
4. 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:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.