Payment Idempotency — Retrying POST /payments Safely
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.
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.
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.
What happens to a request, and whether it reaches the LFI
| Situation | What the TPP receives | Reaches the LFI? |
|---|---|---|
| First request | 201 with a new PaymentId; the key is echoed in the x-idempotency-key response header | Yes |
Same key, same instruction — resent as-is, or re-signed with a new iat and jti | 201 with the original PaymentId and the payment's current Status | No |
| Same key, changed instruction (for example a different amount) | 409, GenericRecoverableError, Idempotency key mismatch: Request parameters differ from original. Nothing is executed | No |
| Same key, after the original payment used up the consent — for example a Single Instant Payment | An error: the consent is no longer authorised. The payment exists; look it up by key | No |
A second POST /payments on the same consent while an earlier one is still being processed, with the same key or not | 403, Consent.BusinessRuleViolation: the previous payment request is still being processed | No |
GET /payments with the key and a client-credentials token | 200 with Data: {} and Links.Self pointing to the payment; an error if no successful payment is recorded for the key | No |
| The same lookup with the consent's access token | 401 | No |
| Same key, after the earlier attempt ended in an error | The request is forwarded as a new request | Yes |
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.
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).
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
/paymentswith the same key and a client-credentials token (scopeopenid payments). A200points to the payment inLinks.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
201received for a retry as the result of the original request. ReadPaymentIdandStatusfrom the response body; do not depend on theLocationheader. - Payment already being processed. On the
403that 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
409Idempotency 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.
// 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
}
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
201with the originalPaymentIdand the payment's currentStatus— 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
409witherrorCodeGenericRecoverableErroranderrorMessageIdempotency key mismatch: Request parameters differ from original.— comparingPersonalIdentifiableInformationafter 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
201and report the outcome throughStatusandPATCH /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.
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.
