Ensure Idempotency with Request Tokens

You can attach a custom, one-time-use identifier to any Payrix Pro API request, across GET, PUT, POST, and DELETE methods. Once submitted, a Request Token is stored, automatically blocking any future request with the same token for 48 hours. This helps ensure that only the first request is processed and subsequent requests return the original response with a “duplicateRequest": true flag.

Key benefits of idempotent requests using Request Tokens include:

Transaction Safety: Eliminate financial risk from retry logic or network errors.
User Trust: Prevent double charges or accidental duplicate actions.
Operational Clarity: Know when a transaction has already been submitted and processed.
Scalability: Build robust integrations with duplication prevention control.

Request Token Use Cases

Request tokens help safeguard against accidental reprocessing in common high-risk operations. Popular use cases for ensuring idempotent API calls using the REQUEST-TOKEN header include:

One-Time Payments: Ensures only one payment is processed from a customer if a request is sent multiple times.
Recurring Payments: Prevents duplication of payment schedules for recurring payments.
Refunds and Reversals: Prevents multiple refunds, voids, or cancellations for the same transaction.
Merchant Boarding: Ensures merchants aren't registered multiple times due to repeated requests.
User Management: Prevents duplicate user records during creation or updates.

Think of your REQUEST-TOKEN as a unique receipt. It helps the API recognize when a request has already been processed, so you don’t end up charging or refunding a customer twice by mistake, for example.

Create a Request Token

A Request Token can be any unique string between 1 and 100 characters, including alphanumeric and special characters.

Example Request

BASH

POST /refunds HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
REQUEST-TOKEN: 20250423-yourmerchant-refunds-001

When the request is received, Payrix Pro links the token to the request. Any future request using the same token, regardless of endpoint, will return the original response and flag the request as a duplicate.

Note

The REQUEST-TOKEN header value is case sensitive.

Recommended Token Naming

To maximize effectiveness and prevent accidental reuse, adopt a structured naming convention for Request Tokens.

Use Hyphens: Improve security and readability by separating token identifiers with hyphens (-).
Include Context: Add details like the endpoint, Merchant name, or login ID, such as yourmerchant-refunds.
Add a Timestamp: Prefix the token with YYYYMMDD for uniqueness. For example, 20250423-yourmerchant-refunds.
Sequence Your Tokens: Add a three or four-digit number to the end of the token to safely create multiple tokens. For example: 20250423-yourmerchant-refunds-001.
Track Usage: Maintain a log of created and used tokens to prevent reuse.

Create an Idempotent Request

To continue from our example above, we can now create a standard sale or refund transaction using the unique Request Token we’ve created to provide idempotency to the transaction. This is especially useful for refund transactions to prevent a customer from being refunded twice by accident through the API.

Example Request

BASH

POST /refunds HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
REQUEST-TOKEN: 20250423-yourmerchant-refunds-001

JSON

{
	"merchant": "t1_mer_123abc4d567890efg1h2i34",
	"fortxn": "t1_txn_123abc4d567890efg1h2i34",
	"total": 1000,
	"type": 5, 
	"origin": 2

A successful response returns the request details. If the same token, 20250423-yourmerchant-refunds-001 is reused, the API won’t process the request again and instead returns the previous transaction details with a “duplicateReqeust": true flag.

Identify Duplicate Requests

When a Request Token is reused, the API includes a “duplicateRequest": true field in the response details metadata. This confirms that the request was recognized as a duplicate and no new transaction is created.

Example Response with Duplicate Flag

JSON

{
    "response": {
        "data": [
            {
            ...
            }
        ],
        "details": {
            "requestId": 1,
            "duplicateRequest": true 
        },
        "errors": []
    }
}

When "duplicateRequest": true is present, no new request is processed. The API returns the details of the first request that used the specified REQUEST-TOKEN.