> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.chipper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
# 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.