Production operations

Production payment UX needs more than a successful pay() response. Build every fulfillment decision so it can survive timeouts, duplicated requests, delayed confirmations, and missed webhooks.

Evidence hierarchy

Evidence	Use it for	Do not use it for
Payer client result	Immediate payer UX and evidence upload	Irreversible fulfillment by itself
Notify event	Wake a backend verifier quickly	Financial finality
Signed receipt	Authenticate gateway output and bind context	Replace chain verification
Chain status	Confirm transfer and finality	Merchant order semantics
Merchant database	Idempotent fulfillment and business policy	Declare a transfer without evidence

Handle a lost success response

If the facilitator broadcast a transaction but the client lost the response, use recoverSettlement. Recovery verifies chain evidence and reconstructs a receipt where possible; it never calls /settle again.

TypeScript
1import { recoverSettlement } from 'x402-paysdk/pay';23const recovered = await recoverSettlement({4  gateway: 'https://pay.example.com',5  refId,6  paymentPayload,7  txHash,8  signedOffer9});1011if (recovered.recovered) {12  await submitEvidence(recovered.txHash, recovered.signedReceipt, recovered.receipt);13}

Persist the original encoded payment payload only for the shortest operational window required by recovery. It is replayable sensitive material and must never enter logs.

Reconcile from chain history

Run reconciliation on a bounded block range and compare chain transfers with your archived receipts.

TypeScript
1import { reconcile } from 'x402-paysdk/merchant';23const report = await reconcile(merchant, {4  payTo,5  fromBlock: lastReconciledBlock,6  limit: 200,7  receipts: archivedPaymentReceipts,8  refundReceipts: archivedRefundReceipts,9  minConfirmations: 3,10  verifyChain: true11});1213for (const anomaly of report.anomalies) {14  await incidentQueue.enqueue(anomaly);15}

Advance your checkpoint to report.lastBlock only after the report and business updates are durably stored.

Rotate credentials

Use independent rotation procedures for API keys and notify keys. Maintain an overlap key ring for notify delivery while both ids can arrive, then explicitly revoke the old key.

TypeScript
1import { rotateMerchantKey, revokeOldMerchantKey } from 'x402-paysdk/merchant';23const rotated = await rotateMerchantKey(merchant, { keyType: 'notifyHmacKey' });4await secrets.storeNotifyKey(rotated.keyId!, rotated.newKey);56// After the configured overlap window:7await revokeOldMerchantKey(merchant, { keyType: 'notifyHmacKey' });

Operational gates

• Keep the merchant client in backend-only modules.
• Use shared atomic nonce storage for notify replay protection.
• Bound /txs queries, RPC timeouts, response sizes, and retry counts.
• Keep paymentId stable only for retries of the same exact context.
• Retry fulfillment writes independently from settlement.
• Archive the receipt pair and tx hash with the merchant order.
• Alert on transfers without receipts, receipts without transfers, context mismatches, and refund cumulative mismatches.
• Keep order mode disabled unless you need gateway-side order authorization and have transactional storage.

Incident rule

When evidence disagrees, stop fulfillment and preserve the original ref snapshot, receipt pair, tx hash, expected order context, and bounded chain response. Never “fix” the mismatch by accepting notify data or issuing a direct wallet transfer.