Idempotency keys

The PPRO API supports idempotency, enabling customers to safely retry the same request multiple times while ensuring the underlying action is executed only once. This prevents unintended duplication in scenarios involving failures or retries. For instance, if a timeout occurs, the same payment request can be resent without risk, with the assurance that the payment will be processed only once.

To minimize unintended side effects from duplicate requests, consider the following measures on your side:

Implement asynchronous server-to-server webhooks - This helps you reliably track missing or delayed responses, which are a common outcome of network timeouts or transmission failures.
Enable idempotency for API requests - The POST and PATCH endpoints support idempotency via the Request-Idempotency-Key header. Other methods such as GET, DELETE, and PUT are inherently idempotent by definition. Using idempotency keys ensures that repeated requests are not processed multiple times, preventing duplicate operations such as multiple payment charges.To minimize unintended side effects from duplicate requests, consider the following measures on your side:

Usage

Optional but recommended: Always include an idempotency key for operations that must not be repeated accidentally. Generate unique idempotency keys per request using the version 4 (random) UUID type.
Retry-safe: If a request fails due to network timeouts or HTTP 5xx errors, it can be safely retried using the same key.
4xx failures: If the initial request fails with a 4xx status code, the idempotency key is not stored, because the request was rejected and no processing occurred. This means the same key could theoretically be reused for a different request.
Key retention: The server stores idempotency keys for 24 hours by default.
Idempotency is consistently supported across all entities available in the PPRO API.

POST /v1/payment-charges HTTP/1.1
Host: api.sandbox.eu.ppro.com
Authorization: Bearer {YOUR_API_KEY}
Merchant-Id: {YOUR_MERCHANT_ID}
Content-Type: application/json
Request-Idempotency-Key: {YOUR_IDEMPOTENCY_KEY}

Sending requests with an already stored idempotency key

If a duplicate request is sent while the original request is still in transit, the API will return a 409 Conflict response.
If the original request was successfully processed, sending the same key will return the same response as the original request. Responses served from the idempotency store include the header:
```
Request-Idempotency: true
```
If a request is sent using a duplicate Request-Idempotency-Key but the request body differs in any way from the original, a 409 Conflict error will also be returned.