Idempotency
How Idempotency Works#
Idempotency is an essential security mechanism in our API, designed to ensure that an operation is executed only once, even if the request is sent multiple times. This prevents duplicate processing of events (such as payments or refunds), ensuring data consistency and integrity across all transactions.
Using x-Idempotency-Key#
To enable idempotency, you must include the x-Idempotency-Key header in your payment and refund requests.
Format: The value of x-Idempotency-Key must be a unique string for each operation, with a defined size limit (usually up to 255 characters, but check the specific API documentation for the exact limit).
API Behavior#
The x-Idempotency-Key acts as a unique identifier for each operation attempt.
First Request:
If the x-Idempotency-Key sent has not been used before, the API will process the request normally.
Repeated Request (Key Already Processed):
If you resend a request with an x-Idempotency-Key that has already been successfully processed, the API will not execute the operation again. Instead, it will return the same result from the first successful execution. This ensures there will be no duplication of payments or refunds.
Repeated Request (Key in Processing):
If you send a request with an x-Idempotency-Key for an operation that is already being processed (not yet completed), the API will return the HTTP status 208 - Already Reported. In this scenario, it is crucial that you retry the call after a brief interval to obtain the final status of the operation.
Error Management#
Idempotency also influences how errors are handled:
Retryable Errors: If a request fails with an error that can be retried (e.g., temporary connection issues), a new attempt with the same idempotency key will result in a retry of the operation.
Non-Retryable Errors: For errors that are not retryable (e.g., invalid parameters, validation issues), the result of the request with the same x-Idempotency-Key will always be the same error, preventing new attempts to process the same failed operation.
The following table contains a classification of non-retryable error types:
| PicPay Error Type | Status Code | Message |
|---|---|---|
| Duplicated_Transaction | (400) Bad Request | Duplicated transaction |
| Funding_source_unavailable | (403) Forbidden | Funding source unavailable |
| Insufficient_funds | (406) Not Acceptable | Insufficient funds |
| Invalid_funding_source | (406) Not Acceptable | Invalid founding source |
| Account_closed | (406) Not Acceptable | The account is closed |
| Account_on_hold | (406) Not Acceptable | The account is on hold |
| Invalid_Permission_refund | (406) Not Acceptable | Invalid Permission |