Learn · Understand · Build

Payment Idempotency — Retrying POST /payments Safely

CategoryPaymentsRead8 minUpdated18 Nov 2026

Every payment initiation request carries an x-idempotency-key. Used correctly, it lets a TPP retry a request that timed out without paying twice. This article explains what the API Hub does with the key, where its protection ends, and what TPPs and LFIs MUST do so that each payment instruction is executed at most once.

PaymentsIdempotencyRetries
01 The key

One key per payment instruction, checked by the API Hub

Every POST/payments request carries an x-idempotency-key header: a string of up to 40 characters, with no whitespace, chosen by the TPP. It identifies one payment instruction.

The API Hub checks the key before it forwards the request to the LFI. If the API Hub has already recorded a successful payment for that key from the same TPP, it answers with that payment and does not forward the request again. The specification sets the window at 24 hours from the first request. Two properties matter in practice:

  • Matching is per TPP, not per consent. The API Hub looks a key up across all of a TPP's payments, on every consent.
  • Only successful payments are recorded. The API Hub records a key once the LFI has created the payment. An attempt that ended in an error leaves nothing recorded.
Never reuse a key

A key MUST identify exactly one payment instruction. Do not reuse it for another instruction, on another consent, or after the 24-hour window. Generate a new key, such as a UUID v4, for every new payment.

02 Outcomes

What happens to a request, and whether it reaches the LFI

SituationWhat the TPP receivesReaches the LFI?
First request201 with a new PaymentId; the key is echoed in the x-idempotency-key response headerYes
Same key, same instruction — resent as-is, or re-signed with a new iat and jti201 with the original PaymentId and the payment's current StatusNo
Same key, changed instruction (for example a different amount)409, GenericRecoverableError, Idempotency key mismatch: Request parameters differ from original. Nothing is executedNo
Same key, after the original payment used up the consent — for example a Single Instant PaymentAn error: the consent is no longer authorised. The payment exists; look it up by keyNo
A second POST /payments on the same consent while an earlier one is still being processed, with the same key or not403, Consent.BusinessRuleViolation: the previous payment request is still being processedNo
GET /payments with the key and a client-credentials token200 with Data: {} and Links.Self pointing to the payment; an error if no successful payment is recorded for the keyNo
The same lookup with the consent's access token401No
Same key, after the earlier attempt ended in an errorThe request is forwarded as a new requestYes

A retry is checked against the consent before its key. That is why a retry of a Single Instant Payment that succeeded is refused rather than answered with the payment: the consent allowed one payment, and it has been used.

03 Reaching the LFI

When a repeated key still reaches the LFI

The API Hub only protects payments that the LFI has already created. A request with a repeated key is forwarded to the LFI when the earlier attempt:

  • ended in an error from the LFI;
  • timed out before the LFI answered — for example by reaching the API Hub's 30-second request limit;
  • was made more than 24 hours earlier.

In the first two cases the LFI may already have created the payment, or even executed it, without the API Hub knowing. Only the LFI can tell, which is why LFIs de-duplicate on the key as well (section 05).

04 TPP retries

Find out what happened before you resend

  • One key per instruction. Generate a new key for each new payment instruction and store it with the instruction before you send the request, so that a retry after a crash or restart uses the same key.
  • Look up before you resend. If you receive no response, the connection fails, or you receive an error, call GET/payments with the same key and a client-credentials token (scope openid payments). A 200 points to the payment in Links.Self. The lookup still works after the consent's access token has expired, or the consent has been used up.
  • Resend unchanged. If the lookup returns an error, no successful payment is recorded under the key. Resend the same instruction under the same key. You may re-sign the request; do not change the instruction, and do not generate a new key.
  • Read the body. Treat a 201 received for a retry as the result of the original request. Read PaymentId and Status from the response body; do not depend on the Location header.
  • Payment already being processed. On the 403 that says a previous payment request is still being processed, wait for your earlier request to complete, then retry with the same key. Do not send parallel payment requests under one consent.
  • Key mismatch. On the 409 Idempotency key mismatch, the key already belongs to a different instruction and nothing was executed for this request. Any payment already made under the key stands. A genuinely new instruction needs a new key.
  • Errors on a retry. Do not treat an error on a retry as proof that the payment failed until you have looked the payment up by key.
typescript
// attempt.key was generated once for this payment instruction (crypto.randomUUID())
// and stored with the instruction before the first send.
async function initiatePayment(attempt: { key: string; instruction: PaymentInstruction }) {
  const first = await postPayment(attempt.instruction, attempt.key).catch(() => null) // null: no response
  if (first?.status === 201) return first.body.message.Data   // PaymentId and current Status

  // No response, or an error: find out whether the payment exists before resending.
  const self = await lookupPaymentByKey(attempt.key)
  if (self) return { self }                                   // it exists: read it via Links.Self

  // Nothing recorded under the key: resend the same instruction under the same key.
  return postPayment(attempt.instruction, attempt.key)
}

// GET /payments with the key. Needs a client-credentials token, not the consent's token.
async function lookupPaymentByKey(key: string): Promise<string | null> {
  const res = await fetch(`${RESOURCE_SERVER}/open-finance/payment/v2.1/payments`, {
    headers: {
      'Authorization':         `Bearer ${await clientCredentialsToken('openid payments')}`,
      'Accept':                'application/jwt',
      'x-idempotency-key':     key,
      'x-fapi-interaction-id': crypto.randomUUID(),
    },
    // agent: new https.Agent({ cert: transportCert, key: transportKey }),
  })
  if (res.status !== 200) return null                         // an error: no payment recorded
  const { message } = await verifySignedResponse(await res.text())  // AEIdempotencyKeyQuerySigned
  return message.Links.Self
}
05 LFI de-duplication

Recognise a retry the API Hub could not answer

The API Hub forwards the TPP's key to your Ozone Connect POST/payments endpoint in requestHeaders["x-idempotency-key"] of the request body. The TPP's client is in tpp.clientId, and the consent is in the o3-consent-id header. Each payment type's Payment Execution requirements carry the rule Repeated x-idempotency-key — for example Single Instant Payment. The LFI MUST:

  • record each payment it creates against the key, the client and the consent, and keep the record for at least 24 hours;
  • check for a matching record before every other check on the request;
  • on a match, not execute the payment again, and return 201 with the original PaymentId and the payment's current Status — if the earlier request is still being processed, return its outcome rather than start a second payment;
  • on a matching key with different payment details, not execute the request, and return 409 with errorCode GenericRecoverableError and errorMessage Idempotency key mismatch: Request parameters differ from original. — comparing PersonalIdentifiableInformation after decryption, because the encrypted value changes each time the TPP re-signs;
  • return an error only when the payment has definitely not been submitted for processing — once it has, return 201 and report the outcome through Status and PATCH /payment-log/{id}.

On the on-demand payment types, this check runs before the duplicate-in-flight check. That check applies only to requests whose key does not match, and it covers the period after the 201, while an earlier payment is still Pending. The API Hub's own check covers the period before: it rejects a request that arrives while another request under the same consent is still being processed.

Why the consent is part of the LFI's key

The API Hub matches keys per TPP. The LFI also matches on the consent: a request with a repeated key on a different consent reaches the LFI only if the API Hub recorded no payment for the key, and matching it to a payment on another consent would attach that payment to the wrong consent.