Skip to main content
Pasteaza supports idempotent requests so you can safely retry sensitive API calls without creating duplicate transactions. 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.
Use idempotency keys for requests that create or move money, such as collections and disbursements.

​
How idempotency works

For sensitive actions, include an Idempotency-Key header in your request. 
Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388
When Pasteaza receives another request with the same idempotency key, it returns the original response instead of creating a duplicate transaction. Use a unique UUID for every new transaction request. 
8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388
Do not reuse one idempotency key for different transactions. Reuse the same key only when retrying the exact same request.

​
Example request

POST /v1/collections 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

Collections

Recommended when you create a collection request that may be retried.

Disbursements

Required when you create a disbursement request that sends funds.

​
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:
  • Creating the same collection twice
  • Sending the same disbursement 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.