API ReferenceIntegrationsKnowledge Base

Payout Idempotency

Idempotency allows you to safely retry or send the same request multiple times without fear of performing the same action more than once.

For example, when you try to create a payout, in some cases due to network downtimes, you may not get a response from our servers. As a consequence, you will not be aware of the payout entity id or its state.

In such cases, you can safely retry the transaction using the same idempotency key without risk of double-payout or duplication.

If a duplicate request is found with the same idempotency key, we return the latest state of the payout entity that was created as part of the first transaction.

Make a Request Idempotent#

To make a request idempotent, add the header X-Payout-Idempotency to the request and pass an idempotency key against it.

An idempotency key is a unique value generated by you. Our servers use this key to recognize subsequent retries of the same request.

The idempotency key (4-36 characters) can only contain alphabets, numbers, hyphens, underscores and space. For example, 53cda91c-8f81-4e77-bbb9-7388f4ac6bf4. We recommend you generate the key using a version 4 (random) UUID generator.

Only Create Payout API Supported:
Currently, idempotency is supported only on the Create Payout API and the Composite APIs.

Note:

  • When retrying a request, the request body must be the same as the first request for idempotency to work. A different payload will be rejected as a BAD_REQUEST.
  • The idempotency key in retries must be the same as the original request.
  • Use unique idempotency keys for each unique request.

Key Validity#

The idempotency key is valid for 7 days from the first submission of the request.

This means you can use the idempotency key to safely retry a request for 7 days without fear of performing the same action twice.

×