UAE Open Finance

01 Section

Consent Validation

When a TPP creates a consent, the API Hub calls your POST /consent/action/validate endpoint before the consent is created. You MUST validate the consent and respond with status: "valid" or status: "invalid". If you respond with invalid, the API Hub will not create the consent and the TPP will receive an error. This validation runs before the customer is involved — there is no authentication or authorization at this stage. The purpose is to reject consents early that your systems cannot fulfil.

#

Rule

Detail

1

Unsupported standardVersion

The consent's standardVersion (a top-level property on the consent object) is the URL path version the TPP will call on subsequent payment initiation requests. If you do not support that version for the Payment Initiation API family, respond with invalid.

Where you are dual-running multiple versions during a deprecation window (see Major Version Deprecation) — for example v2.0 alongside v3.1 — you MUST respond valid for every version you serve.

Minor versions are backward compatible (see Version Management), so prior minors within each major you run are also valid (e.g. running v2.0 and v3.1 means v2.0, v3.0, and v3.1 all resolve to valid).

2

consent.PersonalIdentifiableInformation

The decrypted PII payload must conform exactly to the PII schema. If decryption fails or the payload contains additional or undocumented parameters, respond with invalid.

3

Initiation.DebtorAccount

If provided, validate that the account is a UAE IBAN held at this LFI, reachable through this API Hub integration, and in a state that permits payment initiation (not blocked, dormant, or closed). If any check fails, respond with invalid.

4

Initiation.Creditor

Initiation.Creditor is optional. If provided, it must contain 1–10 creditor entries. Validate that each creditor is a valid UAE domestic creditor — the account is reachable on a supported UAE domestic rail (AANI or UAEFTS) and, where the state of the receiving account can be determined, able to receive payments. Mandatory fields, IBAN, and BIC derivation rules apply to every entry — see Creditor. If any check fails, respond with invalid.

5

Payment type not supported

Delegated SCA must be advertised as supported for the requested beneficiary model via the corresponding flag on your authorisation server entry in the Trust Framework: ApiMetadata.DelegatedAuthentication.SingleBeneficiarySupported (exactly 1 creditor entry), ApiMetadata.DelegatedAuthentication.MultipleBeneficiariesSupported (2–10 entries), or ApiMetadata.DelegatedAuthentication.OpenBeneficiariesSupported (Initiation.Creditor omitted). If the LFI has not advertised support for the requested beneficiary model, respond with invalid.

6

Invalid BaseConsentId

If the consent includes a BaseConsentId, validate that:

The BaseConsentId references an existing consent known to the LFI and belonging to the same end user.
The referenced consent is a Service Initiation consent (authorization_details[0].type is urn:openfinanceuae:service-initiation-consent:*).
The referenced consent does not itself have a BaseConsentId — if it does, the TPP has incorrectly linked to an intermediate consent in the chain rather than the root consent. The BaseConsentId must always reference the original root consent.

If any of these checks fail, respond with invalid.

7

consent.CurrencyRequest

Must not be present. Domestic payments are denominated in AED only; CurrencyRequest is for non-local currency and international transfers. If present, respond with invalid.

02 Section

Authorization — Account Selection

The generic Authorization requirements apply to this journey. The rules below cover the additional account selection logic specific to Delegated SCA. During the consent authorization journey, the customer selects the account to be debited for payments under this consent. The LFI is responsible for presenting only accounts eligible to initiate the payment and applying any constraints the TPP has specified in the consent.

#

Field

Rule

1

Initiation.DebtorAccount

If Initiation.DebtorAccount was provided on the consent, only that account may be used — do not present an account selection screen. If the authenticated customer does not hold the specified account, PATCH the consent to Rejected and call doFail with error: invalid_request and error_description: user_does_not_own_debtor_account.

2

consent.IsSingleAuthorization

If true, only accounts the authenticated customer can solely authorize (no subsequent approvers required) may be offered and selected. If false or not provided (default), accounts where the customer is one of multiple required authorizers may also be offered; subsequent authorizers must then approve the consent before it reaches Authorized status and payments can be executed. See Multi-Authorization.

3

No eligible accounts

If the authenticated customer does not hold any account eligible to initiate a payment under this consent (including the IsSingleAuthorization constraint above), PATCH the consent to Rejected and call doFail with error: invalid_request and error_description: user_lacks_eligible_accounts. See Authorization requirements for details.

4

Single selection

The account selection screen must allow the customer to select exactly one account to be debited. A consent with no account selected must not be authorised.

03 Endpoint

Payment Execution

POST/payments

When the TPP initiates a payment under an authorized consent, the API Hub validates the access token, consent status, amount/currency consistency with the consent, and OpenAPI schema before forwarding the request to your Ozone Connect POST /payments endpoint. The rules below cover what your Ozone Connect endpoint must validate on receipt. Error responses MUST conform to the POST /payments OpenAPI schema — the errorCode values referenced below are drawn from the error schema matching the returned HTTP status (Error400, Error403, or Error409). Delegated SCA delegates strong customer authentication to the TPP, so the LFI MUST additionally verify the SCA proof delivered in the Risk block and the customer-present headers before executing the payment.

