Skip to main content

​
Reconciliation

Reconciliation is how you prove that customer payments, PayChain invoice records, withdrawals, and treasury balances agree.
Source of truth: Invoice state is the source of truth for customer payment fulfillment. Balances and transactions support treasury and accounting reconciliation.

​
What to reconcile

SurfaceUse it forDo not use it for
InvoicesCustomer payment state and order fulfillment.Treasury availability by itself.
Invoice paymentsSettlement evidence and paid amount breakdown.Independent fulfillment without invoice status.
TransactionsOn-chain activity history.Customer payment truth by itself.
BalancesTreasury availability and asset holdings.Determining whether an invoice should be fulfilled.
WithdrawalsOutbound payout lifecycle.Invoice revenue recognition by itself.
WebhooksReal-time state changes.Final truth without fetching the canonical record.
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.
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.

​
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

CaseWhat to do
OverpaymentFulfill according to your policy and reconcile the excess amount.
UnderpaymentDo not fulfill unless your business policy explicitly tolerates it.
Wrong token or networkDo not treat it as a valid invoice payment. Contact support if recovery is needed.
Auto-detected dustIgnore for revenue and fulfillment.
Gas-blocked payoutPayment can be valid while outbound movement is paused. Top up gas credits.
Duplicate webhookIgnore if the event ID or resource transition was already processed.
Direct treasury depositReconcile as treasury movement, not invoice fulfillment.
Payout route partial failureKeep invoice settlement separate from payout completion; investigate failed legs.
Retry after timeoutFetch by idempotency key or resource ID before creating a duplicate.

​
REST examples

​
Fetch invoice after webhook

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

​
List transactions for a period

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

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

​
List withdrawals

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.