Reconcile stablecoin payments with the right source records.

Set externalReference to the merchant order or receivable identifier when creating the checkout session or invoice. Store the returned invoice ID and checkout ID beside it. When a webhook arrives, use those same values to find the record before applying any fulfillment change.

Do not rely on an email address, wallet address, amount, or transaction hash as the only join key. Different customers can pay the same amount, a wallet can pay several orders, and routed payments can expose more than one transaction hash.

The customer order total and merchant wallet receipt are related but not identical. Payclave charges a 0.7% platform fee on each completed live payment. The customer pays amountDue, Payclave records platformFee, and the merchant receives netAmount or merchantAmountSettled.

Use amountDue when deciding whether the customer satisfied the order. Use platformFee and netAmount when matching the Payclave record to the merchant wallet and accounting entry. Do not create a fictional Payclave balance to explain the difference.

• Order and fulfillment basis: amountDue.
• Payclave revenue line: platformFee.
• Merchant wallet expectation: netAmount or merchantAmountSettled.
• Network cost: separate customer-side cost when the route requires it.

Invoice status describes payment verification. Collection state describes the commercial receivable. Payment status describes an individual attempt. Combining those fields into one status hides important cases such as a partially paid invoice with one failed attempt and one verified underpayment.

A later verified payment can complete an underpaid invoice. An overpayment can satisfy the invoice while leaving an exception for review. A duplicate transaction must remain visible as evidence without counting twice toward the amount paid.

• Invoice status includes pending, processing, paid, underpaid, overpaid, expired, failed, and cancelled.
• Collection state includes draft, open, past_due, partially_paid, paid, void, and uncollectible.
• Payment status includes detected, validating, confirmed, failed, duplicate, underpaid, and overpaid.

For each completed payment, match the mode, chain ID, settlement token contract, settlement wallet snapshot, net amount, settlement transaction hash, confirmation time, and invoice ID. Keep test and live records in separate reconciliation runs.

A routed payment may have a source transaction and a separate settlement transaction. The source transaction explains what the customer sent. The settlement transaction is the evidence used to match the merchant's Polygon USDC or USDT receipt.

An exception report should state what happened and what the merchant can do next. Underpayment can create a new exact-remainder checkout. Overpayment needs review. A late payment remains recorded. A failed or duplicate attempt must not trigger fulfillment.

Refunds are merchant-initiated wallet transfers because Payclave never controls settlement funds. Record the external refund reference against the invoice, but do not describe that record as Payclave moving or returning money.