Duplicate Detection

Prevent duplicate transactions from being processed. Our gateway uses idempotency_key and idempotency_time to identify and block duplicate transaction attempts, ensuring that accidental retries or network issues don't result in multiple charges.

How It Works

We use idempotency_key and idempotency_time to determine whether or not a transaction is a duplicate. idempotency_time is an optional parameter used to set a custom TTL (Time To Live) for the idempotency_key. If no idempotency_time is provided in the request, we will use the Merchant's Duplicate detection seconds default value. If this isn't set, we will default to 5 minutes.

Fields

Name	Type	Default	Description	Required
idempotency_key	string (UUID format)		Used to identify duplicate transactions. If idempotency_time is not provided, the TTL will default to 5 minutes
idempotency_time	integer (seconds)	300	Time to live for the idempotency key in seconds. Default is 5 minutes (300 seconds)

Method 1: Using an Idempotency Key (Recommended)

The most reliable way to prevent duplicates is to use an idempotency_key. Generate a unique UUID for each transaction attempt and include it in your request. If the same key is used within the idempotency_time window, the duplicate request will return the original transaction response instead of processing a new transaction.

Example: First Request

Response: Transaction is processed and returns a new transaction ID.

Example: Duplicate Request (Same Idempotency Key)

If you send the exact same request with the same idempotency_key within the idempotency_time window:

Response: Returns the same transaction ID from the first request. No new transaction is processed. The customer is not charged again.

Best Practice

Always generate a unique UUID for each transaction attempt. Store this key with your order/transaction record so you can safely retry failed requests without creating duplicates.

Method 2: Automatic Duplicate Detection (No Idempotency Key)

If no idempotency_key is provided, and you provide an idempotency_time OR the Merchant has a default value for Duplicate detection seconds, then we will determine if a transaction is a duplicate based off of the following fields:

Card Transactions

The following fields are compared to detect duplicates:

• amount
• order_id
• payment_method.card.number
• payment_method.card.cvc
• payment_method.card.expiration_date
• billing_address.first_name
• billing_address.last_name
• billing_address.state
• billing_address.city
• billing_address.country
• Time (of the request)

ACH Transactions

The following fields are compared to detect duplicates:

• amount
• order_id
• payment_method.ach.account_number
• payment_method.ach.routing_number
• payment_method.ach.sec_code
• billing_address.first_name
• billing_address.last_name
• billing_address.state
• billing_address.city
• billing_address.country
• Time (of the request)

Example: Automatic Detection

Important: If you send the same request again with identical values for all the fields listed above within the idempotency_time window, it will be detected as a duplicate and return the original transaction response.

Recommendation

While automatic detection works, using an idempotency_key is more reliable because it gives you explicit control over duplicate detection and doesn't depend on matching multiple fields.