Versions Compared

Version Old Version 1 New Version Current
Changes made by

Chris Michael

Gavin Wong

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Expand
titleMENU
Table of Contents
stylenone

1. API Flows

1.1 Step 1: Agree Account Access Consent

The flow MUST begin with a User who provides consent to a TPP to access their account information from a LFI that they already have a relationship.

1.2 Step 2: Authorize Account Access Consent

The TPP MUST now request the User to authorize the consent. Please refer to the Authentication and Authorization , to review the supported Authorization Flows.

...

A TPP MAY be a broker for data to other parties, so it is valid for a User to have multiple consentsfor the same resource(s), with different consent or authorization parameters agreed upon.

1.2.1 Security and Access Control

Authorization Code Grant

The TPP MUST use an authorization code grant to obtain a token to access all other API resources.

1.3 Step 3: Access Data

1.3.1 Request Data

The TPP MUST have a valid access token (with scope) from the OFP authorization server.

...

The OFP MUST return an API response when provided with a valid access token request from the TPP.

2. Sequence Diagram

The flows illustrate the API interactions completing successfully, with no API Errors.

...

3. Examples

The following are non-normative examples of API access and usage of the Account Information API.

3.1 The TPP Redirects the User to Authorize Account Access Consent

3.1.1 Request: TPP Uses RAR (Rich Authorization Request) via a PAR (Pushed Authorization Request) Endpoint with the OFP to Obtain a Request URI

Create a RAR Request JWT.

...

Code Block
POST /open-finance/v1/par HTTP/1.1
Host: auth1.openfinanceplatform.ae
Content-Type: application/x-www-form-urlencoded
Accept: application/json
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiJ9.ew0KICAiaXNzIjogImM4NDIyNzg3LTFkZmYtNDI0ZC1iNjIwLTM1NmMwODcwYmVkNCIsDQogICJzdWIiOiAiYzg0MjI3ODctMWRmZi00MjRkLWI2MjAtMzU2YzA4NzBiZWQ0IiwNCiAgImF1ZCI6ICJhdXRoMS5sYWIub3BlbmJhbmtpbmcuc2EiLA0KICJqdGkiOiAiYThmZDQ2ZjctYTNiMy00MGQ5LTk2ZjctNDk1YmEyMGFiMTZmIiwNCiAgImV4cCI6IDE1MTYyMzkwMjINCn0.nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI
&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImU0Y2U3N2M0OThlNzcwMDBhMjVhYTdiNDBlNGE4M2Y5In0.eyJpc3MiOiJzNkJoZFJrcXQzIiwiaWF0IjoxNjY5MzkzMTU0LCJleHAiOjE2NjkzOTM0OTYsIm5iZiI6IjE2NjkzOTMxNTQiLCJhdWQiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9sZmkubGFiLm9wZW5iYW5raW5nLmFlL2F1dGgiLCJzY29wZSI6Im9wZW5pZCBhY2NvdW50cyIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJhdXRob3JpemF0aW9uX2RldGFpbHMiOlt7IlR5cGUiOiJBY2NvdW50QWNjZXNzQ29uc2VudCIsIkRhdGEiOnsiQ29uc2VudElkIjoiMzk5ZTAwNjUtOTkwNy00MmNjLTgyYjktMWVjNGYyNzNlM2U5IiwiQ3JlYXRpb25EYXRlVGltZSI6IjIwMjQtMDMtMjdUMTU6Mjc6MTMrMDMwMCIsIkNvbnNlbnRTdGF0dXMiOiJBdXRob3JpemVkIiwiQ29uc2VudFN0YXR1c1VwZGF0ZURhdGVUaW1lIjoiMjAyNC0wMy0yN1QxNjoyNzoxMyswMzAwIiwiUGVybWlzc2lvbnMiOlsiUmVhZEFjY291bnRzQmFzaWMiLCJSZWFkQWNjb3VudHNEZXRhaWwiLCJSZWFkQmFsYW5jZXMiLCJSZWFkQmVuZWZpY2lhcmllc0Jhc2ljIiwiUmVhZEJlbmVmaWNpYXJpZXNEZXRhaWwiLCJSZWFkVHJhbnNhY3Rpb25zQmFzaWMiLCJSZWFkVHJhbnNhY3Rpb25zRGV0YWlsIiwiUmVhZFRyYW5zYWN0aW9uc0NyZWRpdHMiLCJSZWFkVHJhbnNhY3Rpb25zRGViaXRzIiwiUmVhZFNjaGVkdWxlZFBheW1lbnRzQmFzaWMiLCJSZWFkU2NoZWR1bGVkUGF5bWVudHNEZXRhaWwiLCJSZWFkRGlyZWN0RGViaXRzIiwiUmVhZFN0YW5kaW5nT3JkZXJzQmFzaWMiLCJSZWFkU3RhbmRpbmdPcmRlcnNEZXRhaWwiXSwiQXV0aG9yaXphdGlvbkV4cGlyYXRpb25UaW1lV2luZG93IjoiNzIwOjAwOjAwIiwiRXhwaXJhdGlvbkRhdGVUaW1lIjoiMjAyNC0wMy0yOFQxNToyNzoxMyswMzAwIiwiVHJhbnNhY3Rpb25Gcm9tRGF0ZVRpbWUiOiIyMDI0LTAzLTI1VDEyOjE5OjI0KzAzMDAiLCJUcmFuc2FjdGlvblRvRGF0ZVRpbWUiOiIyMDI0LTAzLTI3VDEyOjE5OjI0KzAzMDAiLCJBY2NvdW50VHlwZSI6WyJVQUVPRi5SZXRhaWwiXSwiQWNjb3VudFN1YlR5cGUiOlsiQ3VycmVudEFjY291bnQiXSwiQ29uc2VudFB1cnBvc2UiOlsiQWNjb3VudCBBZ2dyZWdhdGlvbiIsIkUtU3RhdGVtZW50Il19fV19.8T2xivs2zqFdxyrs8h3TWsMxigzk9QcsamU9Dj-2GDs

