FX Service Initiation API Guide
This page MUST be read in conjunction with the FX 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 FX Service Initiation 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.
There is no requirement for a User to authorize consent at a given LFI to receive an FX quote, unless instructing payment as the result of accepting a given quote. The requirements for authorization in this context are contained in Bank Service Initiation, and are out of scope of this guide.
1.2 Step 2: Authorize Consent
There is no requirement for authorization of a consent at an LFI for FX Service Initiation.
1.2.1 Security and Access Control
The fx scope MUST be used for invoking FX Service Initiation operations.
Client Credentials Grant
The TPP MUST use Client Credentials grant to obtain an Access Token to invoke FX Service Initiation Quote operations on behalf of the User.
The User MUST NOT be redirected to any LFI to provide authorize consent for FX Service Initiation Quote 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 FX Service Initiation.
The TPP MUST use the Access Token to retrieve FX Service Initiation Quote 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 FX Service Initiation API.
2.1 Create an FX Quote
The TPP will send the FX Service Initiation Quote 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.
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/jsonPayload
grant_type=client_credentials
&scope=fx
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiJ9...nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI2.1.2 Response: Access Token
Header
HTTP/1.1 200 OK
Content-Type:application/jsonPayload
{
"access_token": "caa1b60d-61ff-4cd8-a4e1-2d18c8696de0",
"expires_in": 432000,
"token_type": "Bearer",
"scope": "fx",
}2.1.3 Request: Create an FX Quote
Header
POST /open-finance/fx/v2.0/fx-quotes 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-2d18c8696de0Payload
{
"Data": {
"TransactionType": "Spot",
"QuotedCurrency": "USD",
"UnitCurrency": "AED",
"TradeAmount": {
"Currency": "USD",
"Amount": "100.00"
},
"ContractIdentification": "54c2d2bd-92de-4dcd-8eb7-f48527a2f0a5",
"Party": {
"Claims": {
"IdentityType": "Person",
"GivenName": "Hamad",
"Surname": "Ali",
"EmiratesId": "7841-1234-1234567-1"
}
}
}
}2.1.4 Responses: Create an FX Quote
2.1.4.1 An FX Quote has been created and returned to the TPP
Header
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache, no-store
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0dPayload
{
"Data": {
"FxQuoteId": "1d747c7b-7285-43e2-bb26-f7d6f195177e",
"BuyAmount": {
"Currency": "USD",
"Amount": "100.00"
},
"SellAmount": {
"Currency": "AED",
"Amount": "367.25"
},
"UnitCurrency": "AED",
"QuotedCurrency": "USD",
"RateType": "Actual",
"ExchangeRate": 0.272294,
"ExpirationDateTime": "2025-08-24T14:15:22.001+04:00",
"UserIdentificationStatus": "UserIdentified"
},
"Links": {
"Self": "https://lfi.openfinanceapihub.ae/open-finance/fx/v2.0-draft2/fx-quotes/1d747c7b-7285-43e2-bb26-f7d6f195177e",
"LiabilityPolicy": "https://www.lfi.ae/links/liability-policy",
"RefundCancellationPolicy": "https://www.lfi.ae/links/refund-cancellation-policy"
},
"Meta": {}
}2.1.4.2 A quote cannot be provided by the LFI
Header
HTTP/1.1 204 No Content
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead2.2 Retrieve an FX Quote
2.2.1 Request: Retrieve an FX Quote
Header
GET /open-finance/fx/v2.0/fx-quotes/3e39ede5-2c10-4679-86f0-579e839e4698 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-2d18c8696de02.2.2 Response: Get an FX Quote
Header
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
x-fapi-interaction-id: f9ccecd5-2ed1-4299-b233-7c5d8a6a2e0dPayload
{
"Data": {
"FxQuoteId": "3e39ede5-2c10-4679-86f0-579e839e4698",
"BuyAmount": {
"Currency": "USD",
"Amount": "100.00"
},
"SellAmount": {
"Currency": "AED",
"Amount": "367.25"
},
"UnitCurrency": "AED",
"QuotedCurrency": "USD",
"RateType": "Actual",
"ExchangeRate": 0.272294,
"ExpirationDateTime": "2025-08-24T14:15:22.001+04:00",
"UserIdentificationStatus": "UserIdentified",
"Party": {
"Claims": {
"IdentityType": "Person",
"GivenName": "Hamad",
"Surname": "Ali",
"EmiratesId": "7841-1234-1234567-1"
}
},
"Status": "Available",
"CreationDateTime": "2025-08-24T14:05:22.001+04:00",
"StatusUpdateDateTime": "2025-08-24T14:05:22.001+04:00"
},
"Links": {
"Self": "https://lfi.openfinanceapihub.ae/open-finance/fx/v2.0/fx-quotes/3e39ede5-2c10-4679-86f0-579e839e4698"
},
"Meta": {}
}2.3 Accept an FX Quote
2.3.1 Request: Accept an FX Quote
Header
PATCH /open-finance/fx/v2.0/fx-quotes/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-a96f300a27f1Payload
The payload for the patch operation MUST be a JWS, signed with the appropriate key.
The FX Service Initiation Quote request payload can optionally contain a Subscription object, allowing the TPP to receive Event Notifications when the QuoteStatus changes.
{
"iss": "https://lfi.openfinanceapihub.ae",
"exp": 1738848508,
"nbf": 1738844908,
"message": {
"Data": {
"QuoteStatus": "Accepted",
"QuoteReference": "234ef592-70c6-4f9f-a249-9554e5c32304",
"Trade": {
"BuyAmount": {
"Currency": "USD",
"Amount": "100.00"
},
"SellAmount": {
"Currency": "AED",
"Amount": "367.25"
}
},
"Commission": {
"CommissionAmount": {
"Currency": "AED",
"Amount": "14.68"
}
}
}
}
}2.3.2 Response: Accept an FX Quote
Header
HTTP/1.1 204 No Content
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead3. Further Examples
3.1 Webhooks
The OFP supports Webhooks for FX Service Initiation QuoteStatus 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/fx/v2.0/fx-quotes/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-a96f300a27f1Payload
{
"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-f420d08acead3.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.iOeN9egThe 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": {
"FxQuoteId": "1d747c7b-7285-43e2-bb26-f7d6f195177e",
"BuyAmount": {
"Currency": "USD",
"Amount": "100.00"
},
"SellAmount": {
"Currency": "AED",
"Amount": "367.25"
},
"UnitCurrency": "AED",
"QuotedCurrency": "USD",
"RateType": "Actual",
"ExchangeRate": 0.272294,
"ExpirationDateTime": "2025-08-24T14:15:22.001+04:00",
"UserIdentificationStatus": "UserIdentified",
"Party": {
"Claims": {
"IdentityType": "Person",
"GivenName": "Hamad",
"Surname": "Ali",
"EmiratesId": "7841-1234-1234567-1"
}
},
"QuoteStatus": "Accepted",
"CreationDateTime": "2025-08-24T14:05:22.001+04:00",
"StatusUpdateDateTime": "2025-08-24T14:05:22.001+04:00"
},
"Links": {
"Self": "https://lfi.openfinanceapihub.ae/open-finance/fx/v2.0-draft2/fx-quotes/1d747c7b-7285-43e2-bb26-f7d6f195177e"
},
"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© CBUAE 2025
Open License and Contribution Agreement | Attribution Notice