Idempotency

Network calls fail in ambiguous ways: a request times out after the server processed it but before the response reached you, and you can't tell whether it succeeded. Idempotency is what lets you retry safely in that situation — a repeated request produces the same result as the first, instead of a duplicate.

The Remittances API does not use an Idempotency-Key header. Instead, every create endpoint is idempotent on the externalId you supply — the same convention everywhere, so a retry after a timeout is safe as long as you send a stable externalId. This page is the single reference for which operations are safe to repeat and how.

The one rule: send your own unique externalId on every create (sender, beneficiary, transaction). It's the idempotency key — the thing that turns an ambiguous retry into a safe one.

Person Creation — Idempotent on externalId

Creating a sender or beneficiary is idempotent when you supply an externalId:

• POST /organizations/{tenant}/v2/senders
• POST /organizations/{tenant}/v2/beneficiaries
• POST /organizations/{tenant}/v2/people (deprecated)

If a person with the same externalId already exists in your tenant, the create returns the existing person with HTTP 200 — no duplicate is created. A genuinely new person returns 201.

First call  → 201 Created   (new person, id abc-123)
Retry       → 200 OK        (same person abc-123 returned, nothing new created)

Always send your own externalId on person creation. It's your retry safety net: without it, a retried create after a network blip produces a second person record for the same individual.

Account Deactivation — Idempotent

Deactivating a funding account or a recipient account is safe to repeat:

• DELETE /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/{fundingAccountId}
• DELETE /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}

Deactivating an already-inactive account succeeds and returns the account unchanged (isActive: false). There's no error on the second call and no additional state change.

Transaction Creation — Idempotent on externalId

POST /organizations/{tenant}/fx/transactions is idempotent when you supply an externalId. A repeat with the same externalId returns the existing transaction with HTTP 200 and starts no second payout; a genuinely new transaction returns 202 Accepted.

First call  → 202 Accepted   (new transaction, id tx-abc)
Retry       → 200 OK         (same transaction tx-abc returned, no second payout)

Because money moves here, this is the most important place to get retries right:

• Always send a unique externalId per intended transaction. It is the idempotency key — without it, a retried create after a network blip starts a second payout.
• Reuse the same externalId when you retry the same intended transaction. The matching is scoped per tenant and backed by a uniqueness constraint, so even two concurrent retries resolve to one transaction.
• A timeout is now safe to retry as long as you send the same externalId — the retry either creates the transaction (if the first never landed) or returns the one already created.

Treat 200 on this endpoint as "already created, here it is" and 202 as "newly accepted" — both are success. Poll the returned transaction's status either way.

Quotes

Quotes are not idempotent and aren't meant to be — each POST /payout/quotes mints a fresh quote with its own id and expiry. There's nothing to deduplicate: request a new quote whenever you need one, and never cache or reuse a quoteId across transactions. See Quotes (FX).

Reads

All GET endpoints are naturally idempotent and side-effect-free — retry them freely.

Summary

The Wallet API is a separate product and does use an explicit Idempotency-Key header on its write endpoints — see the Wallet API Reference. The guidance on this page is for the Remittances API only.