3.1.2 Response: The OFP Provides the Request URI for the TPP

Code Block
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache, no-store
{
  "request_uri": "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c",
  "expires_in": 60
}

3.2 The TPP Redirects the User to Their LFI with the Request URI to Authorize the Consent

Code Block
GET /auth?client_id=c8422787-1dff-424d-b620-356c0870bed4&request_uri=urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c
Host: openbanking.lfi.ae

3.3 The User Logs into Their LFI, Reviews and Authorizes the Consent Request, and Confirms the Accounts They Want to Share with the TPP

The LFI confirms account access consent in the OFP.

Code Block
POST /auth/aac-1a672e83-d1e5-42bc-b8e1-60a490ec52fd/aac/doConfirm
host: auth1.openfinanceplatform.ae
Content-Type: application/x-www-form-urlencoded
accounts=f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115
&accounts=bed6cb83-956e-4795-86c3-0f4254ae1cab
&accounts=528b9f0c-c4e1-45fd-8f28-ab53fda4c850
&accounts=fe1e15fe-d4aa-4b4c-9ce0-e69bbf901fa6
&accounts=802d03c3-4ac5-4809-8c1e-f9f046e314e4
&accounts=02d19fb7-cf51-4b9a-a958-77701120da3c

3.4 The LFI Returns an Authorization Code to the TPP

Code Block
302 Found
Location: https://openbanking.tpp1.ae/simple-redirect-url?
code=ce2aeabf-599c-4475-9171-1f6d8c1a49dc
&state=2616df22-899e-468b-b7af-927145b067cc

3.5 The TPP Exchanges the Authorization Code for an Account API Access Token with the OFP

