Idempotency & references

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.
• A retry must match the original. Sending a different body (amount, currency, recipient or payer) with the same reference returns 409 duplicate, with the original’s id in details.existingId. Nothing new is created.
• Use it for lookups in webhook handlers too: data.externalReference is on every payout, collection, and order event.

​

Request ids