Skip to main content
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.

​
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.