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

# Idempotency

> Prevent duplicate collections and disbursements when retrying requests.

Pasteaza supports idempotent transfer creation so you can safely retry payout requests without creating duplicate transfers.

Idempotency is useful when your server sends a request but does not receive a response because of a timeout, network issue, or temporary server error.

<Info>
  Current V1 backend support for `Idempotency-Key` applies to bank transfer creation only.
</Info>

## How idempotency works

When creating a bank transfer, include an `Idempotency-Key` header in your request.

```http theme={null}
Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388
```

When Pasteaza receives another transfer request from the same merchant and environment with the same idempotency key, it returns the original transfer response instead of creating a duplicate transfer.

## Recommended key format

Use a unique UUID for every new transaction request.

```text theme={null}
8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388
```

<Warning>
  Do not reuse one idempotency key for different transactions. Reuse the same key only when retrying the exact same request.
</Warning>

## Example request

```http theme={null}
POST /v1/disbursements/bank-transfer HTTP/1.1
Host: api.oyapasteaza.com
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388
```

## When to use idempotency

<CardGroup cols={2}>
  <Card title="Create transfer" icon="arrow-up-from-line" href="/disbursements/bank-transfer/create-transfer">
    Supported when you create a bank transfer that may be retried.
  </Card>

  <Card title="Verify transfer status" icon="circle-check" href="/disbursements/bank-transfer/verify-transfer-status">
    Check the final state of a transfer after creating it.
  </Card>
</CardGroup>

## Important rules

* Generate a new idempotency key for every new transaction.
* Reuse the same idempotency key only when retrying the same request.
* Do not reuse one idempotency key across different customers, payments, or payouts.
* Store the idempotency key with your internal transaction record.
* Use UUIDs or another high-entropy unique value.

## Duplicate prevention

If Pasteaza detects a duplicate request, it returns the original transaction response.

This helps prevent issues such as:

* Sending the same bank transfer twice
* Debiting a balance more than once
* Creating confusing webhook events

## Retry flow

<Steps>
  <Step title="Create a unique key">
    Generate a new UUID before sending a create request.
  </Step>

  <Step title="Send the request">
    Include the UUID in the `Idempotency-Key` header.
  </Step>

  <Step title="Retry with the same key">
    If the first request times out, retry the same request with the same idempotency key.
  </Step>

  <Step title="Use the original response">
    Pasteaza returns the original response when the duplicate request is detected.
  </Step>
</Steps>