Prevent duplicate transactions

The Transaction API provides two mechanisms to prevent duplicate transactions before the transaction enters the processing pipeline:

1. Transaction keys
2. Field-based duplicate checking

You can use either method independently or combine them.

Transaction keys

Use the TransactionKey HTTP header to identify each transaction request.

Use any value from your system, such as a claim identifier, payment identifier, or database key.

Transaction keys:

• Support a maximum length of 64 characters
• Use case-insensitive matching
• Must be unique for each transaction request

Example request

POST /api/transactionrequests
TransactionKey: CLM-51837

Request body:

{
  "SendValue": 100.00,
  "SendCurrency": "EUR",
  "Recipient": {
    "Name": "Victoria Lau",
    "RecipientReference": "Claim-51837",
    "Country": "GB",
    "Currency": "GBP",
    "Account": {
      "SortCode": "112233",
      "AccountNumber": "22233445"
    }
  }
}

Duplicate key behaviour

When Vitesse receives a transaction request:

• 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"
}

Verify 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.

Example request

GET /api/transactionrequests/transactionKey/CLM-51837

Example response:

{
  "CreatedOn": "2026-05-13T10:15:00Z",
  "TransactionRequestId": "747101ce-2d0c-41bd-ae4a-ba5a0c267c70"
}

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

Field-based duplicate checking

Use field-based duplicate checking to compare selected values in a transaction request with previously processed transactions.

If the system identifies a matching transaction, Vitesse will reject the request and not process the payment.

Duplicate detection modes

Choose a duplicate detection method

Use TransactionKey whenever possible. Transaction keys provide deterministic duplicate detection and help you recover safely from timeouts or connection failures.

Use field-based duplicate checking to add an additional layer of protection against accidentally submitting the same payment details more than once.