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 Status 5 min read
Every domestic payment initiated through the API Hub is executed by the LFI in one of three modes: intra-bank (both debtor and creditor accounts are held at the same LFI, so no rail is used), AANI (the UAE's instant payment rail, used as the primary interbank rail), or UAEFTS (the UAE Funds Transfer System, used as the fallback interbank rail). Your TPP does not select the execution mode — the LFI owns that decision.
Your TPP receives status updates for every payment through two complementary mechanisms: event notifications (the Hub pushes a webhook to your registered endpoint each time status changes) and polling (GET/payments/{paymentId} on the API Hub). This page covers how to receive status, what each status means, and which statuses you can expect for each execution mode.
How your TPP receives payment status
Event notifications (recommended)
When your consent is created with subscription.Webhook.IsActive: true and a registered Webhook.Url, the API Hub pushes a Payment Status Event to your endpoint each time the LFI PATCHes a new status to the Hub. Events are delivered as JWE-encrypted POST requests signed with your registered Encryption Certificate. Your TPP MUST respond with 202 Accepted immediately and decrypt the payload asynchronously.
Event notifications are the recommended mechanism — they provide the lowest latency and remove the need for your TPP to poll. See the Payment Status Event API Guide for the full event shape, encryption requirements, and retry semantics.
Polling (fallback)
Your TPP MAY instead call GET/payments/{paymentId} on the API Hub to retrieve the current status on demand. Polling is appropriate when:
- Your TPP has not registered a webhook endpoint for this consent.
- You need to reconcile a missed or late event.
- You want to confirm the authoritative status before acting on an event payload.
When polling, make the first poll about 3 seconds after the 201 on POST/payments. By then the LFI is required to have handed the payment to the rail. Back off as time passes, and stop polling once the payment reaches a terminal status (AcceptedWithoutPosting, AcceptedCreditSettlementCompleted, or Rejected). When to expect each status is set out in Payment Timing.
Open Finance payment statuses
The Open Finance payment status enum aligns with ISO 20022 ExternalPaymentTransactionStatus1Code. Five values are relevant for domestic payments:
| Open Finance status | ISO 20022 | Meaning | Terminal? |
|---|---|---|---|
Pending | PDNG | Payment accepted for processing; rail submission or internal execution outstanding. This is the initial status returned in the POST/payments response | No |
AcceptedSettlementCompleted | ACSC | The LFI has completed its checks and handed the payment to AANI or UAEFTS. Set within 3 seconds of the LFI’s 201, and always followed by a terminal status. Does not apply to intra-bank payments | No |
AcceptedWithoutPosting | ACWP | The receiving bank has accepted the payment; the originating LFI cannot confirm that the credit has posted to the creditor account | Yes (on AANI) |
AcceptedCreditSettlementCompleted | ACCC | The creditor account has been credited with the funds of the payment | Yes (on UAEFTS and intra-bank) |
Rejected | RJCT | The payment was rejected, either by the LFI before submission or by AANI or UAEFTS | Yes |
The Open Finance enum also includes Received (ISO 20022 RCVD), used only for bulk and batch payments where the Hub acknowledges receipt of a file of instructions. Bulk and batch payments are not yet documented in v2.2 — for the domestic single and multi-payments covered by this page, you can ignore Received.
Once a payment reaches a terminal status (AcceptedWithoutPosting, AcceptedCreditSettlementCompleted, or Rejected), its status will not change again.
Rail selection and the statuses you can expect
The LFI selects the execution mode on receipt of each POST/payments. The rule is:
- Intra-bank — if both the debtor and creditor accounts are held at the same LFI, the payment is executed internally without a rail.
- AANI — otherwise, the LFI submits the payment to AANI whenever the receiving bank and account are reachable on AANI.
- UAEFTS — if AANI is unavailable or cannot reach the receiving bank, the LFI falls back to UAEFTS. The fall-back is automatic; your TPP and the customer are not involved.
If neither rail can reach the receiving bank, the LFI rejects the payment pre-rail before ever submitting it. The status set your TPP should expect depends on which mode the LFI chose:
You can see which mode was chosen from Data.PaymentRail, returned on the payment record and on the payment status event: LFI (intra-bank), AANI, or FTS. It reports the rail the payment was actually settled over, not the one requested, and is absent until the LFI has routed the payment. The rail also sets the namespace of any RejectReasonCode (LFI.*, AANI.*, or FTS.*).
Intra-bank
Both accounts are at the same LFI, so the LFI has full visibility of both legs and can confirm the creditor has been credited.
- Success path:
Pending→AcceptedCreditSettlementCompleted - Rejection path:
Pending→Rejected(withLFI.<reasonCode>)
On AANI and UAEFTS, the LFI reports AcceptedSettlementCompleted as soon as it submits the payment to the rail, within 3 seconds of its 201. The terminal status follows when the rail responds.
AANI
AANI is the UAE's instant payment rail. It settles within seconds and returns either a positive Account Verification Response (the receiving bank has accepted) or a rejection. AANI does not expose a credit-posting signal to the originating LFI, so the terminal successful status is AcceptedWithoutPosting rather than AcceptedCreditSettlementCompleted.
- Success path:
Pending→AcceptedSettlementCompleted→AcceptedWithoutPosting - Rejection path:
Pending→AcceptedSettlementCompleted→Rejectedwhen AANI rejects the payment, orPending→Rejectedwhen the LFI rejects it before submission — either way withAANI.<reasonCode>
UAEFTS
UAEFTS is the UAE Funds Transfer System, operated by the Central Bank. It carries payments over ISO 20022 pacs.008 messaging and settles through the Central Bank as a centralised interbank clearing. Because settlement is centralised, the CB900 Debit Confirmation implicitly confirms the creditor side, so the terminal successful status is AcceptedCreditSettlementCompleted.
- Success path:
Pending→AcceptedSettlementCompleted→AcceptedCreditSettlementCompleted - Rejection path:
Pending→AcceptedSettlementCompleted→Rejectedwhen UAEFTS rejects the payment, orPending→Rejectedwhen the LFI rejects it before submission — either way withFTS.<reasonCode>
Rejection reason codes
When a payment is rejected, the RejectReasonCode[] array on the payment resource carries a namespaced Code. Where PaymentRail is present, the namespace matches it — including when the LFI rejected the payment before submitting it to the rail:
| Prefix | Source | Example |
|---|---|---|
LFI. | An intra-bank payment (PaymentRail: LFI) rejected by the LFI | LFI.InsufficientFunds |
AANI. | A payment routed to AANI, rejected by AANI or by the LFI before submission | AANI.AC06 |
FTS. | A payment routed to UAEFTS, rejected by UAEFTS or by the LFI before submission | FTS.AC06 |
The API Hub relays RejectReasonCode.Code to your TPP verbatim — it does not remap rail codes into a different namespace. Your TPP SHOULD surface an actionable message to the customer where the underlying reason is recoverable (for example, insufficient funds), and SHOULD log the full code and message for diagnostic purposes.
Illustrative AANI Reject Reason Codes
The authoritative list of AANI reason codes is published in the AANI Core Service Interface Specification. The codes you will see most often are:
| AANI code | Meaning |
|---|---|
AC06 | Blocked Account |
AC07 | Closed Creditor Account Number |
AM04 | Insufficient Funds |
AM14 | Amount Exceeds Agreed Limit |
UCRD | Unknown Creditor |
The TPP-facing schema admits any namespaced code matching ^[A-Za-z]+\.[A-Za-z0-9]+$, so your TPP SHOULD handle a code from an unfamiliar namespace gracefully rather than failing on it.