Idempotent Requests

In any distributed system, network failures or timeouts can create uncertainty about whether a transaction was processed. Retrying a request without a safeguard could result in duplicate charges.

To prevent this, the PCE API supports idempotency through the use of a unique replayId field. By including this ID in your Payment and Terminal API requests, you can safely retry operations. If a request with a replayId has already been processed, our system returns the original, cached response instead of creating a new transaction. This ensures that an operation is performed exactly once.

How It Works

The replayId is a unique key that your client application generates for each new payment request. Our system uses this key to manage idempotency as follows:

First Request: When a request arrives with a new replayId, it is processed normally, and the result is stored in association with that ID.
Subsequent Requests: If another request arrives with the same replayId, the system recognizes it, bypasses transaction processing, and immediately returns the original success or failure response.

Key Characteristics

Attribute	Description
Type	`string` (representing a 15-digit numeric string, equivalent to a `bigInt`)
Purpose	Uniquely identifies a payment request to ensure idempotency.
API Scope	Payment API and Terminal APIs
Transaction Scope	Applicable to ACH and Card payments for all primary payment types: Sale, Authorization, Capture, Refund.
Behavior	Optional. If your integration requires safe retries, providing a unique `replayId` is mandatory.

Practical Use Cases

You should use replayId to build a resilient integration that can safely handle ambiguity and network failures.

Safe Retries for Network Errors and Timeouts: If your application sends a request but a network error prevents it from receiving the response, you can safely resend the exact same request with the same replayId to get the definitive outcome without causing a duplicate charge.
Critical for Terminal Transactions and Reconciliation: For InPerson (Terminal API) payments, the replayId serves as the primary unique identifier. It is essential for tracking and linking your initial API request to the final transaction details. Always store the replayId for terminal payments to ensure accurate reconciliation.
Preventing User-Induced Duplicates: If a user accidentally double-clicks a "Pay Now" button in your application, sending two requests in quick succession with the same replayId will ensure that only the first one is processed.

Best Practices

Client-Side Generation is Key: To leverage idempotency, your application is responsible for generating and storing the unique 15-digit replayId before making the first request.
Use for Reconciliation: For all terminal integrations, always store the replayId. It is your primary key for tracing a transaction from initiation to settlement.
Scope Your IDs: A replayId should represent a single, unique user transaction. If a user's payment fails and they initiate a new attempt (e.g., with a different card), that is a new action and must have a new, unique replayId.