Code Block
POST /token HTTP/1.1
Host: as1.openfinanceplatform.ae
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=authorization_code
&code=ce2aeabf-599c-4475-9171-1f6d8c1a49dc
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiJ9.ew0KICAiaXNzIjogImM4NDIyNzg3LTFkZmYtNDI0ZC1iNjIwLTM1NmMwODcwYmVkNCIsDQogICJzdWIiOiAiYzg0MjI3ODctMWRmZi00MjRkLWI2MjAtMzU2YzA4NzBiZWQ0IiwNCiAgImF1ZCI6ICJhdXRoMS5sYWIub3BlbmJhbmtpbmcuc2EiLA0KICJqdGkiOiAiYThmZDQ2ZjctYTNiMy00MGQ5LTk2ZjctNDk1YmEyMGFiMTZmIiwNCiAgImV4cCI6IDE1MTYyMzkwMjINCn0.nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI
&redirect_uri=https%3A%2F%2Fopenbanking.tpp1.ae%2Fsimple-redirect-url

3.6 The OFP Returns an Access Token, Refresh Token, and ID Token to the TPP

Code Block
HTTP/1.1 200 OK
Content-Type:application/json
{
    "access_token": "caa1b60d-61ff-4cd8-a4e1-2d18c8696de0",
    "expires_in": 432000,
    "token_type": "Bearer",
    "scope": "openid%20accounts",
    "state": "2616df22-899e-468b-b7af-927145b067cc",
    "refresh_token": "266f5f15-eb81-4a02-bf05-e25063ca445f",
    "id_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6IkM4a3FRRlZoUFVOUnZTN1ljamZBSEVSTEVDZEFfamZENXJjb1NXVkMwY2sifQ.eyJzdWIiOiJhYWMtMWE2NzJlODMtZDFlNS00MmJjLWI4ZTEtNjBhNDkwZWM1MmZkIiwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjoiYWFjLTFhNjcyZTgzLWQxZTUtNDJiYy1iOGUxLTYwYTQ5MGVjNTJmZCIsInBzdV9pZGVudGlmaWVycyI6eyJjb21wYW55SWQiOiIxMjM0NSJ9LCJpc3MiOiJodHRwczovL2F1dGgxLmxhYi5vcGVuYmFua2luZy5zYSIsImF1ZCI6ImM4NDIyNzg3LTFkZmYtNDI0ZC1iNjIwLTM1NmMwODcwYmVkNCIsImlhdCI6MTY1OTg2NDEzMywiZXhwIjoxNjU5ODY1MDMzLCJub25jZSI6ImZmMzljMGQxLTIyN2EtNGM3My1iYjA1LTA4NDY0ZjA1MmU4NSIsImF1dGhfdGltZSI6MTY1OTg2NDEzMywiYXpwIjoiYzg0MjI3ODctMWRmZi00MjRkLWI2MjAtMzU2YzA4NzBiZWQ0IiwicmVmcmVzaF90b2tlbl9leHBpcmVzX2F0IjoxNjY3NjQwMTMzLCJjX2hhc2giOiI5UWhXZVlzWnd6NzF0NWhjdlI2OU5BIiwic19oYXNoIjoiNHN0R0QtYTFjS3dFSjVwWFZYOEdnUSIsImFjciI6InVybjpvcGVuYmFua2luZzpwc2QyOnNjYSJ9.AfunjbLyzOMQXtZfAl4563cKxTYbXhzZk5IFrJ864w1aF9_XpIQe1iH5H17xIXL_1XmjbPiPMzx55025NMyDOMwPSRBDu9bIb37EyUlVVtVevxxwVeyOixcOx-NoNMHO4qTKyznhCM_oJmNmq5n8N9xSbmyJSGDIusGiiyXyNt0egnK4xkvPFwri4FJd3IUIdUWOCuUO9RlckBQottUiyo4UazrAaShpn4GIsl_1fj8U2Ga5v4t_6jRG7oEndwQoDruLrftFnwvDWJYD2NSm5LKUb2z4HTb-89aPihcGpCrSrnxqyB6kiAculoJAhZhC8TBY40G3l-6qjc5Ey71JHA"
}

The TPP can now request account resources using the access token.

3.7 Get a List of Accounts

3.7.1 Request: Accounts Resource

Code Block
GET /open-finance/account-information/2024.03.11-draft1/accounts HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

