Bank Data Sharing — API Guide 12 min read

Before implementing Bank Data Sharing, ensure the following are in place:

• API Hub onboarded — Your API Hub instance is provisioned and your environment-specific configuration is complete.
• Consent Journey implemented — The Consent Journey API Guide MUST be implemented first. A Bank Data Sharing request cannot be served without an authorized consent, so GET/auth, GET/consents/{consentId}, PATCH/consents/{consentId}, POST/auth/{interactionId}/doConfirm, and POST/auth/{interactionId}/doFail must already be in place.
• Ozone Connect connectivity verified — Bidirectional mTLS connectivity is confirmed between the API Hub and your Ozone Connect base URL. See Connectivity & Certificates.

During consent creation, if your LFI has configured the POST/consent/action/validate endpoint, the API Hub forwards the full consent payload to your Ozone Connect server before the consent is created. The request and response shape, and the overall placement of this call in the consent lifecycle, are covered in the Consent Journey API Guide — Validate the consent.

For Bank Data Sharing consents (consentType: cbuae-account-access-consents), your LFI MUST respond with data.status: invalid in the cases listed in Bank Data Sharing Requirements — Consent Validation.

The remainder of this guide covers the LFI-facing Ozone Connect endpoints that serve each TPP request after the consent is authorized — the shared conventions (field population, request headers, error responses, pagination) followed by the per-endpoint request and response shapes.

Field population

Every field that exists on the LFI's systems, or is derivable from them, MUST be populated in the response. TPPs rely on this data to serve customer use cases end-to-end — a field the LFI omits is a feature the TPP cannot build. The OpenAPI spec marks the minimum required set, but LFIs MUST populate every optional field they hold.

This rule applies to every endpoint in this guide. The endpoint-specific rules in Bank Data Sharing Requirements call out fields that are always required for each endpoint.

Common request headers

All resource endpoints receive the same set of headers from the API Hub. They are listed here and referenced from each endpoint section below.

Token and consent validation have already been performed by the Hub before the request reaches your Ozone Connect endpoint. Your LFI does not re-validate the token or consent — it is trusted to be valid. See Bank Data Sharing Requirements for what your Ozone Connect endpoints must validate.

Common error responses

Every /accounts/{accountId}/… endpoint MUST check the account's status before returning data — if the account is not Active, the endpoint MUST respond with 403 instead of returning the resource. GET/accounts is the only exception: it lists every consented account regardless of status, with the Status field populated so the TPP can observe the current state.

All error bodies MUST include errorCode and errorMessage.

403 — Forbidden

Return 403 using the Account Status Handling mapping:

400 — Bad Request

Return 400 only for a request that is genuinely malformed — not for a well-formed request that simply matches no data. The API Hub enforces the OpenAPI schema before proxying, so most format errors are rejected upstream and rarely reach your Ozone Connect endpoints.

Pagination

GET/accounts/{accountId}/transactions and GET/accounts/{accountId}/statements MUST support pagination. Other list endpoints (/beneficiaries, /direct-debits, /scheduled-payments, /standing-orders, /products, /accounts/{accountId}/customer) MAY support pagination where result sets warrant it.

The LFI implements page-based pagination (page / page-size query params, meta.paginated / meta.totalPages / meta.totalRecords in the response). The API Hub converts this into the Links envelope returned to the TPP.

See Pagination for the full behaviour.

Backs the TPP request GET https://rs1.LFICODE.apihub.openfinance.ae/open-finance/account-information/vx.y/accounts/{AccountId}.

Returns the full details of a single account. The response shape is the same CbuaeAccount returned inside the data array of GET/accounts, wrapped as a single object rather than an array. Data returned here MUST be consistent with what is returned by GET/accounts for the same account.

Request headers

See Common request headers.

Path parameters

Response

Content-Type: application/json

{
  "data": {
    "id": "acc-001",
    "accountType": "Retail",
    "accountSubType": "CurrentAccount",
    "currency": "AED",
    "status": "Active",
    "accountHolderName": "Ahmed Al Mansouri",
    "servicer": {
      "schemeName": "BICFI",
      "identification": "BANKAEAAXXX"
    },
    "accountNumbers": [
      {
        "schemeName": "IBAN",
        "identification": "AE070331234567890123456"
      }
    ],
    "customers": [
      { "id": "cust-001" }
    ],
    "product": {
      "id": "prod-current-01",
      "productName": "Everyday Current Account"
    }
  },
  "meta": {}
}

Errors: see Common error responses.

See the GET /accounts/{accountId} API Reference for the full schema.

Backs the TPP request GET https://rs1.LFICODE.apihub.openfinance.ae/open-finance/account-information/vx.y/accounts/{AccountId}/transactions.

Returns the transactions for a single account, filtered by booking date-time where provided. Pagination is required for this endpoint — see Pagination.

Request headers

See Common request headers. In addition:

Path parameters

Query parameters

Response

Content-Type: application/json

At least two years of transactions MUST be available for retrieval. If no transactions exist within the requested range, return 200 with an empty data array — do not return 404.

The two-year rule is a minimum availability guarantee, not a query limit. An LFI MUST NOT reject a request solely because fromBookingDateTime or toBookingDateTime extends beyond two years into the past, or because the range matches no transactions — return 200 with the matching subset, empty where there is none. An LFI MAY return transactions older than two years where it holds them. 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 — with 400, so the LFI receives only well-formed ranges. See Common error responses.

