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

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 platform fee.
  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 platform-fee payout transaction hash.
If one leg fails, keep the invoice marked as paid in your order ledger, but mark the payout route as needing review.

​
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

​
REST examples

​
Fetch invoice after webhook

​
List transactions for a period

​
List balances

​
List withdrawals

​
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.