FX Trade
What is it?
How to make it work?
Is this secure?
Communication protocol
API flow
FX Trade test accounts
What is it?
The FX Trade is a set of APIs that allows you to execute Currency Exchange for today or future settlement, from your own systems, request real-time rates, retrieve the status and history of trades on Sandbox.
The Sandbox environment is a place where you can test your application.
How to make it work?
You have to follow a few easy steps to register, create and build an app using our available APIs (you can omit the below steps if you already have an app):
1. You need to create a new app by going to My APPS and clicking on "Create New APP".
2. Then you will need to register your app by filling in the form with:
- the name of the app
- the selection of services that it will use
- a short description
3. Once the registration is completed, you will receive a Client ID and Secret.
The Client ID and Secret will be used with all the APIs that you use and they are provided for each app.
Is this secure?
The API works in two modes:
-
Unsecure mode
This mode allows you to use our API without using any of security mechanism. It's mean that you can call our API without JWS signature.
You are working in this mode if you do not set the X-JWS-SIGNATURE header's field.
The application registration is mandatory (Client ID).
-
Secure mode
This mode works in a way similar to our production security mode. Before you start working in this mode the following data are required:
-
application registration (Client ID)
-
RSA pair of keys (Public key and Private key) 2048 bits lenght
-
The private key is required to create JWS-Signature request header.
JWS in the Secure mode
At the message level, to ensure non-repudiation, a JSON Web Signature should be used, according to the RFC 7515 standard (https://tools.ietf.org/html/rfc7515).
The signature must be included in the X-JWS-SIGNATURE header of each request.
The signature is in a detached form and contains a signature of JSON described below. Responses are also signed with Bank's test certificate.
For the JWS Signature has to be used the RS256 algorithm identifier.
The public key required to verify the signature will be provided during the Onboarding process.
The structure of the JWS payload is presented below:
REQUEST:
The signature request (JSON) contains the following fields (the order is important):
- requestId
- requestMethod
- requestPath
- requestBody (BASE64URL)
The JSON string can not contain newline characters and whitespace characters.
Properties/Keys | Content | Required | Description |
---|---|---|---|
JWS payload JSON fields | |||
requestId |
Request ID using UUID format (Variant 1, Version 1) described in RFC 4122 standard , took from the message REQUEST-ID header field |
Y | UUID with datetime |
requestMethod | Api method | Y | use uppercase letters |
requestPath | Api path | Y |
PATH - copy the path from product without any changes |
requestBody | Body | Y | (BASE64URL) |
Example:
{"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"," requestMethod": "POST"," requestPath": "/fxtrade/v1_0.1/users/authentication"," requestBody": "eyJyZXF1ZXN0SGVhZGVyIjp7InJlcXVlc3RJZCI6IjBmNGYwMjAwLTY5ZTctMTFlYi04YTExLTFmM2QzNmI2MDU0NiIsInVzZXJBZ2VudCI6IjU0IiwiaXBBZGRyZXNzIjoiMTAuMS4zMy4xIiwic2VuZERhdGUiOiIyMDIxLTAyLTA4VDA5OjI0OjI4LjAxMFoifX0"}
RESPONSE:
The signature response (JSON) contains fields (the order is important):
- responseId
- requestMethod
- requestPath
- responseBody (BASE64URL)
The JSON string can not contain newline characters and whitespace characters.
Properties/Keys | Content | Required | Description |
---|---|---|---|
JWS payload JSON fields | |||
responseId | Request ID using UUID format (Variant 1, Version 1) described in RFC 4122 standard, took from the message REQUEST-ID header response field | Y | UUID |
requestMethod | Api method | Y | use uppercase letters |
requestPath | Api path | Y |
PATH - copy the path from product without any changes |
responseBody | Body | Y | (BASE64URL) |
Example:
{"requestId": "0f4f0200-69e7-11eb-8a11-1f3d36b60546"," requestMethod": "POST"," requestPath": "/fxtrade/v1_0.1/users/authentication"," responseBody": "eyJ0b2tlbiI6ICJ4eHh4eHh4eHh4eHh4eHh4IiwicmVzcG9uc2VIZWFkZXIiOnsicmVxdWVzdElkIjoiMGY0ZjAyMDAtNjllNy0xMWViLThhMTEtMWYzZDM2YjYwNTQ2Iiwic2VuZERhdGUiOiAiMjAyMS0wMi0wOFQwODoyNDoyOC43ODZaIn19"}
Communication protocol
As the communication protocol, HTTP / 2 or HTTP 1.1 will be used, secured with TLS 1.2+ protocol with authentication of the server using non-qualified certificates.
API flow
To start the process, you should call the authentication method as follow:
Example request:
POST https://gateway.developer.aliorbank.pl/openapipl/sb/fxtrade/v1_0.1/users/authentication
Accept-Charset: utf-8
X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxxxx
REQUEST-ID: 09d2668a-66f0-11eb-959d-0d39ec005b3c
Accept-Encoding: gzip
Content-Type: application/json
{
"requestHeader": {
"requestId": "09d2668a-66f0-11eb-959d-0d39ec005b3c",
"ipAddress": "10.0.0.1",
"sendDate": "2021-02-16T14:51:10.790Z"
}
}
{
"token": "$2a$10$TW1AIE3g5hlKw8rrtLaPMeCSw8m9RWdZZKcNaKVSm9Eai0ca23Ahi",
"responseHeader": {
"requestId": "09d2668a-66f0-11eb-959d-0d39ec005b3c",
"sendDate": "2021-02-16T13:51:11.407Z"
}
}
If the response is without an error (Http status code = 200 ), you can continue work with API, otherwise you should check the field httpMessage/errorMessage for any additional information in terms of the error reason.
When the login is successful,you will get an unique token which will be used in therequestHeader.token field for all transactional requests.
In this particlar example the token has a value $2a$10$TW1AIE3g5hlKw8rrtLaPMeCSw8m9RWdZZKcNaKVSm9Eai0ca23Ahi,
The below response allows to get the subscription for price flows:
Example request:
POST https://gateway.developer.aliorbank.pl/openapipl/sb/fxtrade/v1_0.1/quote/subscriptions
Accept-Charset: utf-8
X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxxxx
REQUEST-ID: 0a39b3db-66f0-11eb-959d-31748f15c1a7
Accept-Encoding: gzip
Content-Type: application/json
{
"requestHeader": {
"requestId": "0a39b3db-66f0-11eb-959d-31748f15c1a7",
"ipAddress": "10.0.0.1",
"token": "$2a$10$TW1AIE3g5hlKw8rrtLaPMeCSw8m9RWdZZKcNaKVSm9Eai0ca23Ahi"
},
"order": {
"currencyRate": {
"currencySell": "PLN",
"currencyBuy": "EUR"
},
"debtNumber": "97249000050000450080813115",
"credNumber": "37249000050000460074458415",
"amountBuy": "9.00",
"transactionDate": "2021-02-16",
"tranType": "0"
}
}
After subscription, you will receive the price flows - the rate and the subscriptionId fields for this transaction are sent by the Bank.
{
"subscriptionId": "9876d8c9-f221-4ff6-8d4f-061367f2da36",
"currencyRate": {"rate": "4.5038"},
"responseHeader": {
"requestId": "0a39b3db-66f0-11eb-959d-31748f15c1a7",
"sendDate": "2021-02-16T13:51:12.170Z"
}
}
After the quote is received - you can send a trade order.
The request presents the copy of the subscription order with two additional fields - CurrencyRate.rate and subscriptionId
Example request:
POST https://gateway.developer.aliorbank.pl/openapipl/sb/fxtrade/v1_0.1/order
Accept-Charset: utf-8
X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxxxx
REQUEST-ID: 0aae95bc-66f0-11eb-959d-7b0332ced79b
Accept-Encoding: gzip
Content-Type: application/json
{
"requestHeader": {
"requestId": "0aae95bc-66f0-11eb-959d-7b0332ced79b",
"ipAddress": "10.0.0.1",
"token": "$2a$10$TW1AIE3g5hlKw8rrtLaPMeCSw8m9RWdZZKcNaKVSm9Eai0ca23Ahi"
},
"order": {
"currencyRate": {
"currencySell": "PLN",
"currencyBuy": "EUR",
"rate": "4.5038"
},
"debtNumber": "97249000050000450080813115",
"credNumber": "37249000050000460074458415",
"amountBuy": "9.00",
"transactionDate": "2021-02-16",
"tranType": "0",
"subscriptionId": "9876d8c9-f221-4ff6-8d4f-061367f2da36"
}
}
Once the order is successful, you will receive an order status and orderId (a unique id for this operation is available and can be checked in a history file).
{
"orderId": "920cce10-4028-41b5-ba30-d9414d914a01",
"status": "Executed",
"rejectReason": "",
"tranType": "0",
"transactionDate": "2021-02-16T13:51:12.051Z",
"currencyRate": {
"currencySell": "PLN",
"currencyBuy": "EUR"
},
"amountSell": "9.00",
"responseHeader": {
"requestId": "0aae95bc-66f0-11eb-959d-7b0332ced79b",
"sendDate": "2021-02-16T13:51:12.786Z"
}
}
The history file (list of created orders) can be checked by using /order/transaction services.
Example request:
POST https://gateway.developer.aliorbank.pl/openapipl/sb/fxtrade/v1_0.1/order/transactions
Accept-Charset: utf-8
X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxxxx
REQUEST-ID: 3ee49990-66fd-11eb-959d-373a66727635
Accept-Encoding: gzip
Content-Type: application/json
{
"dealType": "WTN",
"status": 0,
"dateFrom": "2021-02-04",
"dateTo": "2021-02-16",
"requestHeader": {
"requestId": "3ee49990-66fd-11eb-959d-373a66727635",
"ipAddress": "10.0.0.1"
}
}
The response will allow you to check the list of orders with basic details:
{"orderList": [
{
"orderId": "fa20783d-a4d0-494b-9024-6c4712faf74a",
"type": "RFQ",
"transactionDate": "2021-02-03T15:04:03.004Z",
"excecutionDate": "2021-02-03T15:04:03.004Z",
"currencyRate": {
"currencySell": "PLN",
"currencyBuy": "EUR",
"rate": "1.3525"
},
"amountSell": "227.00",
"amountBuy": "307.02",
"status": 1,
"channel": "Autodealing"
},
{
"orderId": "920cce10-4028-41b5-ba30-d9414d914a01",
"type": "RFQ",
"transactionDate": "2021-02-16T13:51:12.051Z",
"excecutionDate": "2021-02-16T13:51:12.051Z",
"currencyRate": {
"currencySell": "PLN",
"currencyBuy": "EUR",
"rate": 4.5038
},
"amountSell": "40.53",
"amountBuy": "9.00",
"status": 1,
"channel": "OPENAPI"
}
]}
The single report details are also available:
Example request:
POST https://gateway.developer.aliorbank.pl/openapipl/sb/fxtrade/v1_0.1/order/details
Accept-Charset: utf-8
X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxxxx
REQUEST-ID: a929a5c1-66fd-11eb-959d-1fee4f79d11a
Accept-Encoding: gzip
Content-Type: application/json
{
"order": {
"orderId": "920cce10-4028-41b5-ba30-d9414d914a01"
},
"requestHeader": {
"requestId": "a929a5c1-66fd-11eb-959d-1fee4f79d11a",
"ipAddress": "10.0.0.1"
}
}
The example order is presented below:
{
"order": {
"tranType": "0",
"orderId": "920cce10-4028-41b5-ba30-d9414d914a01",
"transactionDate": "2021-02-16T13:51:12.051Z",
"executionDate": "2021-02-16T13:51:12.051Z",
"currencyRate": {
"currencySell": "PLN",
"currencyBuy": "EUR",
"rate": 4.5038
},
"amountSell": "40.53",
"amountBuy": "9.00",
"status": 1,
"debtNumber": "97249000050000450080813115",
"credNumber": "37249000050000460074458415",
"method": 1,
"info": "Info",
"channel": "OPENAPI"
},
"responseHeader": {
"requestId": "6d1a0055-702a-11eb-a7f6-1b75e2e20a69",
"sendDate": "2021-02-16T07:41:50.179Z"
}
}
FX Trade test accounts
The API provides the default customer settings in the Sandbox environment.
The list of available test accounts is as follow:
-
No Account currency Account number(s) 1 CHF
72249000050000460029684719
2 PLN
97249000050000450080813115
47249000050000453075450686
3 EUR
37249000050000460074458415
4 GBP
02249000050000460058004159
5 CZK
41249000050000460020679118
6 USD
54249000050000460069530800
7 SEK
82249000050000460098522432
8 NOK
96249000050000460029597472
If your application works in the secure mode, it is also possible to create separte test accounts. Such requirement should be communicated during the onboarding process.