Skip to main content
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.
Current V1 backend support for Idempotency-Key applies to bank transfer creation only.

​
How idempotency works

When creating a bank transfer, include an Idempotency-Key header in your request.
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. Use a unique UUID for every new transaction request.
Do not reuse one idempotency key for different transactions. Reuse the same key only when retrying the exact same request.

​
Example request

​
When to use idempotency

Create transfer

Supported when you create a bank transfer that may be retried.

Verify transfer status

Check the final state of a transfer after creating it.

​
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

1

Create a unique key

Generate a new UUID before sending a create request.
2

Send the request

Include the UUID in the Idempotency-Key header.
3

Retry with the same key

If the first request times out, retry the same request with the same idempotency key.
4

Use the original response

Pasteaza returns the original response when the duplicate request is detected.