API Integration Guide

Authentication Flow

UAE Open Finance uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) and Financial-grade API (FAPI) security profiles. Here's the typical authentication flow:

Authorization Request

TPP redirects user to bank's authorization endpoint

→

User Authentication

User authenticates with bank (SCA required)

→

Consent Grant

User reviews and approves data access permissions

→

Authorization Code

Bank redirects back to TPP with auth code

→

Token Exchange

TPP exchanges code for access token

API Endpoints

Account Information APIs

GET /accounts

List all accounts the user has consented to share

GET /accounts/{accountId}

Get details of a specific account

GET /accounts/{accountId}/balances

Get current and available balance

GET /accounts/{accountId}/transactions

Get transaction history with pagination

Payment Initiation APIs

POST /domestic-payments

Initiate a domestic payment

GET /domestic-payments/{paymentId}

Get payment status and details

Confirmation of Payee APIs

POST /funds-confirmation-consents

Create a funds confirmation consent

POST /funds-confirmations

Check if funds are available

Request Headers

All API requests must include the following headers:

Authorization: Bearer {access_token}
x-fapi-auth-date: Sun, 26 Jan 2025 10:00:00 GMT
x-fapi-customer-ip-address: 192.168.1.1
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
x-idempotency-key: FRESCO.21302.GFX.20 (for POST requests)
Content-Type: application/json
Accept: application/json

Example: Get Account Balances

Request

GET /accounts/22289/balances HTTP/1.1
Host: api.bank.ae
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
x-fapi-auth-date: Sun, 26 Jan 2025 10:00:00 GMT
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

{
  "Data": {
    "Balance": [
      {
        "AccountId": "22289",
        "CreditDebitIndicator": "Credit",
        "Type": "InterimAvailable",
        "DateTime": "2025-01-26T10:00:00+04:00",
        "Amount": {
          "Amount": "15000.00",
          "Currency": "AED"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.bank.ae/accounts/22289/balances"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Consent Object

Before accessing account data, you must create a consent request:

{
  "Data": {
    "Permissions": [
      "ReadAccountsBasic",
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadTransactionsBasic",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail"
    ],
    "ExpirationDateTime": "2025-07-26T00:00:00+04:00",
    "TransactionFromDateTime": "2024-07-26T00:00:00+04:00",
    "TransactionToDateTime": "2025-07-26T00:00:00+04:00"
  },
  "Risk": {}
}

Available Permissions

ReadAccountsBasic — Account identification
ReadAccountsDetail — Full account details
ReadBalances — Current and available balances
ReadTransactionsBasic — Transaction amounts and dates
ReadTransactionsDetail — Full transaction details
ReadTransactionsCredits — Credit transactions only
ReadTransactionsDebits — Debit transactions only

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "Code": "400",
  "Id": "93bac548-d2de-4546-b106-880a5018460d",
  "Message": "Bad Request",
  "Errors": [
    {
      "ErrorCode": "UK.OBIE.Field.Missing",
      "Message": "End date is missing",
      "Path": "Data.Permissions",
      "Url": "https://docs.openfinance.ae/errors/field-missing"
    }
  ]
}

Common Error Codes

400 Bad Request — Invalid request format

401 Unauthorized — Invalid or expired token

403 Forbidden — Insufficient permissions

404 Not Found — Resource doesn't exist

429 Too Many Requests — Rate limit exceeded

500 Server Error — Internal bank error

Full API Documentation

For complete API specifications, request/response schemas, and testing tools, visit the official documentation.

View Full Documentation → Trust Framework Directory →