API Reference
Start typing to search…

Idempotency & tracing

Idempotency keys

POST and PATCH endpoints support idempotency keys through the Request-Idempotency-Key header. Idempotency keys prevent duplicate requests, ensuring that operations like payments are not processed multiple times.

Usage

  • Optional but recommended: Always include an idempotency key for operations that must not be repeated accidentally.
  • 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.
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: 4z8IdLhzpGdtoqdrUxoN

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.

Tracing

PPROs API supports request tracing via the Request-Reference header, which allows developers and support teams to track and correlate requests across systems.

Usage

  • The Request-Reference header is optional but recommended for debugging, monitoring, and auditing purposes.
  • Include a unique string identifier in the header for each request to make it easier to trace through logs and API processing pipelines.
  • The header can be included in all HTTP methods (GET, POST, PATCH, etc.).
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: 4z8IdLhzpGdtoqdrUxoN
Request-Reference: abc123-trace-456