#

Rule

Detail

1

PersonalIdentifiableInformation

The decrypted PII payload must conform exactly to the Domestic Payment PII Schema Object (POST /payments). Note that DebtorAccount is not part of the payment-time PII (the debtor is fixed by the consent) and Initiation.Creditor is a single object rather than an array. Reject with HTTP 400 and:

errorCode: JWE.DecryptionError — if decryption of the PII payload fails.
errorCode: Body.InvalidFormat — if any required property is missing, of the wrong type, or the payload contains additional or undocumented properties (additionalProperties: false).

2

PersonalIdentifiableInformation (Creditor)

Delegated SCA consents can carry 1–10 creditor entries, or omit Initiation.Creditor entirely (the "open beneficiaries" model).

If Initiation.Creditor was provided at consent time, the submitted creditor on the payment request MUST exactly match one of the 1–10 consent-time entries — see Creditor for the match rules. If it matches none of the entries, reject with HTTP 400 errorCode: Consent.FailsControlParameters.

If Initiation.Creditor was omitted at consent time, the creditor validation that would normally run at consent-validate MUST be performed here instead. The LFI MUST validate that the submitted creditor is a valid UAE domestic creditor — the account is reachable on a supported UAE domestic rail (AANI or UAEFTS) and, where the state of the receiving account can be determined, able to receive payments. Mandatory fields, IBAN, and BIC derivation rules apply. If any check fails, reject with HTTP 400 errorCode: Consent.FailsControlParameters.

3

Risk.DebtorIndicators.Authentication

The payload MUST demonstrate that the User was recently authenticated by the TPP using SCA (at least two distinct factors). ChallengeOutcome MUST be Pass, AuthenticationFlow MUST be MFA, and at least two of PossessionFactor.IsUsed, KnowledgeFactor.IsUsed, or InherenceFactor.IsUsed MUST be true with a valid Type set on each. ChallengeDateTime MUST be recent relative to the payment request. If any of these conditions are not met, reject with HTTP 400 errorCode: Consent.FailsControlParameters.

4

x-fapi-auth-date

Must be present on the request as the customer was authenticated at the time of the call. Must be a valid HTTP-date (RFC 7231), e.g. Tue, 11 Sep 2012 19:43:31 UTC. If missing or malformed, reject with HTTP 400 errorCode: Body.InvalidFormat.

5

x-fapi-customer-ip-address

Must be present on the request as the customer is actively present at the time of the call. Must be a valid IPv4 or IPv6 address. If missing or malformed, reject with HTTP 400 errorCode: Body.InvalidFormat.

6

Sufficient funds

The debtor account must have sufficient available funds to cover Initiation.InstructedAmount at the time the payment is received, taking into account any holds, pending transactions, and overdraft limits applied by the LFI. If the account has insufficient funds, reject with HTTP 400 errorCode: GenericError and errorMessage: Payment rejected due to insufficient funds.

7

Debtor account — temporarily unavailable

The debtor account selected at consent authorization must still be in a state that permits payment initiation at the time the payment is received. If the account is Inactive, Dormant, or Suspended, reject with HTTP 403 errorCode: Consent.AccountTemporarilyBlocked and errorMessage: The account is temporarily blocked.

8

Debtor account — permanently unavailable

If the debtor account has become Closed, Deceased, or Unclaimed since consent authorization, reject with HTTP 403 errorCode: Consent.PermanentAccountAccessFailure and errorMessage: The account is permanently inaccessible.

9

Duplicate payment in flight

Before creating the payment record, the LFI MUST check whether another payment under the same consent with the same Initiation.Creditor and the same Initiation.InstructedAmount (currency and value) is currently in Pending status. If so, reject the new payment as a duplicate with HTTP 409 errorCode: Payment.DuplicateInFlight and errorMessage: A payment with the same creditor and amount is already in flight under this consent. Once the prior payment has left Pending (reached AcceptedSettlementCompleted, AcceptedCreditSettlementCompleted, AcceptedWithoutPosting, or Rejected), a subsequent identical payment is permitted.

This check is distinct from x-idempotency-key handling — idempotency keys protect against network-retry of the same request, whereas this rule catches genuinely duplicate payment intents submitted under different keys.

If all validations above pass, the LFI MUST create the payment record in its systems and return HTTP 201 with the generated PaymentId per the POST /payments OpenAPI schema. Full response handling is covered in the API Guide.

04 Section

Screening Checks

Once the payment record has been created, the LFI MUST apply its standard fraud, sanctions, and AML screening controls before the payment is submitted to the domestic rail. These checks are the LFI's responsibility and follow the LFI's own policies and regulatory obligations. Screening may result in the payment being held, rejected, or referred for manual review after the 201 response has been returned to the TPP. The outcome MUST be reflected in the payment's Status and surfaced via GET /payments/{paymentId} so the TPP can observe the final state.

