Idempotency

Overview

An idempotent operation or function is one where it can be executed multiple times without changing the result beyond the initial execution.

This characteristic is essential for building robust, fault-tolerant systems that can handle network failures, timeouts, and retry scenarios gracefully.

Implementation in Payment Systems

For APIs involving money movement, idempotency is a critical safety mechanism that prevents duplicate transactions when clients need to retry the API request.

In Pave, idempotency ensures that a client who calls a supported endpoint with the same idempotency key is able to call the API multiple times without generating multiple payments.

Supported Endpoints

Where production is Not supported, the header is ignored and a retry can create a second account. Check whether the first request succeeded before retrying, for example by listing nominal sub-accounts.

Idempotency Behaviour

Transaction Creation

Clients should pass in an idempotency key in their request header. A random UUID per request is a good choice.

When a client creates a request with an idempotency key, the system will exhibit the following behaviour:

• First Request: Creates a new transaction and returns the TransactionID
• Second Request: Returns the same TransactionID for the previously created transaction when using an identical idempotency key
• Immutability: Creating a request with the same idempotency key but different fields will not create a new transaction or update the existing one. The original TransactionID will be returned
  • Sandbox: returns 400 Bad Request instead, so a changed request is never silently ignored. Send it under a new key
• First Request Failed or Still Processing: the second request returns an "idempotency failure" error. See Error Handling
  • Sandbox: returns the same error as the first request if it failed, or 409 Conflict if it is still processing

Key Lifecycle Management

• Expiration: Idempotency keys have a 24-hour time-to-live (TTL). After expiration, subsequent requests with the same key will be processed as new operations
• Scope: Keys are isolated per client and per endpoint

Error Handling

When an idempotency failure occurs, clients will receive an "idempotency failure" error message. Clients should:

• Cease retry attempts
• Contact your Pave integration partner to investigate the transaction state and determine next steps to process the transaction

Sandbox does not return "idempotency failure". Instead:

• Same error as the first request: the first request failed. Fix the request and send it under a new key
• 409 Conflict: the first request is still processing. Wait briefly and retry with the same key
• 400 Bad Request, message Idempotency-Key was already used with a different request payload: send the changed request under a new key

If a 409 persists for more than a few minutes, contact your Pave integration partner with the key and endpoint before creating a new transaction.