Idempotency keys

Overview

Idempotency keys help prevent duplicate transactions by ensuring that identical requests are processed only once. This is particularly important for payment operations where network issues could lead to unintended duplicate submissions.

Implementation Details

Key Requirements

• Must be unique
• Maximum length: 100 characters
• Validity period: 10 days
• Provided in the request header
• Not exposed in reports or API responses

Error Scenarios

When a duplicate key is detected, the response includes the paymentId of the original transaction.

Payment Duplicate Detection

Standard Payment Operations

The API implements two levels of duplicate detection:

1. Idempotency Key Check

   • Prevents duplicate submissions due to network issues
   • Based on the provided idempotency key
   • Valid for 10 days

2. Content-Based Check

   • Compares payment details:
     • Amount
     • Currency
     • Beneficiary name and address
     • Debtor reference
     • Execution date
   • Rejects identical payments with status pendingProcessing

Direct Debit Collections

Important: Direct Debit Collections endpoints currently handle idempotency differently from other payment operations, but we plan to align with the standard pattern in future updates.

For Direct Debit collections:

• Previously accepted requests with the same key return a 400 error
• Error response includes details about the original transaction
• Maximum length: 32 characters
• Keys are valid indefinitely

Example error response:

{
  "error": {
    "id": "{{errorId}}",
    "code": 400,
    "message": "IdempotencyKey {{key}} was already used at {{date}} creating entity {{entityId}}.",
    "details": []
  }
}