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, our current implementation of idempotency encures that a client who calls our external transfer API with the same idempotency key is able to call the API multiple times without generating multiple payments.

Idempotency Behaviour

Transaction Creation

Clients should pass in an idempotency key in their request header.

When a client creates a transfer 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

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

Error Handling

When an idempotency failure occurs, they 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