1 1. API Flows
- 1.1 1.1 Step 1: Agree Consent
- 1.2 1.2 Step 2: Authorize Consent
  - 1.2.1 1.2.1 Security and Access Control
    - 1.2.1.1 Client Credentials Grant
- 1.3 1.3 Step 3: Invoke API Operations
  - 1.3.1 1.2.1 Request Data
2 2. Examples

This page MUST be read in conjunction with the Account Opening Service Initiation OpenAPI description document.

The OpenAPI document provides a machine-readable view of the example API request and response payloads included in this page, and is critical for the correct implementation of client software code.

All sample JSON objects, unless for the sake of exemplar, are shown without encapsulation as a JSON Web Token (JWT), for the sake of simplicity. Sample JSON objects are also abridged for brevity.

Sequence diagrams that cover the flows described herein and include the operations of the API Hub and Ozone Connect are provided in API Hub documentation.

1. API Flows

1.1 Step 1: Agree Consent

The flow MUST begin with a User providing consent to the TPP for undertaking Account Opening operations.

Consent must be agreed between the User and TPP. The TPP can solicit quotes from LFIs who may or may not have an existing relationship with a given LFI.

1.2 Step 2: Authorize Consent

There is no requirement for authorization of a consent at an LFI for Account Opening.

1.2.1 Security and Access Control

The account-opening scope is used for invoking the Account Opening operations.

Client Credentials Grant

The TPP MUST use Client Credentials grant to obtain an Access Token to invoke Account Opening operations on behalf of the User.

The User MUST NOT be redirected to any LFI to provide authorize consent for Account Opening operations.

1.3 Step 3: Invoke API Operations

1.2.1 Request Data

The TPP MUST have a valid Access Token from the OFP authorization server, granted under the correct scope for Account Opening.

The TPP MUST use the Access Token to retrieve Account Opening operations at the OFP resource server.

The OFP MUST perform Access Token introspection, ensuring the Access Token:

has not expired.
has the correct scope.

The OFP must forward the request to the LFI, enriching the request with appropriate session metadata based on the implementation requirements of the OFP.

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

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

2. Examples

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

2.1 Create an Account

The TPP will send the Account Opening request to all LFI instances at the OFP that the User has selected or are in scope to provide a response.

TPPs require an Access Token from each LFI instance at the OFP.

The Account Opening request payload can optionally contain a Subscription object, allowing the TPP to receive Event Notifications when the OpeningStatus value changes.

2.1.1 Request: Access Token with Client Credentials Grant

Header

POST /token HTTP/1.1
Host: as1.openfinanceplatform.ae
Content-Type: application/x-www-form-urlencoded
Accept: application/json

Payload

grant_type=client_credentials
&scope=account-opening
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiJ9...nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI

2.1.2 Response: Access Token

Header

HTTP/1.1 200 OK
Content-Type:application/json

Payload

{
    "access_token": "caa1b60d-61ff-4cd8-a4e1-2d18c8696de0",
    "expires_in": 432000,
    "token_type": "Bearer",
    "scope": "account-opening",
}

2.1.3 Request: Create an Account

The payload for the create account operation MUST be a JWS, signed with the appropriate key.

The request payload can optionally contain a Subscription object, allowing the TPP to receive Event Notifications when the OpeningStatus changes.

Header

POST /open-finance/account-opening/v2.0/accounts HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0d
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

Payload

{
  "iss": "https://lfi.openfinanceapihub.ae",
  "exp": 1738848508,
  "nbf": 1738844908,
  "message": {
    "Data": {
      "LinkedOperations": {
        "FxQuoteId": "1d747c7b-7285-43e2-bb26-f7d6f195177e"
      },
      "Party": {
        "Claims": {
          "IdentityType": "Person",
          "GivenName": "Hamad",
          "Surname": "Ali",
          "EmiratesId": "7841-1234-1234567-1"
        }
      }
    }
  }
}

2.1.4 Responses: Create an Account

Header

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache, no-store
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0d

Payload

{
  "Data": {
    "AccountId": "7a79d7f0-4054-4ee8-bce2-ef696f1a7a31",
    "OpeningStatus": "AwaitingPartyData",
    "OpeningStatusUpdateDateTime": "2021-01-01T00:00:00+04:00"
  },
  "Links": {
    "Self": "https://lfi.openfinanceapihub.ae/accounts/7a79d7f0-4054-4ee8-bce2-ef696f1a7a31",
    "AccountOpeningRedirectUrl": "https://lfi.example.ae/accounts?account-id=7a79d7f0-4054-4ee8-bce2-ef696f1a7a31"
  },
  "Meta": {}
}

