Skip to main content

Idempotency Keys

In payment systems, retries are common - whether due to network errors, timeouts, or disconnects. But retrying a request like "initiate payment" or "issue refund" can lead to duplicate transactions with real financial consequences.

That’s where idempotency keys come in. They make your integration safe and repeatable.

What Is an Idempotency Key?​

An idempotency key is a unique string sent by the client that ensures a specific operation is only executed once, no matter how many times it is submitted.

If the same request is sent multiple times with the same key, our platform:

  • Detects the duplicates
  • Skips re-processing
  • Returns the original result
Good to know

Idempotency keys are particularly important for create or mutate operations such as payments and refunds.

How to Use Idempotency Keys​

  • Send an Idempotency-Key in the request header
  • Keys are valid for 24 hours
  • Reuse the key if retrying the same operation

Example​

To make use of idempotency keys, you should include an additional header to your Payment Requests with Nopan:

cURL - POST /payments/initiate
curl -X POST https://api.nopan.com/payments/initiate \
  -H "Authorization: Bearer <access-token>" \
  // highlight-next-line
  -H "Idempotency-Key: 63c2e3f0-12aa-41bb-ae62-f3d91fdbb762" \
  -H "Signature: nopan_sig=<signature>" \
  -H "Signature-Input: nopan_sig=("@status");keyid="your-key-id";created=1766678793 \
  -H "Content-Type: application/json" \
  -d '{
    "clientTransactionId": "order123",
    "transactionType": "ONE_TIME",
    "paymentDetails": {
      "amount": 100,
      "currency": "PLN",
      "country": "PL",
      "description": "Product ID 1234 purchase"
    },
    "providerDetails": {
      "providerId": "BLIK"
    },
    "payerDetails": {
      "payerId": "payerUUID",
      "oneTimeCode": "123456"
    }
  }'
tip

If a request fails or times out, retry it using the same Idempotency-Key and the exact same payload.

How This Differs from clientTransactionId​

Nopan also asks clients to specify clientTransactionId within the request payload. While it may look similar to Idempotency-Key, it serves a different purpose.

Feature
Idempotency-Key
clientTransactionId
Used for
Retry safety
Business-level tracking
Where it is sent
HTTP header
Request payload field
Generated
Auto-generated per operation
Usually an internal reference ID
Used by PSP logic
To detect and prevent duplicate processing
Logging/Reconciliation/Search/Reporting
Effect on retries
Same key = same result (no duplication)
New request = new payment even if ID is reused
Should be unique?
Yes — per operation
Yes — per business transaction
TTL (time-to-live)
Stored and valid for 24 hours
Stored up to 1 year for lookup
Example value
63c2e3f0-...-ae62-f3d91fdbb762
ORDER-9483
Best Practices
  • Use UUIDv4 strings for idempotency keys
  • Store the key client-side before sending the request
  • Log both Idempotency-Key and clientTransactionId for observability
  • Retry only with the same payload and same key

Which APIs use idempotency?​

Idempotency keys are required for mutating operations and ignored for read-only endpoints.

Mutating (use Idempotency-Key):

  • POST /payments/initiate
  • POST /payments/finalize
  • POST /payments/charge
  • POST /payments/capture
  • POST /payments/cancel
  • POST /payments/refund

Read-only (no idempotency needed):

  • GET /payments/{id}/status
  • GET /payments/{id}/events
  • POST /payments/search
  • POST /payments/providers

Idempotency is a simple but critical tool for building resilient payment flows. It protects your shoppers and your business from accidental duplicates, and ensures your systems behave consistently even in unreliable conditions.