Every time you make a POST request to PaymentsOS, you're changing something. Sometimes this is innocuous, but often it's important that this happens once and only once. For example, creating new authorizations, and customers should ideally only happen once.
We support this capability through a feature named Idempotency.
Using the Idempotency feature is a way of preventing data corruption caused by sending duplicate requests.
To send a post request that is "Idempotent safe", simply include an idempotency_key header.
The idempotency_key must be unique and should only be used in one request. The content of the key is completely up to you. For example, you can use some transaction-related string, or generate a random string.
Re-sending a request until you get a response
You can safely re-send a request containing an idempotency_key, within the "24-hour safe-retry window", until you actually get a response from the server.
Re-sending a request after receiving certain error responses
The following error responses allow you to continue re-sending the same request. In such cases, you should make sure to use the same idempotency_key, to avoid creating multiple resources:
- Error response: 500 - Server Error
- Error response: 503 - Service Unavailable
- Response Category: provider_error
- Response Category: provider_network_error