Error handling

Pass onError and show the message. Most failures are recoverable by the customer, and silence just makes them try again blindly.

onError={(error) => {
  console.error('[stablezact]', error);
  showBanner(String(error));
}}

Common failures

Wrong network. The wallet is on a different chain from the payment. The SDK prompts to switch; some wallets refuse programmatic switching and the customer must change it themselves.

Not enough gas. The customer holds the stablecoin but no native currency to pay for the transfer. Caught before submission by the balance check.

Rejected in the wallet. The customer declined the signature. Not an error to apologise for. Let them try again.

Payment expired. Payments do not stay open indefinitely. Create a new one.

Chain not configured. Creating a payment on a chain with no settlement wallet is rejected, naming the chain. Fix this in your merchant settings, not in code.

What not to do

Do not retry a payment creation without an idempotency key. Send an Idempotency-Key header, or at least the same orderId, so the server can tell a retry from a second purchase. See Retrying safely.

Do not treat a 500 from a payment read as an outage before checking the ID. An unknown payment ID currently returns 500 rather than 404. See Errors.