2.2 Retrieve an Account

2.2.1 Request: Retrieve an Account

Header

GET /open-finance/account-opening/v2.0/accounts/7a79d7f0-4054-4ee8-bce2-ef696f1a7a31 HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/json
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0d
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0

2.2.2 Response: Retrieve an Account

Header

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0d

Payload

{
  "Data": {
    "AccountId": "7a79d7f0-4054-4ee8-bce2-ef696f1a7a31",
    "OpeningStatus": "AwaitingPartyData",
    "OpeningStatusUpdateDateTime": "2021-01-01T00:00:00+04:00"
  },
  "Links": {
    "Self": "https://lfi.openfinanceapihub.ae/accounts/7a79d7f0-4054-4ee8-bce2-ef696f1a7a31",
    "AccountOpeningRedirectUrl": "https://lfi.example.ae/accounts?account-id=7a79d7f0-4054-4ee8-bce2-ef696f1a7a31"
  },
  "Meta": {}
}

3. Further Examples

3.1 Webhooks

The OFP supports Webhooks for Account OpeningStatus changes.

Creating an event notification subscription for a given quote is in shown the examples above.

A general guide to Webhooks is shown in the sections below.

3.1.1 The TPP unsubscribes their Webhook Subscription with the OFP

3.1.1.1 Request: Deactivate Webhook events

Header

PATCH /open-finance/account-opening/v2.0/accounts/3e39ede5-2c10-4679-86f0-579e839e4698 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

Payload

{
  "Subscription": {
    "Webhook": {
      "IsActive": false
    }
  }
}

3.1.1.2 Response: Webhook events deactivated

Header

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

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

3.1.2.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.

Payload

{
  "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>>

3.1.2.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.

Header

POST /webhook/callbackUrl HTTP/1.1
Host: api.tpp.com
x-fapi-interaction-id: 77b0e830-b095-4c6c-94e8-20f83eaa799f
Content-Type: application/jwt
Date: Wed, 24 Aug 2022 07:28:00 AST
Authorization: Bearer eyJhbGciO9.eyJzdWImlhdCI6MTUxNjIzOTAyMn0.iOeN9eg

The payload is a signed and encrypted payload. The JWE contains a JWS, which contains a JSON payload.

Payload

The decrypted payload of the JWS, without the signature, is shown in the example below. The example JSON is abridged for brevity.

{
  "iss": "string",
  "exp": 1664950125,
  "nbf": 1664950125,
  "aud": [
    "6uC8HSQ8C59SDSw43Cdm9YWxxjJmDV"
  ],
  "iat": 1661378036,
  "message": {
    "Data": {
      "AccountId": "7a79d7f0-4054-4ee8-bce2-ef696f1a7a31",
      "OpeningStatus": "AwaitingPartyData",
      "OpeningStatusUpdateDateTime": "2021-01-01T00:00:00+04:00"
    },
    "Links": {
      "Self": "https://lfi.openfinanceapihub.ae/accounts/7a79d7f0-4054-4ee8-bce2-ef696f1a7a31",
      "AccountOpeningRedirectUrl": "https://lfi.example.ae/accounts?account-id=7a79d7f0-4054-4ee8-bce2-ef696f1a7a31"
    },
    "Meta": {}
  }
}

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

Header

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

Account Opening Service Initiation API Guide

1. API Flows

1.1 Step 1: Agree Consent

1.2 Step 2: Authorize Consent

1.2.1 Security and Access Control

Client Credentials Grant

1.3 Step 3: Invoke API Operations

1.2.1 Request Data

2. Examples

2.1 Create an Account

2.1.1 Request: Access Token with Client Credentials Grant

2.1.2 Response: Access Token

2.1.3 Request: Create an Account

2.1.4 Responses: Create an Account

2.2 Retrieve an Account

2.2.1 Request: Retrieve an Account

2.2.2 Response: Retrieve an Account

3. Further Examples

3.1 Webhooks

3.1.1 The TPP unsubscribes their Webhook Subscription with the OFP

3.1.1.1 Request: Deactivate Webhook events

3.1.1.2 Response: Webhook events deactivated

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

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

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

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