FX Trade

v1.0.1

 

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:

  1. 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).
     

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

 

Alior Bank uses its own cookies as well as cookies from third parties. Cookies are used to remember your settings, for traffic measurement and to show you targeted ads. By clicking I understand, you consent to this use of cookies. Read more about our use of cookies.

I understand