# Reconciliation

Reconciliation is how you prove that customer payments, PayChain invoice records, withdrawals, and treasury balances agree.

{% hint style="info" %}
**Source of truth:** Invoice state is the source of truth for customer payment fulfillment. Balances and transactions support treasury and accounting reconciliation.
{% endhint %}

### What to reconcile

| Surface          | Use it for                                     | Do not use it for                                   |
| ---------------- | ---------------------------------------------- | --------------------------------------------------- |
| Invoices         | Customer payment state and order fulfillment.  | Treasury availability by itself.                    |
| Invoice payments | Settlement evidence and paid amount breakdown. | Independent fulfillment without invoice status.     |
| Transactions     | On-chain activity history.                     | Customer payment truth by itself.                   |
| Balances         | Treasury availability and asset holdings.      | Determining whether an invoice should be fulfilled. |
| Withdrawals      | Outbound payout lifecycle.                     | Invoice revenue recognition by itself.              |
| Webhooks         | Real-time state changes.                       | Final truth without fetching the canonical record.  |

### Recommended reconciliation keys

Store these together:

* PayChain business ID.
* PayChain customer ID.
* PayChain invoice ID.
* Your order ID or customer reference.
* Token, chain, and network.
* Expected amount.
* Settled amount.
* Transaction hash when available.
* Webhook event ID.
* Withdrawal ID for payout movement.

### Daily reconciliation flow

1. List paid and overpaid invoices for the period.
2. Match each invoice to your order or customer ledger.
3. Compare settled amounts and expected amounts.
4. List withdrawals for the same period.
5. Match withdrawal IDs to payout routes, dynamic recipients, or manual payouts.
6. Compare balances by token and network.
7. Investigate unmatched transactions, underpayments, overpayments, and failed withdrawals.

### Worked examples

#### Fixed invoice reconciliation

Your order system expects `order_123` to be paid for `100 USDC` on `base-mainnet`.

1. Store `order_123` in invoice metadata when creating the invoice.
2. Receive `invoice.paid`.
3. Verify the webhook signature.
4. Fetch the invoice by ID.
5. Confirm:
   * `status` is `paid` or `overpaid`.
   * `token`, `chain`, and `networkId` match the order.
   * settled amount is enough for your policy.
   * metadata contains `order_123`.
6. Mark the order paid once.

{% hint style="warning" %}
**Wrong-asset note:** If the transaction history shows activity but the invoice is not paid, do not fulfill the order. The customer may have sent the wrong token, wrong network, or a non-qualifying amount.
{% endhint %}

#### Payout route reconciliation

A marketplace invoice is split 80% to seller and 20% to operator.

1. Reconcile the invoice first.
2. Fetch the invoice payout routing summary.
3. Confirm all route legs were created.
4. Match each leg to its withdrawal ID.
5. Confirm each withdrawal reaches `completed`.
6. Record the seller payout transaction hash and the operator payout transaction hash.

If one leg fails, keep the invoice marked as paid in your order ledger, but mark the payout route as needing operator attention.

#### Dynamic recipient reconciliation

An off-ramp order sends funds to a receiver that changes per order.

1. Store your off-ramp order ID in invoice metadata.
2. Store the receiver address and percentage split in your own order system.
3. After invoice settlement, fetch routing or withdrawal records.
4. Confirm the destination address matches your approved receiver.
5. Confirm the withdrawal status before notifying the receiver or completing the fiat leg.

#### Direct treasury deposit reconciliation

Direct treasury deposits can increase business balances and treasury analytics, but they do not prove that a customer invoice was paid.

Use direct treasury deposit data for:

* Treasury availability.
* Portfolio balance.
* Operational funding.
* Finance-side reconciliation.

Do not use direct treasury deposits for:

* Order fulfillment.
* Customer crediting.
* Invoice status overrides.
* Payout route triggering.

### Handling edge cases

| Case                         | What to do                                                                         |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| Overpayment                  | Fulfill according to your policy and reconcile the excess amount.                  |
| Underpayment                 | Do not fulfill unless your business policy explicitly tolerates it.                |
| Wrong token or network       | Do not treat it as a valid invoice payment. Contact support if recovery is needed. |
| Auto-detected dust           | Ignore for revenue and fulfillment.                                                |
| Gas-blocked payout           | Payment can be valid while outbound movement is paused. Top up gas credits.        |
| Duplicate webhook            | Ignore if the event ID or resource transition was already processed.               |
| Direct treasury deposit      | Reconcile as treasury movement, not invoice fulfillment.                           |
| Payout route partial failure | Keep invoice settlement separate from payout completion; investigate failed legs.  |
| Retry after timeout          | Fetch by idempotency key or resource ID before creating a duplicate.               |

### REST examples

#### Fetch invoice after webhook

```bash
curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/invoices/inv_123" \
  -H "x-api-key: $PAYCHAIN_API_KEY"
```

#### List transactions for a period

```bash
curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/transactions?startDate=2026-05-01&endDate=2026-05-20" \
  -H "x-api-key: $PAYCHAIN_API_KEY"
```

#### List balances

```bash
curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/balances" \
  -H "x-api-key: $PAYCHAIN_API_KEY"
```

#### List withdrawals

```bash
curl "$PAYCHAIN_API_URL/businesses/$PAYCHAIN_BUSINESS_ID/withdrawals?status=completed" \
  -H "x-api-key: $PAYCHAIN_API_KEY"
```

### Accounting notes

* Net settled revenue should use the merchant net amount after PayChain fees where available.
* Platform fees and network/gas behavior should be tracked separately from customer gross payment amount.
* Direct treasury deposits can be useful for treasury analytics, but explicit invoice state should remain fulfillment truth.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/reconciliation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.