API Requests Idempotency & Request References

Using API Requests Idempotency

PPRO’s payment processing POST endpoints accept unique idempotency identifiers to eliminate duplicate requests via the header “Request-Idempotency-Key”. The usage of idempotency keys is an optional but highly-recommended best practice, to avoid situations such as accidentally charging the consumer twice for the same purchase.

You can retry idempotent calls that fail with network timeouts or HTTP 5xx status codes for as long as the server stores the idempotency key. Idempotency keys are stored for 24 hours by default.

If the initial call fails with a 4xx status code, we do not store the idempotency key, because the request was rejected outright and no execution / processing took place. This means the idempotency key could theoretically be reused for a different request.

POST /v1/payment-agreements HTTP/1.1
Host: api.sandbox.eu.ppro.com
Request-Idempotency-Key: 4z8IdLhzpGdtoqdrUxoN


Sending requests with an Idempotency Key that has already been stored by PPRO

Sending a duplicate request will result in a 409 error status code if the previous request is still in transit. If the previous request was successfully processed, the duplicate request will return the same response as the original request. When a request is served from the idempotency store, the response will contain a Request-Idempotency: true header.

If a request made using a duplicate Request-Idempotency-Key header, but the request body differs in any way from the original, you will also receive a 409 error.