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

# Reconcile Payouts

> Match each payout to the transactions it carries, and read the balances behind them

A payout is money Quidkey sends to the merchant's own bank account, carrying a batch of transactions. Payouts send no webhook events, so poll them.

| # | Step | Who |
| - | - | - |
| 1 | List the merchant's payouts | API, polling |
| 2 | List the transactions a payout carries | API |
| 3 | Read balances | API |

## 1. List Payouts

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/payouts' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Payouts come newest first. Each one has:

| Field | Meaning |
| - | - |
| `status` | `pending`, created and not yet sent. `processing`, sending has started. `sent`, the provider accepted the transfer. |
| `amount` | What the merchant receives: `net_amount` minus `refund_retained_amount`. |
| `gross_amount`, `fee_amount`, `net_amount` | The transactions before fees, Quidkey's fees, and what's left after them. |
| `refund_retained_amount` | Kept back in the merchant's refund account, to fund refunds. |
| `bank_reference` | The reference the transfer is sent under. Banks don't always show it. |
| `sent_at` | When the provider accepted the transfer. Not when it arrived. |

A payout that fails while being sent leaves the list, and reading it answers 404, until Quidkey staff resolve it. It then comes back under the same `id`. Part or all of its money may have moved by then.

## 2. List a Payout's Transactions

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/transactions?payout_id=po_1' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The payout's `transactions` link is the same list. Each transaction's `payout_amount` is what it adds to the payout, after fees and any conversion, and `exchange_rate` explains the conversion. The amounts are authoritative: don't recompute them from the rate.

A transaction's `payout` links back to the payout that carries it, and is `null` until it's batched.

### Export a Payout's Transactions

For an accounting tool, ask for the same list as a file:

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/transactions?payout_id=po_1' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: text/csv' \
  -o po_1.csv
```

The file holds every transaction the payout carries, one per row, with no paging. Its amounts are decimals beside a currency column, which a tool sums as written. `Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` answers an Excel workbook instead. [Transaction export](https://docs.quidkey.com/api-v1/reference/transaction-export.md) lists the columns, and [Files](https://docs.quidkey.com/api-v1/standards/collections.md#files) the rules, among them a limit of 10,000 rows.

## 3. Read Balances

A merchant's virtual accounts, which Quidkey holds for it, each have a balance. To read them:

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/bank-accounts?account_type=virtual&status=active&include=balance' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Each account's `balance` is in `entities`, with the `amount` its provider reports, and `retrieved_at`. An `amount` of `null` means Quidkey couldn't get a figure, and never means zero. Every read asks the provider, so don't poll balances tightly.

To total a currency, add `currency=EUR` and sum each balance on the page. A credential without permission to read balances gets the accounts, with each balance in `not_included`.

Test payment transactions don't appear in payouts or balances: those show live money only.


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