{
  "data": [
    {
      "accountId": "acc-001",
      "transactionId": "txn-900123",
      "transactionDateTime": "2026-04-12T14:22:11Z",
      "bookingDateTime": "2026-04-12T14:22:11Z",
      "valueDateTime": "2026-04-12T14:22:11Z",
      "transactionType": "POS",
      "subTransactionType": "CardPurchase",
      "creditDebitIndicator": "Debit",
      "status": "Booked",
      "amount": { "amount": "42.50", "currency": "AED" },
      "transactionInformation": "CARREFOUR MALL OF THE EMIRATES",
      "transactionReference": "POS-20260412-900123",
      "balance": {
        "creditDebitIndicator": "Credit",
        "balanceType": "InterimAvailable",
        "amount": { "amount": "12345.67", "currency": "AED" }
      },
      "merchantDetails": {
        "merchantName": "Carrefour",
        "merchantCategoryCode": "5411"
      }
    }
  ],
  "meta": {
    "paginated": true,
    "totalPages": 12,
    "totalRecords": 1187
  }
}

Errors: see Common error responses.

See the GET /accounts/{accountId}/transactions API Reference for the full schema.

Backs the TPP request GET https://rs1.LFICODE.apihub.openfinance.ae/open-finance/account-information/vx.y/accounts/{AccountId}/beneficiaries.

Returns the beneficiaries linked to the account. Only supported for CurrentAccount and Savings — not available for CreditCard, Finance, or Mortgage accounts.

Request headers

See Common request headers.

Path parameters

Query parameters

Response

Content-Type: application/json

If the account holds no beneficiaries, return 200 with an empty data array — do not return 404.

{
  "data": [
    {
      "accountId": "acc-001",
      "beneficiaryId": "ben-00123",
      "beneficiaryType": "Trusted",
      "addedViaOF": false,
      "reference": "Rent March",
      "creditorAccount": {
        "schemeName": "IBAN",
        "identification": "AE220331234567890876543",
        "name": "Fatima Al Zaabi"
      },
      "servicer": {
        "schemeName": "BICFI",
        "identification": "BANKAEAAXXX"
      }
    }
  ],
  "meta": { "totalPages": 1, "totalRecords": 1 }
}

Errors: see Common error responses.

See the GET /accounts/{accountId}/beneficiaries API Reference for the full schema.

Backs the TPP request GET https://rs1.LFICODE.apihub.openfinance.ae/open-finance/account-information/vx.y/accounts/{AccountId}/scheduled-payments.

Returns one-off scheduled payments linked to the account. Only supported for CurrentAccount and Savings.

Request headers

See Common request headers.

Path parameters

Query parameters

Response

Content-Type: application/json

{
  "data": [
    {
      "accountId": "acc-001",
      "scheduledPaymentId": "sp-9981",
      "scheduledType": "Execution",
      "scheduledPaymentDateTime": "2026-04-20T09:00:00Z",
      "instructedAmount": { "amount": "1500.00", "currency": "AED" },
      "creditorAccount": {
        "schemeName": "IBAN",
        "identification": "AE220331234567890876543",
        "name": "Fatima Al Zaabi"
      },
      "creditorReference": "Rent April",
      "debtorReference": "Rent April"
    }
  ],
  "meta": { "totalPages": 1, "totalRecords": 1 }
}

Errors: see Common error responses.

See the GET /accounts/{accountId}/scheduled-payments API Reference for the full schema.

Backs the TPP request GET https://rs1.LFICODE.apihub.openfinance.ae/open-finance/account-information/vx.y/accounts/{AccountId}/product (singular on the TPP side).

Returns the product data associated with the account — fees, charges, rates, rewards, benefits, and eligibility criteria. FinanceRates may be returned as cleartext JSON or as a JWE compact string — see Encrypted FinanceRates.

Request headers

See Common request headers.

Path parameters

Query parameters

Response

Content-Type: application/json

If no product data exists for the account, return 200 with an empty data array.

{
  "data": [
    {
      "accountId": "acc-001",
      "productId": "prod-current-01",
      "productName": "Everyday Current Account",
      "productType": "CurrentAccount",
      "fees": [
        {
          "feeType": "MonthlyMaintenance",
          "amount": { "amount": "25.00", "currency": "AED" }
        }
      ],
      "benefits": [
        { "benefitType": "FreeATMWithdrawals", "description": "Unlimited free ATM withdrawals within the UAE" }
      ]
    }
  ],
  "meta": { "totalPages": 1, "totalRecords": 1 }
}

Errors: see Common error responses.

See the GET /accounts/{accountId}/products API Reference for the full schema.

Backs the TPP request GET https://rs1.LFICODE.apihub.openfinance.ae/open-finance/account-information/vx.y/parties — "parties" on the TPP side, "customer" on Ozone Connect.

Returns the customer record for the authenticated customer. Unlike /accounts/{accountId}/customer, this endpoint is not scoped to a specific account.

The response is based on OpenID Connect for Identity Assurance 1.0. See Identity Assurance Claims.

Request headers

See Common request headers. o3-psu-identifier is the operative header for this endpoint.

Response

Content-Type: application/json

{
  "data": {
    "id": "cust-001",
    "customerCategory": "Retail",
    "verifiedClaims": [
      {
        "verification": { "trustFramework": "UAE.FI" },
        "claims": {
          "identityType": "Person",
          "fullName": "Ahmed Al Mansouri",
          "givenName": "Ahmed",
          "familyName": "Al Mansouri",
          "emiratesId": "784-1985-1234567-1",
          "emiratesIdExpiryDate": "2029-06-15",
          "residentialAddress": {
            "streetAddress": "Building 12, Marina Walk",
            "locality": "Dubai",
            "country": "AE"
          }
        }
      }
    ]
  },
  "meta": {}
}

See the GET /customer API Reference for the full schema.