Prevent duplicate transactions

The system performs duplicate detection before the transaction enters the processing pipeline. The Transaction API provides two mechanisms to prevent duplicate payments:

1. Transaction keys
2. Field-based duplicate checking

You can use either method independently or combine them. Vitesse recommends using at least one duplicate detection method.

Transaction keys

Use the TransactionKey HTTP header to attach a unique identifier to each transaction request.

POST /api/transactionRequests
Host: api.vitessepsp.com
Content-Type: application/json
TransactionKey: your-unique-key
Authorization: Bearer <access_token>

You can use any unique string from your system to populate this header value (for example, a record ID or payment reference). Maximum length: 64 characters. Values are treated as case-insensitive.

Duplicate key behaviour

When a transaction request is received:

• If the TransactionKey value is unique, the system validates the request.
• If the key already exists, the API returns a DuplicateTransactionKey error.

Example response:

{
  "Code": "DuplicateTransactionKey",
  "Message": "A duplicate transaction key was sent to the API.",
  "MoreInfo": "https://docs.vitessepsp.com/reference/errors#duplicatetransactionkey"
}

❗

Transaction keys are retained for one month. After that period, the API can reuse the same key for a different transaction.

Verifying a transaction key

If your system sends a request but does not receive a response (for example, because of a network timeout), query the key to check whether the transaction was created.

GET /api/transactionrequests/transactionKey/{key}
Authorization: Bearer <access_token>

Example response:

{
  "CreatedOn": "2021-11-26T17:53:24.677Z",
  "TransactionRequestId": "3c78ca56-87f1-4a22-aca7-b87b1d681375"
}

This allows your application to determine whether the original request was successfully received.

Field-based duplicate checking

The system can also detect duplicates based on selected field values.

When enabled, the system compares the field values in the incoming request with previously processed transactions. If the system finds a matching transaction, it rejects the request and does not process the payment.

This feature must be enabled by contacting your Vitesse account manager.

Two configurations are available:

📘

Contact your Vitesse account manager to enable this feature, or to configure custom duplicate detection rules.

Choosing a duplicate detection method

The TransactionKey header is the most reliable way to prevent duplicate requests and is recommended for all integrations.

Field-based duplicate checks provide additional protection against accidentally submitting the same payment details more than once.