3.7.2 Response: Accounts Resource

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
  "Data": {
    "Account": [
      {
        "AccountId": "f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115",
        "AccountHolderName": "Hamad Ali",
        "AccountHolderShortName": "",
        "Status": "Active",
        "Currency": "AED",
        "AccountType": "UAEOF.Retail",
        "AccountSubType": "CurrentAccount",
        "Nickname": "CurrentAC",
        "OpeningDate": "2021-01-28T15:27:13+0300",
        "AccountIdentifiers": [
          {
            "IdentificationType": "UAEOF.IBAN",
            "Identification": "SA4420000001234567891234",
            "Name": "Hamad Ali"
          }
        ],
        "Servicer": {
          "IdentificationType": "UAEOF.BICFI",
          "Identification": "SASAMA"
        }
      },
      {
        "AccountId": "g91d07d0-6d8f-4e0e-9fb4-0ac61f84e444",
        "AccountHolderName": "Hamad Ali",
        "AccountHolderShortName": "",
        "Status": "Active",
        "Currency": "USD",
        "AccountType": "UAEOF.Retail",
        "AccountSubType": "Savings",
        "Nickname": "SavingsAC",
        "OpeningDate": "2021-01-28T15:27:13+0300",
        "AccountIdentifiers": [
          {
            "IdentificationType": "UAEOF.IBAN",
            "Identification": "SA4420000001234567890001",
            "Name": "Hamad Ali"
          }
        ],
        "Servicer": {
          "IdentificationType": "UAEOF.BICFI",
          "Identification": "SASAMA"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://rs1.openfinanceplatform.ae/open-finance/account-information/2024.03.11-draft1/accounts"
  },
  "Meta": {}
}

3.8 Get Balances for an Account

3.8.1 Request: accounts/{AccountId}/balances resource

Code Block
GET /open-finance/account-information/2024.03.11-draft1/accounts/f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115/balances HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Accept: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

3.8.2 Response: accounts/{AccountId}/balances resource

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
  "Data": {
    "AccountId": "f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115",
    "Balance": [
      {
        "CreditDebitIndicator": "UAEOF.Credit",
        "Type": "UAEOF.ClosingAvailable",
        "DateTime": "2023-01-28T15:27:13+0300",
        "Amount": {
          "Amount": "10000.00",
          "Currency": "AED"
        },
        "CreditLine": [
          {
            "Included": true,
            "Type": "UAEOF.Available",
            "Amount": {
              "Amount": "45000.00",
              "Currency": "AED"
            }
          }
        ]
      }
    ]
  },
  "Links": {
    "Self": "https://rs1.openfinanceplatform.ae/open-finance/account-information/2024.03.11-draft1/accounts/f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115/balances"
  },
  "Meta": {}
}

3.9 Get Transactions for an Account

3.9.1 Request: accounts/{AccountId}/transactions resource

Code Block
GET /open-finance/account-information/2024.03.11-draft1/accounts/f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115/transactions HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Accept: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

3.9.2 Response: accounts/{AccountId}/transactions resource

Code Block
HTTP/1.1 200 OK
Content-Type: application/json
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
  "Data": {
    "AccountId": "f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115",
    "Transaction": [
      {
        "TransactionId": "19ee5b71-e70a-4a97-8cc2-c235c7274beb",
        "TransactionDateTime": "2023-01-26T16:18:32+0300",
        "LocalTimeZone": "UTC+04:00",
        "StatementReference": "502fec1c-ed4f-4524-a477-13b9802c03d",
        "TransactionReference": "20230126SAMA1234567812345678123456",
        "TransactionType": "UAEOF.POS",
        "SubTransactionType": "UAEOF.Purchase",
        "TerminalId": "1234567812345678",
        "Flags": [
          "UAEOF.Cashback"
        ],
        "PaymentModes": "UAEOF.Online",
        "CreditDebitIndicator": "UAEOF.Debit",
        "Status": "UAEOF.Booked",
        "TransactionMutability": "UAEOF.Mutable",
        "BookingDateTime": "2023-01-26T16:18:32+0300",
        "ValueDateTime": "2023-01-26T16:18:32+0300",
        "Amount": {
          "Amount": "100.00",
          "Currency": "AED"
        },
        "ChargeAmount": {
          "Amount": "10.00",
          "Currency": "AED",
          "ChargeIncluded": true
        },
        "ChargeAmountVat": {
          "Amount": "0.00",
          "Currency": "AED"
        },
        "CurrencyExchange": {
          "SourceCurrency": "AED",
          "TargetCurrency": "AED",
          "UnitCurrency": "1",
          "ExchangeRate": "1.02",
          "InstructedAmount": {
            "Amount": "102.00",
            "Currency": "AED"
          }
        },
        "Balance": {
          "CreditDebitIndicator": "UAEOF.Credit",
          "Type": "UAEOF.ClosingAvailable",
          "Amount": {
            "Amount": "9900.00",
            "Currency": "AED"
          }
        },
        "MerchantDetails": {
          "MerchantId": "1234567890",
          "MerchantName": "Rand's Cafe",
          "MerchantCategoryCode": "5812"
        },
        "CreditorAccount": {
          "IdentificationType": "UAEOF.IBAN",
          "Identification": "SA4420000001234567899876",
          "Name": "Rand's Cafe"
        },
        "DebtorAccount": {
          "IdentificationType": "UAEOF.IBAN",
          "Identification": "SA4420000001234567891234",
          "Name": "Hamad Ali"
        },
        "CardInstrument": {
          "CardSchemeName": "UAEOF.mada",
          "InstrumentType": "UAEOF.madaPay",
          "Name": "Mr. Hamad Ali",
          "Identification": "1234********4321"
        },
        "BillDetails": {
          "BillerId": "0",
          "BillNumber": "",
          "BillPaymentType": ""
        }
      },
      {
        "TransactionId": "c68d98ea-6e91-4a3b-8459-f12a9d7ecba4",
        "TransactionDateTime": "2023-01-26T16:18:32+0300",
        "LocalTimeZone": "UTC+04:00",
        "StatementReference": "502fec1c-ed4f-4524-a477-13b9802c03d",
        "TransactionReference": "20230126SASAMASAMA2BMOB11444064073",
        "TransactionType": "UAEOF.LocalBankTransfer",
        "SubTransactionType": "UAEOF.MoneyTransfer",
        "PaymentModes": "UAEOF.Online",
        "CreditDebitIndicator": "UAEOF.Credit",
        "Status": "UAEOF.Booked",
        "TransactionMutability": "UAEOF.Immutable",
        "BookingDateTime": "2023-01-26T16:18:32+0300",
        "ValueDateTime": "2023-01-26T16:18:32+0300",
        "Amount": {
          "Amount": "100.00",
          "Currency": "AED"
        },
        "ChargeAmount": {
          "Amount": "0.00",
          "Currency": "AED",
          "ChargeIncluded": true
        },
        "ChargeAmountVat": {
          "Amount": "0.00",
          "Currency": "AED"
        },
        "Balance": {
          "CreditDebitIndicator": "UAEOF.Credit",
          "Type": "UAEOF.ClosingAvailable",
          "Amount": {
            "Amount": "10000.00",
            "Currency": "AED"
          }
        },
        "CreditorAccount": {
          "IdentificationType": "UAEOF.IBAN",
          "Identification": "SA4420000001234567899876",
          "Name": "Rand Ali"
        },
        "DebtorAccount": {
          "IdentificationType": "UAEOF.IBAN",
          "Identification": "SA4420000001234567891234",
          "Name": "Abdulelah Alyahya"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://rs1.openfinanceplatform.ae/open-finance/account-information/2024.03.11-draft1/accounts/f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115/transactions"
  },
  "Meta": {
    "FirstAvailableDateTime": "2023-01-25T12:19:24+0300",
    "LastAvailableDateTime": "2023-01-27T12:19:24+0300"
  }
}

4. Further Examples

4.1 The TPP Queries the Account Access Consent Resource for the Status after a User has Authorized the Consent

4.1.1 Request: account-access-consents/{ConsentId} resource

Code Block
GET /open-finance/account-information/2024.03.11-draft1/account-access-consents/aac-1a672e83-d1e5-42bc-b8e1-60a490ec52fd HTTP/1.1
Host: rs1.openfinanceplatform.ae
Content-Type: application/json
x-fapi-interaction-id: 2e974f01-d111-4078-9a19-7a9b385e637c
Authorization: Bearer e6156449-6f27-4c42-aa5b-36602f73eac9

4.1.2 Response: account-access-consents/{ConsentId} resource

Code Block
HTTP/1.1 200 OK
Content-Type:application/json
x-fapi-interaction-id: 2e974f01-d111-4078-9a19-7a9b385e637c
{
  "Data": {
    "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
    "CreationDateTime": "2023-01-27T15:27:13+0300",
    "ConsentStatus": "Authorized",
    "ConsentFlags": {
      "PartlyAuthorized": "2023-01-27T16:27:13+0300"
    },
    "ConsentStatusUpdateDateTime": "2023-01-27T16:27:13+0300",
    "Permissions": [
      "ReadAccountsBasic",
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadBeneficiariesBasic",
      "ReadBeneficiariesDetail",
      "ReadTransactionsBasic",
      "ReadTransactionsDetail",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadScheduledPaymentsBasic",
      "ReadScheduledPaymentsDetail",
      "ReadDirectDebits",
      "ReadStandingOrdersBasic",
      "ReadStandingOrdersDetail"
    ],
    "AuthorizationExpirationTimeWindow": "720:00:00",
    "ExpirationDateTime": "2023-01-28T15:27:13+0300",
    "TransactionFromDateTime": "2023-01-25T12:19:24+0300",
    "TransactionToDateTime": "2023-01-27T12:19:24+0300",
    "AccountType": [
      "UAEOF.Retail"
    ],
    "AccountSubType": [
      "CurrentAccount"
    ],
    "ConsentPurpose": [
      "Account Aggregation",
      "E-Statement"
    ]
  },
  "Subscription": {
    "Webhook": {
      "Url": "https://api.tpp1.com/webhook/callbackUrl",
      "IsActive": false
    }
  },
  "Links": {
    "Self": "https://rs1.openfinanceplatform.ae/open-finance/account-information/2024.03.11-draft1/account-access-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa"
  },
  "Meta": {}
}

4.2 The TPP Requests a List of Accounts Using an Expired Access Token

4.2.1 Request: accounts resource

Code Block
GET /open-finance/account-information/2024.03.11-draft1/accounts HTTP/1.1
Host: rs1.openfinanceplatform.ae
Content-Type: application/json
x-fapi-interaction-id: 9a371b79-4e79-4d7d-a77d-380c528ab8c0
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

4.2.2 Response: 403 Forbidden

Code Block
HTTP/1.1 401 Unauthorized
Content-Type: application/json
x-fapi-interaction-id: 9a371b79-4e79-4d7d-a77d-380c528ab8c0
{
  "Errors": [
    {
      "Code": "UAEOF.AccessToken.Unauthorized",
      "Message": "max_age_exceeded: Token has expired",
      "Path": "Authorization",
      "Url": "https://developer.openfinanceplatform.ae/api-errors/401"
    }
  ]
}

4.3 Webhooks

4.3.1 The TPP Creates an Account Access Consent Request with a Webhook Subscription

4.3.1.1 Request: Account Access Consent and Webhook Subscription

Code Block
{
    "typ": "JWT",
    "alg": "PS256",
    "kid": "e4ce77c498e77000a25aa7b40e4a83f9"
}
.
{
    "iss": "s6BhdRkqt3",
    "iat": 1669393154,
    "exp": 1669393496,
    "nbf": 1669393154,
    "aud": "https://server.example.com",
    "response_type": "code id_token",
    "redirect_uri": "https://openbanking.lfi.ae/auth",
    "scope": "openid payments",
    "state": "af0ifjsldkj",
    "authorization_details": [
        {
            "Type": "AccountAccessConsent",
            "Data": {
                "ConsentId": "399e0065-9907-42cc-82b9-1ec4f273e3e9",
                "CreationDateTime": "2024-03-27T15:27:13+0300",
                "ConsentStatus": "Authorized",
                "ConsentStatusUpdateDateTime": "2024-03-27T16:27:13+0300",
                "Permissions": [
                    "ReadAccountsBasic",
                    "ReadAccountsDetail",
                    "ReadBalances",
                    "ReadBeneficiariesBasic",
                    "ReadBeneficiariesDetail",
                    "ReadTransactionsBasic",
                    "ReadTransactionsDetail",
                    "ReadTransactionsCredits",
                    "ReadTransactionsDebits",
                    "ReadScheduledPaymentsBasic",
                    "ReadScheduledPaymentsDetail",
                    "ReadDirectDebits",
                    "ReadStandingOrdersBasic",
                    "ReadStandingOrdersDetail"
                ],
                "AuthorizationExpirationTimeWindow": "720:00:00",
                "ExpirationDateTime": "2024-03-28T15:27:13+0300",
                "TransactionFromDateTime": "2024-03-25T12:19:24+0300",
                "TransactionToDateTime": "2024-03-27T12:19:24+0300",
                "AccountType": ["UAEOF.Retail"],
                "AccountSubType": ["CurrentAccount"],
                "ConsentPurpose": ["Account Aggregation", "E-Statement"]
            },
            "Subscription": {
              "Webhook": {
                "Url": "https://api.tpp1.com/webhook/callbackUrl",
                "IsActive": false
              }
            }
        }
    ]
}

4.3.2 The TPP updates a Webhook Subscription preference with the OFP

4.3.2.1 Request: Activate Webhook events

Code Block
PATCH /open-finance/account-information/2024.03.11-draft1/account-access-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Content-Type: application/json
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
{
  "Subscription": {
    "Webhook": {
      "IsActive": true
    }
  }
}

4.3.2.2 Response: Webhook events activated

Code Block
HTTP/1.1 204 No Content
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead

4.3.3 The TPP unsubscribes their Webhook Subscription with the OFP

4.3.3.1 Request: De-Activate Webhook events

Code Block
PATCH /open-finance/account-information/2024.03.11-draft1/account-access-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Content-Type: application/json
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
{
  "Subscription": {
    "Webhook": {
      "IsActive": false
    }
  }
}

4.3.3.2 Response: Webhook events de-activated

Code Block
HTTP/1.1 204 No Content
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead

4.3.4 The TPP receives data from the OFP (specific to the consent and permissions) via its Webhook

4.3.4.1 The OFP generates a Self Signed JWT Authorization Token for Client Authentication with the TPP.

This JWT Authorization Token MUST be set in the Authorization Header.

Code Block
{
  "alg": "PS256",
  "typ": "JOSE",
  "cty": "json",
  "kid":  "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
 "iss": "https://openbanking.masrif-ahmar.ae",
 "sub": "e75c26bf-1682-401a-a227-ec125f6636ab",
 "aud": "https://api.tpp.com/webhook/callbackUrl",
 "exp": 1661378066,
 "iat": 1661378036,
 "nbf": 1661378036,
 "jti": "274aa39d-d77a-46a9-b832-b2ced47919dd"
}
.
<<signature>>

4.3.4.2 Request: OFP publishes signed/encrypted data to the registered Webhook Url provided by the TPP

The example below shows a signed and encrypted payload with the JWT Authorization Token set in the Authorization Header.

...

Code Block
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 1664950125,
  "nbf": 1664950125,
  "aud": [
    "6uC8HSQ8C59SDSw43Cdm9YWxxjJmDV"
  ],
  "iat": 1661378036,
  "message": {
    "Data": {
      "AccountId": "f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115",
      "Account": [
        {   
          "Currency": "AED",
          "Status": "Active",          
          "AccountIdentifiers": [
            {
              "Name": "Account 1",
              "IdentificationType": "UAEOF.IBAN",
              "Identification": "00003130000001"
            }
          ]
        }
      ]
    },
    "Links": {
      "Self": "https://rs1.openfinanceplatform.ae/open-finance/account-information/2024.03.11-draft1/accounts/f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115"
    },
    "EventMeta": {
      "EventDateTime": "2022-08-24T07:28:00.556Z",
      "EventResource": "accounts",
      "EventType": "UAEOF.Resource.Created",
      "ConsentId": "aac-1a672e83-d1e5-42bc-b8e1-60a490ec52fd"
    }
  }
}
.
<<signature>>

4.3.4.3 Response: TPP validates the Self Signed JWT Authorization Token from LFI, stores data, and acknowledges a successful response to the OFP

Code Block
HTTP/1.1 202 Accepted
x-fapi-interaction-id: 77b0e830-b095-4c6c-94e8-20f83eaa799f

4.3.5 Webhook Payload for a single resource collection associated with a single event type

The following non-normative example illustrates a OFP webhook payload for a collection of account ID transactions of the same event type: UAEOF.Resource.Created

Code Block
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 1664950125,
  "nbf": 1664950125,
  "aud": [
    "6uC8HSQ8C59SDSw43Cdm9YWxxjJmDV"
  ],
  "iat": 1661378036,
  "message": {
    "Data": {
      "AccountId": "f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115",
      "Transaction": [
        {
          "TransactionId": "668f2fc8-7aa8-411b-bb9f-7571a90e7512",
          "TransactionReference": "1852efce-bedc-4fda-ba51-0f76c9137f91",
          "CreditDebitIndicator": "Debit",
          "Status": "Booked",
          "TransactionMutability": "",
          "BookingDateTime": "2022-08-24T07:27:00.556Z",
          "ValueDateTime": "2022-08-24T07:27:00.556Z",
          "TransactionInformation": "Foo Group ",
          "Amount": {
            "Amount": "41.10",
            "Currency": "AED"
          },
          "BankTransactionCode": {
            "Code": "CustomerCardTransactions",
            "SubCode": "CashWithdrawal"
          },
          "ProprietaryBankTransactionCode": {
            "Code": ""
          }
        },
        {
          "TransactionId": "05b6bfde-ce5a-48e1-a448-66d75518f1e8",
          "TransactionReference": "b5a6a869-730f-449d-badf-14ebf3980147",
          "CreditDebitIndicator": "Debit",
          "Status": "Booked",
          "TransactionMutability": "",
          "BookingDateTime": "2022-08-24T07:28:00.556Z",
          "ValueDateTime": "2022-08-24T07:28:00.556Z",
          "TransactionInformation": "Bar Holding",
          "Amount": {
            "Amount": "32.40",
            "Currency": "AED"
          },
          "BankTransactionCode": {
            "Code": "CustomerCardTransactions",
            "SubCode": "CashWithdrawal"
          },
          "ProprietaryBankTransactionCode": {
            "Code": ""
          }
        }
      ]
    },
    "Links": {
      "Self": "https://rs1.openfinanceplatform.ae/open-finance/account-information/2024.03.11-draft1/accounts/f91d07d0-6d8f-4e0e-9fb4-0ac61f84d115/transactions"
    },
    "EventMeta": {
      "EventDateTime": "2022-08-24T08:28:00.556Z",
      "EventResource": "transactions",
      "EventType": "UAEOF.Resource.Created",
      "ConsentId": "aac-1a672e83-d1e5-42bc-b8e1-60a490ec52fd"
    }
  }
}
.
<<signature>>

5. OpenAPI Specification

See Bank Data API - Swagger

6. Notes

  • IBAN

    • Where Data.Account.AccountIdentifiers[].IdentificationType is UAEOF.IBAN, the Identification field SHOULD contain the full IBAN

  • Passport, Driving Permit, IDCard, Residence Permit

    • Where Data.Party.VerifiedClaims.[].Verification.Evidence[DocumentDetails.Type] is set to any one of these enumerated values, then the DocumentNumber field SHOULD contain the actual number of the document type specified.

  • ProprietaryBankTransactionCodes

    • This code is mandatory when the BenefeciaryCode with code specifying the Domain, Family, and SubFamily as per External Codes ISO20022 is absent. This code is a proprietary code from the LFI and does not have a defined code list.