v2.2-rc2 is not ratified and MUST NOT be used for production. Current: v2.1. Changelog
This is v2.2-rc2 — a release candidate for the v2.2 standards, published for review and not yet ratified. It MUST NOT be used as the basis for a production implementation. For the current standards, switch to v2.1 using the version selector. See the v2.1 → v2.2-rc2 changelog for every change in this version.
Payment Refunds — API Guide 2 min read
The Payment Refunds endpoint lets the API Hub retrieve the debtor's payment account details from your LFI after a payment has been made. The TPP uses those details to initiate a refund back to the original payer. This endpoint does not execute the refund itself — it only returns the account details needed to initiate one.
End-to-end refund account retrieval
Return the debtor's refund account
/payment-consents/{consentId}/refundRequest headers
| Header | Required | Description |
|---|---|---|
o3-provider-id | Yes | Identifier for your LFI registered in the Hub |
o3-aspsp-id | Yes (deprecated) | Deprecated alias for o3-provider-id. Will be removed in a future version — use o3-provider-id |
o3-caller-org-id | Yes | Organisation ID of the TPP making the underlying request |
o3-caller-client-id | Yes | OIDC client ID of the TPP application |
o3-caller-software-statement-id | Yes | Software statement ID of the TPP application |
o3-api-uri | Yes | The parameterised URL of the API being called by the TPP |
o3-api-operation | Yes | The HTTP method of the operation carried out by the TPP (e.g. GET) |
o3-ozone-interaction-id | Yes | Hub-generated interaction ID. Equals o3-caller-interaction-id if the TPP provided one |
o3-caller-interaction-id | No | Interaction ID passed in by the TPP, if present |
o3-psu-identifier | Yes | Base64-encoded representation of the customer identifier JSON object |
Path parameters
| Parameter | Required | Description |
|---|---|---|
consentId | Yes | The consent ID of the original payment consent |
Response
Content-Type: application/json
Return 200 with the debtor's refund account details. The Hub wraps the response in a signed JWS before returning it to the TPP — your LFI returns plain JSON.
200 — Refund account found
Return the debtor's account details under data.refundAccount, and the status of that account under data.accountStatus. Both are required. The refundAccount object must contain the debtor's IBAN and name.
Return the refund account regardless of its status, as GET /accounts does. An account that is Inactive, Dormant, Suspended, Unclaimed, Deceased or Closed is still answered with 200, and accountStatus carries its state so the TPP can observe it. Do not return 403 because the account is blocked from receiving payments — v2.1 did, v2.2 does not.
{
"data": {
"consentId": "con-7f4a9b2c-1d3e-4f5a-b6c7-8d9e0f1a2b3c",
"refundAccount": {
"schemeName": "IBAN",
"identification": "AE070331234567890123456",
"name": {
"en": "Ibrahim Al Suwaidi"
}
},
"accountStatus": "Active"
},
"meta": {}
}
data
| Field | Type | Required | Description |
|---|---|---|---|
consentId | string | No | The consent ID of the original payment consent |
refundAccount | object | Yes | The debtor's account — see below |
accountStatus | string | Yes | The status of the account in refundAccount, using the statuses that apply to current and savings accounts: Active, Inactive, Dormant, Unclaimed, Deceased, Suspended or Closed. The Hub returns it to the TPP as AccountStatus |
data.refundAccount
| Field | Type | Required | Description |
|---|---|---|---|
schemeName | string | Yes | Account identifier scheme — always IBAN |
identification | string | Yes | The debtor's IBAN |
name | object | Yes | The account holder name |
name.en | string | Yes | Account holder name in English (max 70 characters) |
name.ar | string | No | Account holder name in Arabic (max 70 characters) |
Error responses
All error bodies must include errorCode and errorMessage.
An account that is blocked from receiving payments is not an error. Return 200 with its accountStatus, as described under Refund account found above.
504 — Gateway Timeout
You MAY return 504 when you cannot complete processing within your internal time limit. The API Hub treats it as a timeout. The body for this status is not standardised and no schema is defined for it. A 504 is a 5xx response, so it counts as a failed request under the Ozone Connect Availability Policy.
Full request and response schema
See the GET /payment-consents/{consentId}/refund API Reference for the full request and response schema.
