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

# Idempotency

> How to retry requests safely without creating duplicate payments or disbursements.

When a request times out, you don't know whether it reached Spotflow, so you need to be able to retry without charging a customer or paying someone twice.

All `POST` requests that create or initiate transactions take an idempotency key in the `reference` field of the request body. If you send two requests with the same `reference`, Spotflow processes it once and returns the same response for the second request.

```bash Idempotent request theme={null}
curl -X POST https://api.spotflow.co/api/v1/payments/initialize \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1001",
    "amount": 5.00,
    "currency": "GHS",
    "customer": { "email": "john@example.com" }
  }'
```

## Rules

| Rule | Detail |
| - | - |
| Where | The `reference` field on [Initialize Payment](https://docs.spotflow.one/api-reference/payments/initialize-collection.md) and [Create Disbursement](https://docs.spotflow.one/api-reference/transfer-api/create-single-transfer.md) |
| Scope | References must be unique per transaction type. Payment references are separate from disbursement references |
| Window | Duplicates are detected for 24 hours |
| After a 5xx | It's safe to retry with the same reference |
| After a success | Retrying with the same reference returns the original response, without creating a duplicate |

## Retrying safely

**1. Create the reference once**

Generate it from your own record, for example your order ID, and save it **before** you call the API.

**2. Check before you retry**

If a request fails or times out, check whether it actually succeeded first. For payments, call [Verify Payment](https://docs.spotflow.one/api-reference/payments/verify-collection.md) with your reference. For disbursements, call [Get Transfer by Reference](https://docs.spotflow.one/api-reference/transfer-api/transfer-by-reference.md).

**3. Retry with the same reference**

If the transaction doesn't exist, send the exact same request again with the same reference.

> [!WARNING]
>
> Never generate a new `reference` to retry a request whose outcome you don't know. That's how a customer gets charged twice or a payout goes out twice.

## Failed payments

A `FAILED` payment can't be retried with the same reference. Create a new payment with a new reference. See [Payment lifecycle](https://docs.spotflow.one/developer-resources/payment-states.md).

## Webhooks

Each webhook includes a unique `webhook-id` header. Store it and ignore events you've already processed, because the same event can be delivered more than once. See [Webhooks](https://docs.spotflow.one/developer-resources/webhooks/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.