Idempotency & references

externalReference is how you make money-moving calls safe to retry.

Networks fail after the request lands. Without idempotency, a retry sends money twice.

Every money-moving create call — payouts, collections, orders, conversions, simulations — takes an externalReference: a string you choose, unique within your organization. It does two jobs:

1. Idempotency. Retrying with the same externalReference never creates a second resource. You get the original back with status 200 instead of 201, and its state reflects whatever has happened since.
2. Lookup. GET /v1/payouts/by-reference/{externalReference} (and the same for orders and collections) finds the resource by your id — so you can reconcile even if you never stored ours.

# first call → 201, payout created
POST /v1/payouts { "externalReference": "inv-1042", ... }

# same call again (timeout, crash, double-click) → 200, same payout, no new money moved
POST /v1/payouts { "externalReference": "inv-1042", ... }

Rules

• Uniqueness is per organization and permanent — an externalReference can’t be reused for a different payment later. Derive it from something in your system that’s already unique: an invoice number, an order id, a ledger entry id.
• The replay is keyed on the reference alone. Sending a different body with the same reference returns the original, not an error — so don’t reuse references across distinct intents.
• Use it for lookups in webhook handlers too: data.externalReference is on every payout, collection, and order event.

Request ids

Separately, every response carries an x-request-id header (also in error bodies as requestId). It identifies the HTTP request, not the payment. Log it; quote it to support.