Errors and idempotency

Follow these rules across your whole integration. They prevent duplicate resources, brittle error handling, and data that drifts out of sync.

​

Idempotency and retries

Use a stable external_reference from your own system for every profile and account, and use it to match records. Process webhooks idempotently too. Use the event id to skip events you’ve already handled.

​

Handle errors

Branch your code on the stable error reason, not the human-readable message. The message is for people and can change at any time.

​

Treat changes as asynchronous

Assume creation and status-changing operations finish asynchronously, unless the endpoint explicitly says otherwise. Wait for a webhook or read the resource before treating a change as done. When ordering matters, read the current state of the resource instead of relying on the order events arrive in.

​

Represent amounts exactly

Many financial and token amounts are strings paired with a decimals value. Keep them as strings or use a decimal library. Don’t convert them to floating-point numbers, which lose precision.

​

Keep secrets out of logs

Never log credentials, access tokens, or sensitive card data. See Handle sensitive card data for the full list of safeguards.

​

Before going live

Test the complete lifecycle in sandbox, from onboarding to card transactions and reconciliation, before you request production access. See Sandbox vs Production.