Built by the community
Navigation
Metrics
Program
Service DeskPricingPoliciesDocument RepositoryLive Ecosystem
Developer Docs
TPP — Open Finance StandardsLFI — Integration GuideAPI SpecsKnowledge BaseRelease Notes & Erratas
NewsGitHub
Validate · Enforce · Trust

Bank Data Sharing — Requirements v2.112 min read

The Authentication requirements, Authorization requirements, and User Journeys must be adhered to.

The tables below list the rules that apply to Bank Data Sharing. All request validation of the TPP's credentials, access token, and consent is performed by the Hub before your Ozone Connect endpoints are called. The rules below cover what your Ozone Connect endpoints must validate and what they must return. Two cross-cutting checks apply to every endpoint under /accounts/{accountId} and /accounts/{accountId}/…: Account Access Validation (the account is held by the resolved customer) and Account Status Handling (the account is in a readable state).

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. The field names in the rules below match the Ozone Connect newConsent payload the Hub delivers — standardVersion sits at the top level of the consent object; BaseConsentId, AccountType, AccountSubType, and Permissions sit under consentBody.Data.

#
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 data sharing requests. If you do not support that version for the Account Information 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
Unsupported AccountType
If the consent's AccountType array contains a value that is not supported by the API Hub integration the consent was received on, respond with invalid. Each API Hub integration is scoped to a single segment (Retail, SME, or Corporate). If the LFI serves multiple segments, each segment MUST be configured as a separate API Hub integration because the API Hub has a single authorization endpoint. Validate that every requested AccountType is within scope of the integration that received the consent.
3
Unsupported AccountSubType
If the consent's AccountSubType array contains a value not supported by this LFI, respond with invalid. For example, if the LFI does not offer Mortgage products but the consent requests Mortgage, the consent MUST be rejected at validation.
4
Unsupported permissions
If the consent includes permissions that reference an endpoint the LFI has not yet delivered, respond with invalid. For example, if the consent includes ReadStandingOrdersBasic or ReadStandingOrdersDetail but GET /accounts/{AccountId}/standing-orders is not yet available, the consent MUST be rejected at validation.
5
Invalid BaseConsentId
If the consent includes a BaseConsentId, validate that:
  • The BaseConsentId references an existing consent known to the LFI.
  • The referenced consent is a Data Sharing consent (authorization_details[0].type is urn:openfinanceuae:account-access-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.
02 Section

Authorization — Account Selection

The generic Authorization requirements apply to this journey. The rules below cover the additional account selection logic specific to Bank Data Sharing. During the consent authorization journey, the customer selects which of their accounts to share with the TPP. The LFI is responsible for presenting the eligible accounts and applying any filters the TPP has specified in the consent.

#
Field
Rule
1
consent.AccountType
If the consent specifies AccountType, only present accounts whose type matches one of the specified values (Retail, SME, Corporate). If not specified, present accounts of all types supported by this API Hub integration.
2
consent.AccountSubType
If the consent specifies AccountSubType, only present accounts whose subtype matches one of the specified values. If not specified, present accounts of all subtypes.
3
No eligible accounts
If the authenticated customer does not hold any accounts matching the requested consent parameters (e.g. AccountType, AccountSubType, or the permissions requested), 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
Multiple selection
The account selection screen must allow the customer to select more than one account. A consent with no accounts selected must not be authorised.
03 Endpoint

List Accounts

GET/accounts
#
Field
Rule
1
accountIds
Return the accounts whose id matches one of the values in the accountIds query parameter. Populate the Status field on each account so the TPP can see the current state.
2
Data completeness
All fields that exist or are derivable from your systems must be populated on each account. All fields marked as required in the OpenAPI spec must be present. This includes accountHolderName, status, currency, accountType, and accountSubType where held.
3
accountNumbers
Must contain at least one entry. schemeName and identification are required on each entry.
4
accountNumbers.schemeName
Must reflect the account identifier type: IBAN for CurrentAccount and Savings; MaskedPAN for CreditCard; MortgageReference for Mortgage; FinanceReference for Finance.
5
customers
For non-business accounts, customers must contain at least one entry. For business accounts, populate businessCustomer instead.
6
AccountSubType
Supported for all account subtypes: CurrentAccount, Savings, CreditCard, Finance, and Mortgage.
7
Account access
For every accountId in the accountIds query parameter, validate that the account is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before returning — if any of the requested accounts is not held by the customer, return 403 with errorCode: Consent.PermanentAccountAccessFailure.
8
Account status
Return all consented accounts regardless of Status. Accounts that are Inactive, Dormant, Suspended, Unclaimed, Deceased, or Closed MUST still be included — the Status field on each account reflects the current state so the TPP can observe it. This endpoint is exempt from the Account Status Handling mapping.
04 Endpoint

Get Account

GET/accounts/{accountId}
#
Field
Rule
1
account
Return the account whose id matches the value in the accountId path parameter.
2
Data completeness
All fields that exist or are derivable from your systems must be populated, consistent with what is returned by GET /accounts for the same account. All fields marked as required in the OpenAPI spec must be present.
3
accountNumbers
Must contain at least one entry. schemeName and identification are required on each entry.
4
accountNumbers.schemeName
Must reflect the account identifier type: IBAN for CurrentAccount and Savings; MaskedPAN for CreditCard; MortgageReference for Mortgage; FinanceReference for Finance.
5
AccountSubType
Supported for all account subtypes: CurrentAccount, Savings, CreditCard, Finance, and Mortgage.
6
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
7
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
05 Endpoint

List Balances

GET/accounts/{accountId}/balances
#
Field
Rule
1
account
Return the balances for the account whose id matches the value in the accountId path parameter.
2
Data completeness
All balance types that exist for the account must be returned. All fields marked as required in the OpenAPI spec must be present on each record, including accountId, balanceType, amount (with amount and currency), creditDebitIndicator, and timestamp.
3
Multiple balance types
Return one record per distinct balance type held for the account. More than one record per account is permitted and expected where multiple balance types exist. Include creditLines where applicable.
4
InterimAvailable
For CurrentAccount and Savings accounts, a record with balanceType: InterimAvailable must always be included. This is the real-time available balance on the account.
5
AccountSubType
Supported for all account subtypes: CurrentAccount, Savings, CreditCard, Finance, and Mortgage.
6
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
7
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
06 Endpoint

List Beneficiaries

GET/accounts/{accountId}/beneficiaries
#
Field
Rule
1
account
Return the beneficiaries linked to the account whose id matches the value in the accountId path parameter.
2
Required fields
Every beneficiary record must include accountId, beneficiaryId, beneficiaryType, and addedViaOF.
3
Data completeness
All fields that exist or are derivable must be populated, including creditorAccount (with schemeName and identification), servicer, and reference where held.
4
Empty result
If the account holds no beneficiaries, return 200 with an empty data array. Do not return 404.
5
AccountSubType
Only supported for CurrentAccount and Savings accounts. Not available for CreditCard, Finance, or Mortgage accounts.
6
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
7
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
07 Endpoint

List Direct Debits

GET/accounts/{accountId}/direct-debits
#
Field
Rule
1
account
Return the direct debits linked to the account whose id matches the value in the accountId path parameter.
2
Required fields
Every direct debit record must include accountId, directDebitId, directDebitStatusCode, mandateIdentification, name, and frequency.
3
Data completeness
Include previousPaymentDateTime and previousPaymentAmount where available.
4
Empty result
If the account holds no direct debits, return 200 with an empty data array. Do not return 404.
5
AccountSubType
Only supported for CurrentAccount and Savings accounts. Not available for CreditCard, Finance, or Mortgage accounts.
6
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
7
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
08 Endpoint

List Scheduled Payments

GET/accounts/{accountId}/scheduled-payments
#
Field
Rule
1
account
Return the scheduled payments linked to the account whose id matches the value in the accountId path parameter.
2
Required fields
Every scheduled payment record must include accountId, scheduledPaymentId, scheduledType, scheduledPaymentDateTime, and instructedAmount (with amount and currency).
3
Data completeness
Include creditorAccount (with schemeName and identification), creditorAgent, creditorReference, and debtorReference where held.
4
Empty result
If the account holds no scheduled payments, return 200 with an empty data array. Do not return 404.
5
AccountSubType
Only supported for CurrentAccount and Savings accounts. Not available for CreditCard, Finance, or Mortgage accounts.
6
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
7
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
09 Endpoint

List Standing Orders

GET/accounts/{accountId}/standing-orders
#
Field
Rule
1
account
Return the standing orders linked to the account whose id matches the value in the accountId path parameter.
2
Required fields
Every standing order record must include accountId, standingOrderId, frequency, firstPaymentDateTime, standingOrderStatusCode, and firstPaymentAmount (with amount and currency).
3
Data completeness
Include nextPaymentDateTime, nextPaymentAmount, lastPaymentDateTime, lastPaymentAmount, finalPaymentDateTime, finalPaymentAmount, numberOfPayments, creditorAccount, creditorAgent, and standingOrderType where held.
4
Empty result
If the account holds no standing orders, return 200 with an empty data array. Do not return 404.
5
AccountSubType
Only supported for CurrentAccount and Savings accounts. Not available for CreditCard, Finance, or Mortgage accounts.
6
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
7
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
10 Endpoint

List Statements

GET/accounts/{accountId}/statements
#
Field
Rule
1
account
Return the statements for the account whose id matches the value in the accountId path parameter.
2
fromStatementDate
If provided, return only statements with a statement date on or after this date. Filtering is open-ended (from the earliest available statement) if not provided.
3
toStatementDate
If provided, return only statements with a statement date on or before this date. Filtering is open-ended (to the latest available statement) if not provided.
4
Required fields
Every statement record must include accountId, accountSubType, statementId, statementDate, openingDate, closingDate, openingBalance (with creditDebitIndicator, amount, and currency), closingBalance (with creditDebitIndicator, amount, and currency), and summary (with creditDebitIndicator, subTransactionType, amount, and count per entry).
5
Data completeness
All fields that exist or are derivable for each statement must be returned, including creditLine where applicable.
6
Data retention
The endpoint must support retrieval of at least the last two years of statements. This is a minimum availability floor, not a query limit — the endpoint MAY return statements older than two years where it holds them.
7
Range handling
A request whose fromStatementDate or toStatementDate extends beyond two years into the past is well-formed and MUST NOT be rejected — return 200 with the matching subset (empty where none).
8
Empty result
If no statements exist within the requested range, return 200 with an empty data array. Do not return 404.
9
Invalid range
The API Hub rejects malformed date-range requests before proxying — an unparseable date, a contradictory range (fromStatementDate after toStatementDate), or a toStatementDate in the future — returning 400 with errorCode: Resource.InvalidFormat. The endpoint therefore receives only well-formed ranges and does not re-validate them.
10
Pagination
Pagination must be supported. meta.paginated, meta.totalRecords, and meta.totalPages must be accurate.
11
AccountSubType
Supported for all account subtypes: CurrentAccount, Savings, CreditCard, Finance, and Mortgage.
12
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
13
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
11 Endpoint

List Transactions

GET/accounts/{accountId}/transactions
#
Field
Rule
1
account
Return the transactions for the account whose id matches the value in the accountId path parameter.
2
fromBookingDateTime
If provided, return only transactions booked on or after this date-time. Filtering is open-ended if not provided.
3
toBookingDateTime
If provided, return only transactions booked on or before this date-time. Filtering is open-ended if not provided.
4
Timezone
Any timezone offset in fromBookingDateTime or toBookingDateTime must be ignored. Filter against local booking date-time only.
5
Required fields
Every transaction record must include accountId, transactionId, transactionDateTime, transactionType, subTransactionType, creditDebitIndicator, status, bookingDateTime, and amount (with amount and currency).
6
Data completeness
All fields that exist or are derivable must be populated, including balance (with creditDebitIndicator, balanceType, and amount) where available, merchantDetails, creditorAccount, debtorAccount, cardInstrument, currencyExchange, flags, and paymentPurposeCode where held.
7
Transaction context
transactionInformation and transactionReference must be provided where held to give the TPP meaningful context for the transaction.
8
Data retention
The endpoint must support retrieval of at least the last two years of transactions. This is a minimum availability floor, not a query limit — the endpoint MAY return transactions older than two years where it holds them.
9
Range handling
A request whose fromBookingDateTime or toBookingDateTime extends beyond two years into the past is well-formed and MUST NOT be rejected — return 200 with the matching subset (empty where none).
10
Empty result
If no transactions exist within the requested range, return 200 with an empty data array. Do not return 404.
11
Invalid range
The API Hub rejects malformed date-range requests before proxying — an unparseable date-time, a contradictory range (fromBookingDateTime after toBookingDateTime), or a toBookingDateTime in the future — returning 400 with errorCode: Resource.InvalidFormat. The endpoint therefore receives only well-formed ranges and does not re-validate them.
12
Pagination
Pagination must be supported. meta.paginated, meta.totalRecords, and meta.totalPages must be accurate.
13
AccountSubType
Supported for all account subtypes: CurrentAccount, Savings, CreditCard, Finance, and Mortgage.
14
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
15
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
12 Endpoint

List Products

GET/accounts/{accountId}/products
#
Field
Rule
1
account
Return the products associated with the account whose id matches the value in the accountId path parameter.
2
Data completeness
All product data that exists or is derivable from your systems must be returned, including fees, charges, rates, rewards, benefits, and eligibility criteria where held. Every field other than FinanceRates is always returned in cleartext, regardless of which response shape is chosen for FinanceRates (see below).
3
FinanceRates — permission gating
Only include the FinanceRates field on a Product record when the consent carries the ReadProductFinanceRates permission. If the permission is absent, omit the field entirely — do not substitute null, an empty object, or a placeholder JWE. See Encrypted FinanceRates — Step 1 for the permission-check pattern.
4
FinanceRates — response shape
When ReadProductFinanceRates is present, the LFI MAY return FinanceRates as either a cleartext AEProductFinanceRates JSON object or as an AEJwe compact serialisation string. The choice is at the LFI's discretion, typically per product type (e.g. cleartext for deposit accounts, JWE for credit cards, finance accounts, and mortgages where the rate is commercially sensitive).
5
FinanceRates — cleartext path
If returning cleartext, serve the AEProductFinanceRates object alongside the rest of the Product record in the standard JSON response, exactly as every other field on this endpoint is served. No additional handling — no OTP, no encryption, no rate limits beyond the standard ones — applies.
6
FinanceRates — JWE path
If returning an encrypted JWE, the LFI MUST follow the Encrypted FinanceRates guide in full — generate a fresh one-time code per call, deliver it to the customer on a channel the LFI controls, encrypt the cleartext AEProductFinanceRates as a PBES2-HS512+A256KW / A256GCM JWE with the OTP as the password, embed a 30-minute exp in the plaintext, and enforce the per-(consent, account) rate limits (60-second interval, 12 fresh OTPs per rolling 24 hours) by rejecting breaches with 429 Too Many Requests and a Retry-After header.
7
Empty result
If no product data exists for the account, return 200 with an empty data array. Do not return 404.
8
AccountSubType
Supported for all account subtypes: CurrentAccount, Savings, CreditCard, Finance, and Mortgage.
9
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
10
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
13 Endpoint

Get Customer

GET/accounts/{accountId}/customer
#
Field
Rule
1
account
Return the customers associated with the account whose id matches the value in the accountId path parameter.
2
Multiple customers
Return one record per customer associated with the account. Joint accounts must return a record for each joint holder.
3
Required fields
Every customer record must include id, claims verifiedClaims, customerType, customerCategory, and accountRole.
4
Person claims
For retail customers, verifiedClaims[].claims must include identityType, fullName, givenName, familyName, emiratesId, emiratesIdExpiryDate, and residentialAddress. Include all optional fields (middleName, birthDate, mobileNumber, email, nationality, etc.) where held.
5
Corporate claims
For SME/Corporate customers, verifiedClaims[].claims must include identityType, businessName, and tradeLicenceNumber. Include all optional fields (taxIdentificationNumber, dateOfIncorporation, countryOfIncorporation, corporateAddress, etc.) where held.
6
Data completeness
All fields that exist or are derivable from your systems must be populated on each customer record.
7
Empty result
If no customer records are associated with the account, return 200 with an empty data array. Do not return 404.
8
Account access
Validate that the account in the accountId path parameter is held by the customer resolved from o3-psu-identifier. Apply the Account Access Validation check before status handling — a non-held account MUST return 403 with errorCode: Consent.PermanentAccountAccessFailure.
9
Account status
If the account is not Active, do not return the resource. Apply the Account Status Handling mapping to return 403 with the corresponding errorCode and errorMessage.
14 Endpoint

Get Customer

GET/customer
#
Field
Rule
1
Customer identification
Identify the customer from the o3-psu-identifier header passed by the Hub.
2
Required fields
The customer record must include id, verifiedClaims, and customerCategory.
3
Person claims
For retail customers, verifiedClaims[].claims must include identityType, fullName, givenName, familyName, emiratesId, emiratesIdExpiryDate, and residentialAddress. Include all optional fields where held.
4
Corporate claims
For SME/Corporate customers, verifiedClaims[].claims must include identityType, businessName, and tradeLicenceNumber. Include all optional fields where held.
5
Data completeness
All fields that exist or are derivable from your systems must be populated.
15 Section

Account Access Validation

Every endpoint that takes an account identifier — whether as the accountId path parameter under /accounts/{accountId} and /accounts/{accountId}/…, or as values in the accountIds query parameter on GET /accounts — MUST validate that each account is held by the customer resolved from the o3-psu-identifier header before applying the per-endpoint rules above. Account ownership is authoritative on the LFI side — the Hub stores the accountIds patched onto the consent at authorization, but the LFI is the source of truth for which accounts the customer actually holds. If the patched set ever drifted from the customer's actual holdings, only the LFI can detect it.

If any requested account is not held by the resolved customer, return 403 with errorCode: Consent.PermanentAccountAccessFailure and errorMessage: The account is permanently inaccessible. Apply this check before the Account Status Handling mapping — a non-held account MUST NOT leak status information.

GET /customer is exempt — it is resolved from o3-psu-identifier and not scoped to a specific account.

16 Section

Account Status Handling

The rules above assume the account is in a readable state. The table below summarises how each value of AEAccountStatusCode maps to a response for endpoints under /accounts/{accountId}.

Status
Readable
Response if not readable
Active
✅
—
Inactive
✅
—
Dormant
✅
—
Suspended
❌
403 with errorCode: Consent.AccountTemporarilyBlocked and errorMessage: The account is temporarily blocked.
Unclaimed
❌
403 with errorCode: Consent.PermanentAccountAccessFailure and errorMessage: The account is permanently inaccessible.
Deceased
❌
403 with errorCode: Consent.PermanentAccountAccessFailure and errorMessage: The account is permanently inaccessible.
Closed
❌
403 with errorCode: Consent.PermanentAccountAccessFailure and errorMessage: The account is permanently inaccessible.

GET /accounts is exempt from this mapping — it returns all consented accounts regardless of status, with the Status field populated so the TPP can see the current state.