#

Rule

Detail

1

Screening duration

Screening checks SHOULD complete within 3 seconds of the payment record being created. This is a target, not a hard cutoff — where the LFI's controls require longer (for example, referral for manual review), the payment remains in Pending and the final outcome is reflected when available. A payment MUST NOT be rejected solely because screening exceeded 3 seconds.

2

Screening failure — notify API Hub

If a screening check fails, the LFI MUST immediately call PATCH /payment-log/{id} on the API Hub Consent Manager with paymentResponse.status: Rejected and a paymentResponse.RejectReasonCode entry. The entry's Code MUST use the LFI. namespace (the check that failed is in the LFI's systems, not AANI or UAEFTS), matching the pattern ^LFI\.[A-Za-z0-9]+$. The Message MUST be sanitised for onward relay to the TPP — it MUST NOT reveal detection logic, sanctions list matches, or internal case identifiers.

Example:
Code: LFI.ScreeningRejected
Message: Payment rejected by LFI screening controls.

05 Section

Rail Submission

Once the payment has passed screening, the LFI MUST submit it to the domestic rails for processing. AANI is the primary rail for Delegated SCA payments; UAEFTS is the fallback.

#

Rule

Detail

1

Submit to AANI

Once screening has passed, the LFI MUST immediately submit the payment to AANI for processing.

2

Fallback to UAEFTS

If AANI is unavailable for any reason — including the AANI service being degraded or unreachable, or the receiving bank being unable to receive the payment via AANI — the LFI MUST fall back to UAEFTS and submit the payment there. The fallback decision MUST NOT require TPP or customer intervention.

3

Propagate status changes to the API Hub

Whenever a rail status change at AANI or UAEFTS maps to a change in the payment's Open Finance status, the LFI MUST immediately call PATCH /payment-log/{id} on the API Hub Consent Manager to update paymentResponse.status to the new Open Finance status. Rail statuses that are deliberately not mapped (see Payment Status) do not require a PATCH; the mapping document is the source of truth for which rail transitions are reportable.

4

paymentTransactionId propagation

Once AANI or UAEFTS assigns the end-to-end identifier for the payment (the IPP identifier for AANI, or the equivalent for UAEFTS), the LFI MUST include it as paymentTransactionId on the next PATCH /payment-log/{id} — ideally on the same PATCH as the accompanying status transition. Once set, paymentTransactionId MUST NOT be changed. Note that paymentTransactionId identifies the payment instruction on the rail and is distinct from the Bank Data Sharing transactionId (which identifies a ledger entry).

5

Rail rejection — reject reason code

If the payment is rejected by AANI or UAEFTS, the LFI MUST populate paymentResponse.RejectReasonCode on the PATCH /payment-log/{id} call. The Code MUST use the namespace of the rail that rejected the payment (AANI. or FTS., matching the spec pattern ^(AANI|FTS)\.[A-Za-z0-9]+$), with the specific reason code mapped directly from the rail's originating rejection code. The Message MUST be sanitised for onward relay to the TPP.

Example:
Code: AANI.AM04
Message: Payment request cannot be executed as insufficient funds at debtor account.

6

PATCH /payment-log/{id} delivery

The LFI MUST treat Consent Manager updates as durable — status, paymentTransactionId, and RejectReasonCode changes cannot be dropped. If a PATCH fails with a transient error (HTTP 5xx, connection error, or timeout), the LFI MUST retry with exponential backoff until the update is accepted; updates that cannot be delivered immediately MUST be queued and retried rather than abandoned. A PATCH rejected with a 4xx response indicates a client-side issue that retry will not fix — the LFI MUST NOT retry in this case and MUST raise the failure for operational investigation.

06 Endpoint

Payment Status Retrieval

GET/payments/{paymentId}

The TPP may use GET /payments/{paymentId} to retrieve the current status of a payment it has initiated. The API Hub validates the access token and consent, then forwards the request to your Ozone Connect endpoint.

#

Rule

Detail

1

Sustain period

The LFI MUST continue to serve GET /payments/{paymentId} for at least 1 year from the creation date of the payment. Within this window, the endpoint MUST return the current Status of the payment, reflecting any subsequent state changes (e.g. screening outcomes, rail settlement, reversal).

2

Status consistency with the API Hub

The Status returned by GET /payments/{paymentId} MUST exactly match the status most recently PATCHed to the API Hub Consent Manager via PATCH /payment-log/{id}. The LFI is responsible for keeping the two representations in lockstep — any status change in the LFI's systems MUST be reflected on both surfaces before the change is observable to the TPP.

3

paymentTransactionId consistency

Once the rail has assigned an end-to-end identifier and the LFI has PATCHed it to the Consent Manager, GET /payments/{paymentId} MUST return the same paymentTransactionId. Before the rail has assigned one, paymentTransactionId MUST be omitted from the response rather than returned as an empty string.

Delegated SCA — Requirements v2.111 min read