API Documentation
The URLs for the APIs are:
- https://test-api.forexfix.com/api for Test API
- https://api.forexfix.com/api for Production API
Authorization on the Forexfix platform is required
Content type should be JSON.
- 200 - OK, the request was successful.
- 201 - Object has been created
- 400 - Bad Request, the request could not be understood or was missing required parameters.
- 401 - Unauthorized, authentication failed, please login correctly.
- 429 - Too many requests
- 500 - Internal Server Error, something wrong happened on the server. Please try again later and (possibly) report the accident to us.
- 503 - Maintenance.
High level code
Basic message outlining the error.
Array of reasons why the error occured.
["buy_sell_type"]Array of objects with further details on the “reasons”.
Timestamp of error
{
"code": "unable_to_get_rates",
"message": "Unable to get rates.",
"reasons": [
"buy_sell_type",
"error_parsing_date"
],
"errors": [
{
"code": "buy_sell_type",
"required": "fixed_side",
"value": "something_wrong"
},
{
"code": "error_parsing_date",
"required": "YYYY-MM-DD",
"value": "2018-XX-07"
}
],
"timestamp": "2018-03-08T17:37:11+00:00"
}{
"code": "maintenance",
"message": "maintenance.",
"reasons": [
"maintenance"
],
"timestamp": "2018-03-08T16:05:59+00:00"
}1. Create order
An order is a conversion between two different currencies with an fixed exchange rate. An order can be booked as spot or as forward. Spot is used for transferring money directly to a beneficiary within 5 days. The client pays the full amount immedately to one of our partner accounts. Forwards are used to fix an exchange rate for a longer timeframe. A forward needs a downpayment of 3% to 10% of the sell_amount. More information regarding spot and forward can be found here: Difference between spot and forwards
There are two different ways to create an order:
- Book order from rate with a predefined rate that is acquired from the endpoint Create rate. The exchange rate is known in advance
- Book order with market rate without knowing the exchange rate in advance
- Valid currencies are returned by the endpoint Get valid currencies
- Valid conversion date are returned by the endpoint Get order dates
- The limit for one transaction can be requested from Get client limits
2. Create beneficiary
To send the converted money to a beneficiary, first a beneficiary has to be created. Which details are needed is dependend on the payment type (see Local/Regular and Swift/Priority payment the beneficiaries bank account country and the beneficiaries bank account currency. The exact required details for creating a beneficiary can be requested from the endpoint Get required beneficiary details. In some cases there are more than one valid option to provide account details. (e.g. for British GBP accounts the client can provide the sort code with the account number OR the iban). At least one of these options have to be provided.
3. Create payment
To send money to the beneficiary a payment must be created. The payment can linked to a conversion or payed directly from the matching currency balance. If connected to a conversion, it is possible to create multiple payments from one conversion by adjusting the amount. The sum of the amount of all payments linked to one conversion can not be higher than the buy amount of the conversion. The payment currency is always the same as the buy currency of the linked conversion
Spot vs Forward
At Forexfix it’s possible to book a forward or a spot order. The main difference between these two is the time between the creation date and the conversion date. A spot converts from sell currency to buy currency within five days. Forwards conversion dates lie up until one year in future from now. The exchange rate is always fixed till the conversion date, thats why forwards are used to hedge currency risks.
Flow of funds
After booking an order the clients have to transfer money from their bank acount to the bank account of Forexfix partner.
Spot orders are getting funded with one payment from the clients bank account to the partner bank account. After the order is funded (the whole sell amount is at the partner bank account) the sell amount will be converted to the buy amount. They buy amount afterwards can be sent to the beneficiary through a payment.
Forward orders are getting funded with two payments from the clients bank account to the partner bank account. The downpayment have to be done within the first days after the order creation. The amount of the downpayment lies between 3% - 10% of the sell amount depending on how far the conversion date is in the future. The remaining amount has to be provided shortly before the conversion date. After the order is funded (the whole sell amount is at the partner bank account) the sell amount will be converted to the buy amount. They buy amount afterwards can be sent to the beneficiary throug a payment.
With Forexfix payments to the beneficiary can be sent through the local/regular payment system. The local payment is cheaper because there are no swift charges. Local payments are only available for a some bank account currency and bank account country combinations and for GBP and USD there is a maximum amount for local payment. The endpoint Required information for beneficiary creation returns all required details of a beneficiary for local payment if local payment is possible in general and if the parameter swift is set to false.
The main differences between local/regular and swift/priority payment are:
- Local payment is cheaper because there are no swift charges
- The sender of a local payment is the payment provider (e.g. Currency cloud) and not the client itself
- Local payments are only possible for some currencies and in this range some currencies only up to certain amounts (GBP 250.000, USD 100.000)
- Swift payments are always possible no matter which bank account currency and bank account country
This endpoint signs a new client (and user) up.
Request body
E-Mail address of new client
The password - must contain at least one special character, letter, number and uppercase character
First name of the client
Last name of the client
Telephone number
Company name
Client’s language
English
Germany
Accepted version of the terms and conditions
Responses
Body
Token for accessing api
The id of the client
The id of the user (one client can have multiple users)
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_client”
The possible “unable_to_create_client” error “reasons”:
- “client_already_exists” - The client already exists
- “password_incorrect_format” - The password is in the incorrect format
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_create_client",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "..."
}POST https://api.forexfix.com/api/user/register HTTP/1.1
Content-Type: application/json
{
"email": "email@address.com",
"password": "VeRyStroNgP@assW0rd!",
"first_name": "my",
"last_name": "name",
"telephone": "+35 123456789",
"company_name": "my company",
"client_language": "DE",
"terms": "V0"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"client_token": "eyJhbGciOiJIUzI1N...l5LI31m1w8mhJeQ",
"client_id": 11713903,
"user_id": 8255445427
}This endpoint allows a user to login with credentials and receives a token which is valid for 24hours
Request body
E-Mail adress of the user
Secret password of the user
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_login_client”
With possible “unable_to_login_client” Error “reasons”:
- “client_not_found” - The client is not found
- “too_many_requests” - There has been too many incorrect requests
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/user/login HTTP/1.1
Content-Type: application/json
{
"email": "email@address.com",
"password": "VeRyStroNgP@assW0rd!"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"client_id": "80013318",
"user_id": "8013910448",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5c...........ml4LmRlIiwECfwHX0s"
}This endpoint returns a list of restrictions for the user.
Request headers
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_get_restrictions”
The possible “unable_to_create_client” error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
GET https://api.forexfix.com/api/user/restrictions HTTP/1.1
Authorization: Bearer <auth_token>
HTTP/1.1 200 OK
Content-Type: application/json
[
"beneficiary_deactivate"
]Returns an array of notifications/emails that will not be sent to the user
Request headers
Responses
Body
Examples
Array of restricted notifications/emails
[
"notification_secondary_transfer_strong_reminder",
"notification_create_conversion",
"notification_primary_transfer_arrived",
"notification_secondary_transfer_arrived",
"notification_call_for_beneficiary",
"notification_secondary_transfer_reminder",
"notification_secondary_transfer_strong_reminder",
"notification_primary_transfer_late",
"notification_secondary_transfer_late",
"notification_payment_completed",
"notification_order_cancelled",
"notification_change_conversion_date"
]Body
This endpoint allows a user reset their password.
Request body
E-Mail adress of the user
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “internal_service_error”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/password_reset_request HTTP/1.1
Content-Type: application/json
{
"email": "email@address.com",
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ok":true
}This endpoint allows a user set their password. To generate a token, use Reset password request.
Request body
The token through the email from Reset password request.
A strong new password
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “invalid_password_reset_token”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/password_reset HTTP/1.1
Content-Type: application/json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cC.....qCMyQclzlgSuSJPgmdakPKlVwY",
"password": "%K;/yp}PHEct8U(Qkx2;"
}
HTTP/1.1 200 OK
{
"ok": true
}Set user restrictions for a subuser. Is only possible for master users
Request body
User id of the user that should be updated
List of all restrictions for the user
["beneficiary_update","beneficiary_create","beneficiary_deactivate","user_notifications","user_conversions","user_pay_in_service"]Pin of the user that updates the resticitions
Responses
Body
Set the limits for a subuser. Userlimits have to be lower than clients (company) limits. This can only be done by the masteruser
Request body
Currency for the limit
Sets the limit per transaction
Sets the limit per day all transactions combined
Sets the limit per month all transactions combined
User id of the user that should be updated
Pin of the user that updates the limits for a subuser
This endpoint allows a user to validate their email for onboarding.
Request body
The token through the email after signing up
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “invalid_email_verification_token”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/validate/email HTTP/1.1
Content-Type: application/json
{
"email_verify_token": "eyJhbGciOiJIUzI1NiIsInR5cC.....qCMyQclzlgSuSJPgmdakPKlVwY"
}
HTTP/1.1 200 OK
{
"ok": true
}This endpoint allows a user to create a security pin required for trading. To change your pin, please contact support.
Request body
The pin to be created.
Responses
Body
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “pin_duplicate”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/client/pin/create HTTP/1.1
Content-Type: application/json
{
"pin": "1223"
}
HTTP/1.1 200 OK
{
"ok": true
}This endpoint allows a user to validate a security pin required for trading. To change your pin, please contact support.
Request body
The pin to be validated.
Responses
Body
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “pin_invalid”
- “too_many_requests”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/client/pin/validate HTTP/1.1
Content-Type: application/json
{
"pin": "1223"
}
HTTP/1.1 200 OK
{
"validated": true
}The endpoint returns an exchange rate with a fixed exchange rate, a buy and a sell amount including the commission. This quote can be booked within a timeframe (until “rate_valid_till”) with the “book order from rate” api. By calling this endpoint no bindable order will be created.
Request headers
Request body
The currency for the buy side. All possiblities are returned by Get valid currencies endpoint
The currency for the sell side. All possiblities are returned by Get valid currencies endpoint
The side that should be fixed
The sell side is fixed and the buy side will be calculated based on the rate
The buy side is fixed and the sell side will be calculated based on the rate
The amount of the fixed side
The conversion date. If left out, the default value will be chosen. The default date and more information regarding the conversion date, are delivered by the Get order dates endpoint
Responses
Body
This ID can be used to book a conversion on exactly this rate. The id is valid until the “rate_valid_till” date/time
The date-time until this offer is valid and can be booked with the rate_id. Timeframe is about 1min after API Call
The buy currency including comission
The sell currency
The fixed side
The buy side is fixed and the sell side will be calculated based on the rate
The sell side is fixed and the buy side will be calculated based on the rate
The date of the converison
The exchange rate exluding the comission
The buy amount including comission
The sell amount including comission
Secondary transfer required is true if the order is a forward
The primary transfer amount. Deposit for forwards, full amount for spot orders
The secondary transfer amount. Remaining amount for forwards
The currency in which the primay and secondary amount should be transfered
The comission charges the customer for this trade
The currency in which we charge the comission
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_rate”
With possible Error “reasons”:
- “error_parsing_date” - conversion date is not valid. Cannot be weekend or holiday
- “buy_currencies” - The buy currency is not available for the sell currency (e.g. RUB)
- “currencies” - One of the currencies is not a valid currency
- “error_parsing_currency_pair” - The currencypair is not available
- “buy_sell_type” - Request fixed_side is not valid
- “greater_than_zero” - The amount has to be greater than zero
- “amount_is_too_small” - The amount is too small
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_create_rate",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}GET https://api.forexfix.com/api/trade/rate/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"buy_currency": "GBP",
"sell_currency": "EUR",
"fixed_side": "sell",
"amount": "10000",
"conversion_date": "2018-11-05"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"rate_id": "ASDKJHSF_39823474",
"rate_valid_till": "2018-03-09T12:33:41Z",
"buy_currency": "GBP",
"sell_currency": "EUR",
"fixed_side": "buy",
"conversion_date": "2017-09-19T13:00:00Z",
"client_facing_rate": "0.8894",
"client_facing_buy_amount": "20.00",
"client_facing_sell_amount": "22.49",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"client_facing_commission": 0.43,
"client_facing_commission_currency": "EUR",
"payment_type": "regular",
"primary_transfer_amount": "22.92",
"secondary_transfer_amount": "0.00",
"total_transfer_amount": "22.92"
}This endpoint allows a client to book an order from a previously requested “Create rate” within the timeframe (until the provided rate_valid_till timestamp).
Request headers
Request body
The Rate Id retrieved from the “Create rate” endpoint
Comment for the converison
The user specific pin
A unique request ID to ensure order is not doubled-booked and to allow linking the request with the order response
Responses
Body
The id of the conversion
Reference used for transfering the funds
The amount of the buy side
The amount of the sell side
The rate including commission
The comission for the client
The currency of the buy side
The currency of the sell side
The conversion date
The primary pay in amount (downpayment for forwards, total amount for spots)
The date until the primary transfer amount has to be arrived
The secondary pay in amount (the remaining amount of forwards)
The date until the secondary transfer amount has to be arrived
Is true if the order is a forward and therefore a second amount has to be payed
The currency for the primary and secondary transfer amount
The sell and buy currencypair in an standardized format
A unique request ID to ensure order is not doubled-booked and to allow linking the request with the order response
The rate id from the request
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_conversion”
- “pin_invalid”
- “internal_service_error”
- “required_validated_account” With possible “unable_to_create_conversion” Error “reasons”:
- “rate_id_invalid” - The rate ID is invalid
- “rate_id_has_expired” - The rate ID has expired
- “str_required” - A string has to be present for a required request attribute
- “too_many_requests” - There has been too many “pin_invalid” requests
- “conversion_below_limit” - The amount of the requested rate is too small to create order
- “client_limit_not_in_range” - Requested amount is not within the client’s limit
- “limit_month_reached” - The requested amount is greater thant the client’s monthly limit
- “limit_day_reached” - The requested amount is greater thant the client’s daily limit
- “limit_trade_reached” - The requested amount is greater thant the client’s trade limit
- “required_validated_account” - A fully validated account is required
Examples
{
"code": "unable_to_create_conversion",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "..."
}POST https://api.forexfix.com/api/trade/conversion/fixed HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"rate_id": "ALSKHSDF_983726421",
"unique_request_id":"5467890567",
"comment": "my comment",
"pin": "1234"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"unique_request_id":"5467890567",
"conversion_id": "91290323477",
"pay_in_reference": "20180309-CLVFFB",
"client_facing_buy_amount": "10000.00",
"client_facing_sell_amount": "8752.62",
"client_facing_commission": "17.47",
"client_facing_rate": "1.1855",
"buy_currency": "USD",
"sell_currency": "EUR",
"conversion_date": "2018-11-07T00:00:00+00:00",
"primary_transfer_amount": "875.27",
"primary_transfer_date": "2018-03-13T16:30:00+00:00",
"secondary_transfer_amount": "7877.35",
"secondary_transfer_date": "2018-11-07T16:30:00+00:00",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"currency_pair": "EURUSD"
}This endpoint allows a client to immediately book (multiple) orders from the market exchange rate between the requested currencies. Each amount has to be within the client’s limit thresholds (min-max). For more information regarding available and unavailable dates, see Get order dates. The requested orders are processed in a chronological order.
Request headers
Request body
The client’s security pin code
The bought currency
The sold currency
The fixed side of the order
If the buy side is fixed then the sell side will be calculated based on the rate
If the sell side is fixed then the buy side will be calculated based on the rate
The amount of the fixed side
The conversion date. If left out, the default value will be chosen. The default date and for more information regarding dates, see the Get order dates endpoint
Comment for the converison
A unique request ID to ensure order is not doubled-booked and to allow linking the request with the order response
Responses
Body
The id of the conversion
Reference used for transfering the funds
The amount of the buy side
The amount of the sell side
The charged comission for the client
The rate including commission
The currency of the buy side
The currency of the sell side
The conversion date where sell amount will be converted to buy amount. After the conversion the buy amount can be payed to the beneficiary
The primary pay in amount (downpayment for forwards, total amount for spots)
The date until the primary transfer amount has to be arrived
The secondary pay in amount (the remaining amount of forwards)
The date until the secondary transfer amount has to be arrived
Is true if the order is a forward and therefore a second amount has to be payed
The currency for the primary and secondary transfer amount
The currency pair in a standardized format
A unique request ID to ensure order is not doubled-booked and to allow linking the request with the order response
Body
For this endpoint, if the response code is 201, an array of objects is returned. An object in the array could either be a successfully booked order or an error object following the same structure as shown in API Error Object
With possible Error “reasons”:
- “error_parsing_date” - conversion date is not valid. Cannot be weekend or holiday
- “buy_currencies” - The buy currency is not available for the sell currency (e.g. RUB)
- “currencies” - One of the currencies is not a valid currency
- “error_parsing_currency_pair” - The currencypair is not available
- “buy_sell_type” - Request fixed_side is not valid
- “greather_than_zero” - The amount has to be greater than zero
- “pin_invalid” - The given pin is invalid
- “str_required” - A string has to be present for a required request attribute
- “too_many_requests” - There has been too many “pin_invalid” requests
- “client_limit_not_in_range” - Requested amount is greater than a client’s limit
- “limit_month_reached” - The requested amount is greater thant the client’s monthly limit
- “limit_day_reached” - The requested amount is greater thant the client’s daily limit
- “limit_trade_reached” - The requested amount is greater thant the client’s trade limit
- “required_validated_account” - A fully validated account is required
- “internal_service_error” - There is a Forexfix internal service error
- “duplicate_request” - The unique request id has already been used.
Examples
[
...
{
//succesfully booked order
},
...
{
"code": "unable_to_create_conversion",
"unique_request_id":"123456789",
"message": "Unable to create conversion.",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T17:37:11+00:00"
}
...
]Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_conversion”
The possible error “reasons”:
- “pin_invalid” - The given pin is invalid
- “too_many_conversions” - There are too many (cannot be greater than 10) requested orders
- “too_many_requests” - There has been too many “pin_invalid” requests
- “array_required” - An array with length greater than zero is required
Examples
{
"code": "unable_to_create_conversion",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}response containing successfully created order
POST https://api.forexfix.com/api/trade/conversion/market HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"pin": "1234",
"conversions": [
{
"buy_currency": "GBP",
"sell_currency": "EUR",
"fixed_side": "buy",
"amount": "10000",
"conversion_date": "2018-11-05",
"comment": "order comment",
"unique_request_id": "123456789"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json
[
{
"conversion_id": "91290323477",
"pay_in_reference": "20180309-CLVFFB",
"client_facing_buy_amount": "10000.00",
"client_facing_sell_amount": "8752.62",
"client_facing_rate": "1.1855",
"client_facing_commission": "17.47",
"buy_currency": "USD",
"sell_currency": "EUR",
"conversion_date": "2018-11-07T00:00:00+00:00",
"primary_transfer_amount": "875.27",
"primary_transfer_date": "2018-03-13T16:30:00+00:00",
"secondary_transfer_amount": "7877.35",
"secondary_transfer_date": "2018-11-07T16:30:00+00:00",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"currency_pair": "EURUSD",
"unique_request_id": "123456789"
}
...
]response containing successfully created order and error creating order
POST https://api.forexfix.com/api/trade/conversion/market HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"pin": "1234",
"conversions": [
{
"buy_currency": "GBP",
"sell_currency": "EUR",
"fixed_side": "buy",
"amount": "10000",
"conversion_date": "2018-11-05",
"comment": "order comment",
"unique_request_id": "123456789"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json
[
{
"conversion_id": "91290323477",
"pay_in_reference": "20180309-CLVFFB",
"client_facing_buy_amount": "10000.00",
"client_facing_sell_amount": "8752.62",
"client_facing_rate": "1.1855",
"client_facing_commission": "17.47",
"buy_currency": "USD",
"sell_currency": "EUR",
"conversion_date": "2018-11-07T00:00:00+00:00",
"primary_transfer_amount": "875.27",
"primary_transfer_date": "2018-03-13T16:30:00+00:00",
"secondary_transfer_amount": "7877.35",
"secondary_transfer_date": "2018-11-07T16:30:00+00:00",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"currency_pair": "EURUSD",
"unique_request_id": "2345678790",
"rate_id": ""
},
...
{
"code": "unable_to_create_conversion",
"message": "Unable to create conversion.",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}
...
]The endpoint allows a client to create an order and pay the total bought funds to a beneficiary. The beneficiary must have the same currency as the bought curreny. It is possible to change or remove beneficiary details after the order has been booked.
Request headers
Request body
The beneficiary receiving the bought funds
Client comment for the converison
A unique request ID to ensure order is not doubled-booked and to allow linking the request with the order response
The user specific pin
If this paramater is set to true, the payment will always be sent through the swift system. If this is false the payment will be sent through the local payment system if possible (depended on the amount of the payment, the beneficiary bank account country and the beneficiary bank account currency)
Reason of the payment for
Payment reference which will be on the bank statement of the beneficiary
The Rate Id retrieved from the “Create rate” endpoint
Responses
Body
The buy currency including comission
The sell currency
The date of the converison
The exchange rate exluding the comission
The buy amount including comission
The sell amount including comission
Secondary transfer required is true if the order is a forward
The primary transfer amount. Deposit for forwards, full amount for spot orders
The secondary transfer amount. Remaining amount for forwards
The currency in which the primay and secondary amount should be transfered
The comission charges the customer for this trade
A unique request ID to ensure order is not doubled-booked and to allow linking the request with the order response
The beneficiary Id
The payment Id
The reason for payment
Payment reference shown on the beneficiaries bank statement
The conversion Id
Reference used for transfering the funds
The sell and buy currencypair in an standardized format
The date until the primary transfer amount has to be arrived
The date until the secondary transfer amount has to be arrived
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_conversion_to_beneficiary”
- “unable_to_create_payment_after_booking”
- “pin_invalid”
- “internal_service_error”
- “required_validated_account”
Please note, if error code “unable_to_create_payment_after_booking” is returned, this is an internal service error regarding creating the payment to beneficiary after the order was created. In this rare case, we will open a client ticket
With possible “unable_to_create_conversion_to_beneficiary” Error “reasons”:
- “rate_id_invalid” - The rate ID is invalid
- “rate_id_has_expired” - The rate ID has expired
- “str_required” - A string has to be present for a required request attribute
- “too_many_requests” - There has been too many “pin_invalid” requests
- “conversion_below_limit” - The amount of the requested rate is too small to create order
- “client_limit_not_in_range” - Requested amount is not within the client’s limit
- “limit_month_reached” - The requested amount is greater thant the client’s monthly limit
- “limit_day_reached” - The requested amount is greater thant the client’s daily limit
- “limit_trade_reached” - The requested amount is greater thant the client’s trade limit
- “beneficiary_not_found” - The requested beneficiary has not been found
- “conversion_currency_not_matching_beneficiary_currency” - The beneficiary country doesn’t match the bought currency
- “payment_type_not_available_for_beneficiary” - The beneficiary requires extra details for this payment type
Examples
{
"code": "unable_to_create_conversion_to_beneficiary",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/trade/conversion/beneficiary HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"beneficiary_id": "18711923627",
"comment": "my comment",
"unique_request_id": "2345678790",
"rate_id": "ALSKHSDF_983726421",
"pin": "6240",
"swift": "true",
"reason": "Invoice of payment '23111",
"reference": "Downpayment no:4432"
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"buy_currency": "GBP",
"sell_currency": "EUR",
"conversion_date": "2017-09-19T13:00:00Z",
"client_facing_rate": "0.8894",
"client_facing_buy_amount": "20.00",
"client_facing_sell_amount": "22.49",
"client_facing_commission": 0.43,
"client_facing_commission_currency": "EUR",
"secondary_transfer_required": true,
"primary_transfer_amount": "22.92",
"primary_transfer_date": "2018-03-13T16:30:00+00:00",
"secondary_transfer_amount": "0.00",
"secondary_transfer_date": "2018-11-07T16:30:00+00:00",
"transfer_currency": "EUR",
"unique_request_id": "123456789",
"beneficiary_id": "18711923627",
"payment_id": "94345660902",
"reason": "Invoice of payment '23111",
"reference": "Downpayment no:4432",
"conversion_id": "33700278091",
"pay_in_reference": "20180309-CLVFFB",
"currency_pair": "EURGBP"
}The endpoint returns exchange rates from a start date to the current day. The exchange rate given on the current day is up to 60seconds old. The rates included in this api DO NOT include any commission.
Request headers
Request body
The starting currency pair
The end currency pair
The starting date for the rates to be returned
Responses
Body
The rate at the given date
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “too_many_requests”
With possible Error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_create_rate",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}GET https://api.forexfix.com/api/trade/rate/historic HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"end_currency": "USD",
"start_currency": "EUR",
"start_date": "2018-07-24"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"2018-07-24": 1.16877,
"2018-07-25": 1.174121,
"2018-07-26": 1.164687,
"2018-07-27": 1.16536,
"2018-07-28": 1.16536,
"2018-07-29": 1.166011,
...
"2018-08-18": 1.144852,
"2018-08-19": 1.143792,
"2018-08-20": 1.148894,
"2018-08-21": 1.157428,
"2018-08-22": 1.158779,
"2018-08-23": 1.154155,
"2018-08-24": 1.158916
}This endpoint returns a list of required beneficiary details based on the account currency, the account country, the beneficiary country, the beneficiary entity type, the amount of the payment. This endpoint should be used before creating a beneficiary. If the client wants required beneficiary information only for swift payments, the “swift” attribute should be set to true. More information here Local/Regular and Swift/Priority payment
Request body
Country where the beneficiaries bank account lies
Currency of the bank account
Entity type of the beneficiary
Residence country of the beneficiary
If the payment amount for the beneficiary is already known. The the amount is important for the differentation between local and swift payment. Local payment is only possible up until certain amounts
If regular payment is possible but this option is set to true, then it will always return the required information for swift payment. If set to false the endpoint will return the required local payment information if local payment is possible (dependend on amount, bank_account_country and bank_currency)
Responses
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_get_beneficiary_details”
The possible “unable_to_get_beneficiary_details” error “reasons”:
- “str_required” - A string has to be present for a required request attribute
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_get_beneficiary_details",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}Body
Basic information required for creating the beneficiary
The beneficiary entity type: can be “company” or “individual”
Indicates whether the field is required
The matching regex required for validation
The address of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The city of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The two-letter country code of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The company name of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The state or province of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The post code of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The first name of the beneficiary
Indicates whether the field is required
The matching regex required for validation
The last name of the beneficiary
Indicates whether the field is required
The matching regex required for validation
Account information types required for creating the beneficiary
POST https://api.forexfix.com/api/data/beneficiary_details HTTP/1.1
Content-Type: application/json
{
"amount": 1000,
"bank_account_country": "US",
"bank_currency": "USD",
"beneficiary_country": "US",
"entity_type": "company",
"swift":false
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"basic_information": {
"beneficiary_entity_type": {
"required": true,
"regular_expression": "^.{1,255}"
},
"beneficiary_address": {
"required": true,
"regular_expression": "^.{1,255}"
},
"beneficiary_city": {
"required": true,
"regular_expression": "^.{1,255}"
},
"beneficiary_country": {
"required": true,
"regular_expression": "^[A-z]{2}$"
},
"beneficiary_company_name": {
"required": true,
"regular_expression": "^.{1,255}"
},
"beneficiary_state_or_province": {
"required": false,
"regular_expression": "^.{1,255}"
},
"beneficiary_post_code": {
"required": true,
"regular_expression": "^.{1,255}"
},
"beneficiary_first_name": {
"required": true,
"regular_expression": "^.{1,255}"
},
"beneficiary_last_name": {
"required": true,
"regular_expression": "^.{1,255}"
}
},
"account_information": [
{
"account_number":"^[0-9A-Z]{1,50}$",
"sort_code":"^\d{6}$"
},
{
"iban":"([A-Z0-9]\s*){15,34}"
}
]
}This endpoint allows the client to create beneficiaries. Beneficiaries are needed in order to payout funds by means of a payment. Different details are required for creating a beneficiary based on the account currency, the account country, the beneficiary country, the beneficiary entity type, the amount of the payment. For further details, please see Get required beneficiary details and Local/Regular and Swift/Priority payment
Request headers
Request body
The name of the bank account holder
The currency of the bank account
The country where the bank account was created
account number
[cond required] Depended on bank_account_currency and bank_account_country
ABA routing number for USD accounts
[cond required] Depended on bank_account_currency and bank_account_country
International SWIFT Code
[cond required] Depended on bank_account_currency and bank_account_country
IBAN Code of bank account
[cond required] Depended on bank_account_currency and bank_account_country
Sort code for GBP accounts
[cond required] Depended on bank_account_currency and bank_account_countrySort Code for GBP Accounts
BSB Code for AUD Accounts
[cond required] Depended on bank_account_currency and bank_account_country
Institution number for CAD Accounts
[cond required] Depended on bank_account_currency and bank_account_country
Bank code
[cond required] Depended on bank_account_currency and bank_account_country
Bank branch code
[cond required] Depended on bank_account_currency and bank_account_country
Clabe for mexican accounts
[cond required] Depended on bank_account_currency and bank_account_country
Cnaps code for CNY accounts
[cond required] Depended on bank_account_currency and bank_account_country
IFSC for INR Accounts (not yet active)
[cond required] Depended on bank_account_currency and bank_account_country
Entitiy type of the beneficiary
Company name of the beneficiary
[cond_required] Required if entity_type is company
First name of the beneficiary
[cond_required] Required if entity_type is individual
Last name of the beneficiary
[cond_required] Required if entity_type is individual
Beneficiaries country of residence
Address of the beneficiary
[cond required] Depended on bank_account_currency and bank_account_country
Post code of the beneficiary address
[cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
City of the beneficiary
[cond required] Depended on bank_account_currency and bank_account_country
State (US, Mexico), Province (Canada) of the beneficiary
[cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
The client’s given reference
A reference used to identify the API partner
A reference used by the API partner to identify the beneficiary. Required in conjunction with “origin_reference”.
Responses
Body
The Id of the created beneficiary
The client’s given reference
Body
For this endpoint we always return an array of objects. An object in the array could either be a successfully created beneficiary or an error object following the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_beneficiary”
- “unable_to_validate_beneficiary”
The possible “unable_to_create_beneficiary” error “reasons”:
- “str_required” - A string has to be present for a required request attribute
- “user_is_restricted” - The user cannot perfom this action as the user is restricted
- “country” - The country is not allowed or requested in an incorrect format
- “internal_service_error” - There is a Forexfix internal service error
The possible “unable_to_validate_beneficiary” error “reasons”:
- “beneficiary_country_is_required”
- “beneficiary_country_is_in_invalid_format”
- “beneficiary_entity_type_not_in_range”
- “beneficiary_entity_type_is_missing”
- “beneficiary_company_name_is_missing”
- “beneficiary_first_name_is_missing”
- “beneficiary_last_name_is_missing”
- “beneficiary_city_is_missing”
- “beneficiary_state_or_province_is_missing”
- “beneficiary_state_or_province_is_not_supported”
- “beneficiary_postcode_is_missing”
- “beneficiary_date_of_birth_type_is_wrong”
- “account_number_is_too_short”
- “account_number_is_too_long”
- “account_number_is_missing”
- “account_number_is_invalid”
- “routing_code_value_1_is_too_short”
- “routing_code_value_1_is_too_long”
- “routing_code_value_2_is_too_short”
- “routing_code_value_2_is_too_long”
- “iban_is_too_short”
- “iban_is_too_long”
- “iban_is_missing”
- “iban_is_invalid”
- “bic_swift_is_too_short”
- “bic_swift_is_too_long”
- “bic_swift_is_missing”
- “bic_swift_is_invalid”
- “bank_address_is_missing”
- “bank_address_is_too_short”
- “bank_address_is_too_long”
- “bank_name_is_too_short”
- “bank_name_is_too_long”
- “bank_name_is_missing”
- “bank_name_is_invalid”
- “bank_account_type_not_in_range”
- “bank_account_type_is_missing”
- “bank_country_is_required”
- “bank_country_is_in_invalid_format”
- “bank_country_is_not_supported”
- “currency_is_required”
- “currency_is_in_invalid_format”
- “currency_code_is_invalid”
- “unique_value_parameters”
- “beneficiary_create_failed”
- “beneficiary_details_are_missing”
- “payment_types_not_in_range”
- “sort_code_is_missing”
- “sort_code_is_invalid”
- “aba_is_missing”
- “aba_is_invalid”
- “bsb_code_is_missing”
- “bsb_code_is_invalid”
- “branch_code_is_missing”
- “branch_code_is_invalid”
- “institution_no_is_missing”
- “institution_no_is_invalid”
- “bank_code_is_missing”
- “bank_code_is_invalid”
- “cnaps_is_missing”
- “cnaps_is_invalid”
- “payment_type_is_not_supported”
- “clabe_is_missing”
- “clabe_is_invalid”
Examples
[
{
"beneficiary_id": 57639236993,
"your_reference": "Beneficiary_#123"
},
...
{
"code": "unable_to_create_beneficiary",
"message": "Unable to create beneficiary.",
"your_reference": "Beneficiary_#666"
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T17:37:11+00:00"
}
...
]Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_create_beneficiary”
The possible error “reasons”:
- “array_required” - An array with length is required
- “user_is_restricted” - The user is restricted
- “internal_service_error” - There is a Forexfix internal service error
POST https://api.forexfix.com/api/beneficiaries/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
[
{
"bank_account_holder_name": "ABC Limited",
"bank_account_currency": "GBP",
"bank_account_country": "GB",
"account_number": "63421098",
"aba": "63421098",
"bic_swift": "COBADEFFXXX",
"iban": "DE78123412341234123434",
"sort_code": "231235",
"bsb_code": "082902",
"institution_no": "830",
"bank_code": "443254",
"branch_code": "081",
"clabe": "032180000118359719",
"cnaps": "123456789012",
"ifscCode": "SBIN0000058",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": "ABC Limited",
"beneficiary_first_name": "John",
"beneficiary_last_name": "Doe",
"beneficiary_country": "GB",
"beneficiary_address": "Smith Street",
"beneficiary_postcode": "AH 342",
"beneficiary_city": "London",
"beneficiary_state_or_province": "New York",
"your_reference": "Beneficiary_#123"
}
...
]
HTTP/1.1 201 Created
Content-Type: application/json
[
{
"beneficiary_id": "57639236993",
"your_reference": "Beneficiary_#123"
},
...
{
"code": "unable_to_create_beneficiary",
"message": "Unable to create beneficiary.",
"your_reference": "Beneficiary_#666",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T17:37:11+00:00"
}
...
]This endpoint returns the amount already allocated in payments to beneficiaries and available amount for further payments for a requested order.
Request headers
Request body
The order id
Responses
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_get_available_payment_amount”
The possible “unable_to_get_available_payment_amount” error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_get_available_payment_amount",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}Body
The leftover amount available in the given order
The amount already processed in the given order
POST https://api.forexfix.com/api/payment/amounts HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"conversion_id": "21263026032"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment_amount_available": 103000,
"payment_amount_processed": 11251.04
}This endpoint allows a client to create payment (payout). A payment pays out funds to a beneficiary. The payment amount does not have to equal the total converted funds but can be split into smaller payments. The payment does not have to be linked directly to a order but can be paid separatly. For information regarding available payment amounts for a linked order, please see Get available payment amount.
Request headers
Request body
Amount of the payment
Beneficiary ID of the beneficiary who should receive the payment
Conversion ID of the connected order
Currency of the payment
User Pin to confirm the payment
Payment reference which will be on the bank statement of the beneficiary
If this paramater is set to true, the payment will always be sent through the swift system. If this is false the payment will be sent through the local payment system if possible (depended on the amount of the payment, the beneficiary bank account country and the beneficiary bank account currency)
Responses
Body
Id of the payment
Id of the conversion
Id of the beneficiary
Amount of the payment
Currency of the payment
Payment Status
Payment reference shown on the beneficiaries bank statement
Reason of the payment
Payment type
Wished date of the payment
The exchange rate for the last created conversion converting into the currency of the payment
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_create_payment”
With possible “unable_to_create_payment” “reasons”:
- “payment_type_not_available_for_beneficiary” - The beneficiary payment type is not correct for this payment (for example payment can only sent through swift but beneficiary details are only for local payment). This issue can be fixed by calling the Get required beneficiary details endpoint
- “payment_date_is_too_early” - The payment date is too early
- “payment_date_is_in_invalid_format” - The payment date is an invalid format
- “invalid_payment_date” - The payment date is invalid
- “invalid_amount_for_order” - There is not enough unallocated funds for the payment amount
- “invalid_currency” - The payment currency is invalid
- “greather_than_zero” - The amount has to be greater than zero
- “pin_invalid” - The given pin is invalid
- “str_required” - A string has to be present for a required request attribute
- “too_many_requests” - There has been too many “pin_invalid” requests
- “required_validated_account” - A fully validated account is required
- “internal_service_error” - There is a Forexfix internal service error
- “payment_currency_not_matching_beneficiary_currency” The currency for the payment has to match the currency of the beneficiary
Examples
{
"code": "unable_to_create_payment",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/payment/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"amount": "5000",
"beneficiary_id": "2738120859",
"conversion_id": "22506410080",
"currency": "USD",
"pin": "4729",
"reason": "payment of supplier",
"reference": "Downpayment no:4432",
"swift":false
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"amount": 5000,
"currency": "USD",
"status": "ready_to_send",
"reference": "Invoice #2342",
"reason": "Paying suppliers",
"payment_type": "regular",
"payment_date": "2018-03-12",
"beneficiary_id": "2738120859",
"conversion_id": "22506410080",
"payment_id": "49695635168"
}This endpoint returns the list of beneficiaries for a client. List can be filtered by bank account currency or a beneficiary Id.
Request headers
Request body
optional parameter to filter the list by the bank_account_currency
optional paramter to filter the list by the id
Sort the returned array
ascending order (oldest to newest)
descending order (newest to oldest)
The page number
The amount of results per page
Responses
Body
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_get_beneficiary_list”
The possible “unable_to_create_beneficiary” error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_get_beneficiary_list",
"message": "...",
"reasons": [
..
],
"errors": [
..
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/beneficiaries/list HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"currency": "GBP"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"sort": "desc",
"page": 1,
"per_page": 50,
"total": 1
},
"results": [
{
"beneficiary_id": "1061748205",
"bank_account_holder_name": "ABC Limited",
"bank_account_currency": "GBP",
"bank_account_country": "GB",
"account_number": "10004545",
"sort_code": "402141",
"bsb_code": "563",
"bic_swift": "",
"iban": "",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": "ABC Limited",
"beneficiary_first_name": "John",
"beneficiary_last_name": "Doe",
"beneficiary_country": "GB",
"beneficiary_address": "Smith street 23",
"beneficiary_postcode": "rh19 5ck",
"beneficiary_city": "London",
"beneficiary_state_or_province": "New York",
"created_at": "2017-09-14T14:46:10+00:00",
"active": true,
"user_id": "8083910448",
"your_reference": "Beneficiary_#123"
}
....
]
}This endpoint allows the client to update a beneficiary. It is not possible to update the “currency” and “bankCountry” for an existing beneficiary. Different details are required for creating/updating a beneficiary based on the account currency, the account country, the beneficiary country, the beneficiary entity type, the amount of the payment. For further details, please see Get required beneficiary details and Local/Regular and Swift/Priority payment. To return the current beneficiary details, use Get beneficiary list filtered by beneficiary Id.
Request headers
Request body
The Id of the beneficiary to be updated
The user specific pin
The client’s given reference
The name of the bank account holder
account number [cond required] Depended on bank_account_currency and bank_account_country
ABA routing number for USD accounts [cond required] Depended on bank_account_currency and bank_account_country
International SWIFT Code [cond required] Depended on bank_account_currency and bank_account_country
IBAN Code of bank account [cond required] Depended on bank_account_currency and bank_account_country
Sort code for GBP accounts [cond required] Depended on bank_account_currency and bank_account_countrySort Code for GBP Accounts
BSB Code for AUD Accounts [cond required] Depended on bank_account_currency and bank_account_country
Institution number for CAD Accounts [cond required] Depended on bank_account_currency and bank_account_country
Bank code [cond required] Depended on bank_account_currency and bank_account_country
Bank branch code [cond required] Depended on bank_account_currency and bank_account_country
Clabe for mexican accounts [cond required] Depended on bank_account_currency and bank_account_country
Cnaps code for CNY accounts [cond required] Depended on bank_account_currency and bank_account_country
IFSC for INR Accounts (not yet active) [cond required] Depended on bank_account_currency and bank_account_country
Entitiy type of the beneficiary
Company name of the beneficiary [cond_required] Required if entity_type is company
First name of the beneficiary [cond_required] Required if entity_type is individual
Last name of the beneficiary [cond_required] Required if entity_type is individual
Beneficiaries country of residence
Address of the beneficiary [cond required] Depended on bank_account_currency and bank_account_country
Post code of the beneficiary address [cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
City of the beneficiary [cond required] Depended on bank_account_currency and bank_account_country
State (US, Mexico), Province (Canada) of the beneficiary [cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
Responses
Body
The Id of the beneficiary
The client’s given reference
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_update_beneficiary”
The possible “unable_to_update_beneficiary” error “reasons”:
- “str_required” - A string has to be present for a required request attribute
- “user_is_restricted” - The user cannot perfom this action as the user is restricted
- “country” - The country is not allowed or requested in an incorrect format
- “internal_service_error” - There is a Forexfix internal service error
- “pin_invalid” - The given pin is invalid
- “too_many_requests” - There has been too many “pin_invalid” requests
- “str_not_allowed” - This attribute cannot be present for update
The possible “unable_to_validate_beneficiary” error “reasons”:
- “beneficiary_country_is_required”
- “beneficiary_country_is_in_invalid_format”
- “beneficiary_entity_type_not_in_range”
- “beneficiary_entity_type_is_missing”
- “beneficiary_company_name_is_missing”
- “beneficiary_first_name_is_missing”
- “beneficiary_last_name_is_missing”
- “beneficiary_city_is_missing”
- “beneficiary_state_or_province_is_missing”
- “beneficiary_state_or_province_is_not_supported”
- “beneficiary_postcode_is_missing”
- “beneficiary_date_of_birth_type_is_wrong”
- “account_number_is_too_short”
- “account_number_is_too_long”
- “account_number_is_missing”
- “account_number_is_invalid”
- “routing_code_value_1_is_too_short”
- “routing_code_value_1_is_too_long”
- “routing_code_value_2_is_too_short”
- “routing_code_value_2_is_too_long”
- “iban_is_too_short”
- “iban_is_too_long”
- “iban_is_missing”
- “iban_is_invalid”
- “bic_swift_is_too_short”
- “bic_swift_is_too_long”
- “bic_swift_is_missing”
- “bic_swift_is_invalid”
- “bank_address_is_missing”
- “bank_address_is_too_short”
- “bank_address_is_too_long”
- “bank_name_is_too_short”
- “bank_name_is_too_long”
- “bank_name_is_missing”
- “bank_name_is_invalid”
- “bank_account_type_not_in_range”
- “bank_account_type_is_missing”
- “bank_country_is_required”
- “bank_country_is_in_invalid_format”
- “bank_country_is_not_supported”
- “currency_is_required”
- “currency_is_in_invalid_format”
- “currency_code_is_invalid”
- “unique_value_parameters”
- “beneficiary_create_failed”
- “beneficiary_details_are_missing”
- “payment_types_not_in_range”
- “sort_code_is_missing”
- “sort_code_is_invalid”
- “aba_is_missing”
- “aba_is_invalid”
- “bsb_code_is_missing”
- “bsb_code_is_invalid”
- “branch_code_is_missing”
- “branch_code_is_invalid”
- “institution_no_is_missing”
- “institution_no_is_invalid”
- “bank_code_is_missing”
- “bank_code_is_invalid”
- “cnaps_is_missing”
- “cnaps_is_invalid”
- “payment_type_is_not_supported”
- “clabe_is_missing”
- “clabe_is_invalid”
Examples
{
"code": "unable_to_update_beneficiary",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/beneficiaries/update HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"beneficiary_id": "2913318580",
"pin": "2231",
"your_reference": "Beneficiary_#123",
"bank_account_holder_name": "ABC Limited",
"account_number": "63421098",
"aba": "63421098",
"bic_swift": "COBADEFFXXX",
"iban": "DE78123412341234123434",
"sort_code": "231235",
"bsb_code": "082902",
"institution_no": "830",
"bank_code": "443254",
"branch_code": "081",
"clabe": "032180000118359719",
"cnaps": "123456789012",
"ifscCode": "SBIN0000058",
"beneficiary_entity_type": "company",
"beneficiary_company_name": "ABC Limited",
"beneficiary_first_name": "John",
"beneficiary_last_name": "Doe",
"beneficiary_country": "GB",
"beneficiary_address": "Smith Street",
"beneficiary_postcode": "AH 342",
"beneficiary_city": "London",
"beneficiary_state_or_province": "New York"
}
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"beneficiary_id": "57639236993",
"your_reference": "Beneficiary_#123"
}This endpoint allows a client to deactivate a beneficiary. Is only possible when there are no active payments and client has no endpoint restriction.
Request headers
Request body
Id of the beneficiary which should be deactivated
Responses
Body
Body
The error object follows the same structure as shown in API Error Object The possible Error top level “code”:
- “unable_to_deactivate_beneficiary”
With possible “unable_to_deactivate_beneficiary” Error “reasons”:
- “user_is_restricted” - The user cannot perfom this action as the user is restricted
- “beneficiary_has_active_payments” - There are active payments to this beneficiary
- “beneficiary_not_found” - The given beneficiary ID has not been found
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_deactivate_beneficiary",
"message": "Unable to deactivate beneficiary.",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T17:37:11+00:00"
}POST https://api.forexfix.com/api/beneficiaries/deactivate HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"beneficiary_id": "3285505146"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ok": true
}This endpoint allows the client to validate a beneficiary. Different details are required for creating a beneficiary based on the account currency, the account country, the beneficiary country, the beneficiary entity type, the amount of the payment. For further details, please see Get required beneficiary details and Local/Regular and Swift/Priority payment.
Request headers
Request body
account number [cond required] Depended on bank_account_currency and bank_account_country
ABA routing number for USD accounts [cond required] Depended on bank_account_currency and bank_account_country
International SWIFT Code [cond required] Depended on bank_account_currency and bank_account_country
IBAN Code of bank account [cond required] Depended on bank_account_currency and bank_account_country
Sort code for GBP accounts [cond required] Depended on bank_account_currency and bank_account_countrySort Code for GBP Accounts
BSB Code for AUD Accounts [cond required] Depended on bank_account_currency and bank_account_country
Institution number for CAD Accounts [cond required] Depended on bank_account_currency and bank_account_country
Bank code [cond required] Depended on bank_account_currency and bank_account_country
Bank branch code [cond required] Depended on bank_account_currency and bank_account_country
Clabe for mexican accounts [cond required] Depended on bank_account_currency and bank_account_country
Cnaps code for CNY accounts [cond required] Depended on bank_account_currency and bank_account_country
IFSC for INR Accounts (not yet active) [cond required] Depended on bank_account_currency and bank_account_country
Entitiy type of the beneficiary
Beneficiaries country of residence
Address of the beneficiary [cond required] Depended on bank_account_currency and bank_account_country
Post code of the beneficiary address [cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
City of the beneficiary [cond required] Depended on bank_account_currency and bank_account_country
State (US, Mexico), Province (Canada) of the beneficiary [cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
Responses
Body
true
Body
The error object follows the same structure as shown in API Error Object.
The Error top level “code”:
- “unable_to_validate_beneficiary”
The possible “unable_to_validate_beneficiary” error “reasons”:
- “beneficiary_country_is_required”
- “beneficiary_country_is_in_invalid_format”
- “beneficiary_entity_type_not_in_range”
- “beneficiary_entity_type_is_missing”
- “beneficiary_company_name_is_missing”
- “beneficiary_first_name_is_missing”
- “beneficiary_last_name_is_missing”
- “beneficiary_city_is_missing”
- “beneficiary_state_or_province_is_missing”
- “beneficiary_state_or_province_is_not_supported”
- “beneficiary_postcode_is_missing”
- “beneficiary_date_of_birth_type_is_wrong”
- “account_number_is_too_short”
- “account_number_is_too_long”
- “account_number_is_missing”
- “account_number_is_invalid”
- “routing_code_value_1_is_too_short”
- “routing_code_value_1_is_too_long”
- “routing_code_value_2_is_too_short”
- “routing_code_value_2_is_too_long”
- “iban_is_too_short”
- “iban_is_too_long”
- “iban_is_missing”
- “iban_is_invalid”
- “bic_swift_is_too_short”
- “bic_swift_is_too_long”
- “bic_swift_is_missing”
- “bic_swift_is_invalid”
- “bank_address_is_missing”
- “bank_address_is_too_short”
- “bank_address_is_too_long”
- “bank_name_is_too_short”
- “bank_name_is_too_long”
- “bank_name_is_missing”
- “bank_name_is_invalid”
- “bank_account_type_not_in_range”
- “bank_account_type_is_missing”
- “bank_country_is_required”
- “bank_country_is_in_invalid_format”
- “bank_country_is_not_supported”
- “currency_is_required”
- “currency_is_in_invalid_format”
- “currency_code_is_invalid”
- “unique_value_parameters”
- “beneficiary_create_failed”
- “beneficiary_details_are_missing”
- “payment_types_not_in_range”
- “sort_code_is_missing”
- “sort_code_is_invalid”
- “aba_is_missing”
- “aba_is_invalid”
- “bsb_code_is_missing”
- “bsb_code_is_invalid”
- “branch_code_is_missing”
- “branch_code_is_invalid”
- “institution_no_is_missing”
- “institution_no_is_invalid”
- “bank_code_is_missing”
- “bank_code_is_invalid”
- “cnaps_is_missing”
- “cnaps_is_invalid”
- “payment_type_is_not_supported”
- “clabe_is_missing”
- “clabe_is_invalid”
Examples
{
"code": "unable_to_validate_beneficiary",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/beneficiaries/validate HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"account_number": "63421098",
"aba": "63421098",
"bic_swift": "COBADEFFXXX",
"iban": "DE78123412341234123434",
"sort_code": "231235",
"bsb_code": "082902",
"institution_no": "830",
"bank_code": "443254",
"branch_code": "081",
"clabe": "032180000118359719",
"cnaps": "123456789012",
"ifscCode": "SBIN0000058",
"beneficiary_entity_type": "company",
"beneficiary_country": "GB",
"beneficiary_address": "Smith Street",
"beneficiary_postcode": "AH 342",
"beneficiary_city": "London",
"beneficiary_state_or_province": "New York"
}
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"ok": true
}
This endpoint returns a payments list which can be filtered.
Request headers
Request body
Payments get filtered by the beneficiary id, if empty payments are not filtered by the beneficiary id
Payments get filtered by a list of status. If the array is empty, endpoint returns all payments
Payment is created and will be processed at payment date
Payment is in process
Payment is sent
The payment failed
Payments get filtered by the payment id
Sort the returned array
ascending order (oldest to newest)
descending order (newest to oldest)
The page number
The amount of results returned per page
Responses
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_get_payment_list”
The possible “unable_to_get_payment_list” error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_get_payment_list",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}Get all payments for a beneficiary ID
POST https://api.forexfix.com/api/payments/list HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"beneficiary_id": "2965911077"
}
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"payment_id": "18830664793",
"conversion_id": "29419170714",
"beneficiary_id": "2965911077",
"amount": 10,
"currency": "GBP",
"status": "payment_in_process",
"reference": "Transfer for goods #12345",
"reason": "paying suppliers",
"payment_type": "regular",
"payment_date": "2018-03-21",
"created_at": "2018-03-01T13:03:04+00:00",
"user_id": "8083910448"
}
...
]Get all finished payments
POST https://api.forexfix.com/api/payments/list HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
Content-Type: application/json
{
"status_filter": [
"payment_finished"
]
}
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"payment_id": "18830664793",
"conversion_id": "29419170714",
"beneficiary_id": "2965911077",
"amount": 10,
"currency": "GBP",
"status": "payment_finished",
"reference": "Transfer for goods #12345",
"reason": "paying suppliers",
"payment_type": "priority",
"payment_date": "2018-03-21",
"created_at": "2018-03-01T13:03:04+00:00",
"user_id": "8083910448"
}
...
]Get a specific payment
POST https://api.forexfix.com/api/payments/list HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"payment_id": "85763248199"
}
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"payment_id": "18830664793",
"conversion_id": "29419170714",
"beneficiary_id": "2965911077",
"amount": 10,
"currency": "GBP",
"status": "payment_in_process",
"reference": "Transfer for goods #12345",
"reason": "paying suppliers",
"payment_type": "regular",
"payment_date": "2018-03-21",
"created_at": "2018-03-01T13:03:04+00:00",
"user_id": "8083910448"
}
]This endpoint allows a client to update a payment (payout) from an order. The attributes for this endpoint are the same as Create a payment, apart from a payment Id is also given. For information regarding available update payment amounts for an order, please see Get available payment amount. To return the current payment details, use Get payments filtered by payment Id.
Request headers
Request body
Amount of the payment
Beneficiary ID of the beneficiary who should receive the payment
Conversion ID of the connected order
Currency of the payment
User Pin to confirm the payment
Reason of the payment for
Payment reference which will be on the bank statement of the beneficiary
The payment id of the payment that should be updated
If this paramater is set to true, the payment will always be sent through the swift system. If this is false the payment will be sent through the local payment system if possible (depended on the amount of the payment, the beneficiary bank account country and the beneficiary bank account currency)
Responses
Body
Amount of the payment
Currency of the payment
Payment Status
Payment reference shown on the beneficiaries bank statement
Reason of the payment
Payment type
Wished date of the payment
Id of the beneficiary
Id of the conversion
Id of the payment
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_update_payment”
With possible “unable_to_update_payment” “reasons”:
- “beneficiary_unabled_to_receive_swift” - The beneficiary is unable to receive swift payments
- “payment_date_is_too_early” - The payment date is too early
- “payment_date_is_in_invalid_format” - The payment date is an invalid format
- “invalid_payment_date” - The payment date is invalid
- “invalid_amount_for_order” - There is not enough unallocated funds for the payment amount
- “invalid_currency” - The payment currency is invalid
- “greather_than_zero” - The amount has to be greater than zero
- “pin_invalid” - The given pin is invalid
- “str_required” - A string has to be present for a required request attribute
- “too_many_requests” - There has been too many “pin_invalid” requests
- “required_validated_account” - A fully validated account is required
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_update_payment",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/payment/update HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"amount": "5000",
"payment_id": "85763248199",
"beneficiary_id": "2738120859",
"conversion_id": "22506410080",
"currency": "USD",
"swift": false,
"pin": "4729",
"reason": "Invoice of payment '23111",
"reference": "Downpayment no:4432"
}
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"amount": 5000,
"currency": "USD",
"status": "ready_to_send",
"reference": "Invoice #2342",
"reason": "Paying suppliers",
"payment_type": "regular",
"payment_date": "2018-03-12",
"beneficiary_id": "2738120859",
"conversion_id": "22506410080",
"payment_id": "49695635168"
}This endpoint allows a client to delete a payment.
Request headers
Request body
Id of the payment which should be deleted
Responses
Body
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_delete_payment”
The possible “unable_to_delete_payment” error “reasons”:
- “payment_not_found” - The payment cannot be found
- “required_validated_account” - Required a validated account
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_delete_payment",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T17:37:11+00:00"
}POST https://api.forexfix.com/api/payments/delete HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"payment_id": "3285505146"
}
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"ok": true
}This endpoint returns the details of a singular beneficiary for a client.
Request headers
Request body
optional paramter to filter the list by the id
A reference used to identify the API partner
A reference used by the API partner to identify the beneficiary. Required in conjunction with “origin_reference”.
Responses
Body
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “internal_service_error”
The possible “unable_to_create_beneficiary” error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "internal_service_error",
"message": "...",
"reasons": [
..
],
"errors": [
..
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/beneficiaries/get HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"beneficiary_id": "3285505146",
"origin_reference": "origin_reference",
"origin_reference_id": "FOREXFIX_PARTNER_BENEFICIARY_9PDHCH"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"beneficiary_id": "1061748205",
"bank_account_holder_name": "ABC Limited",
"bank_account_currency": "GBP",
"bank_account_country": "GB",
"account_number": "10004545",
"sort_code": "402141",
"bsb_code": "563",
"bic_swift": "",
"iban": "",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": "ABC Limited",
"beneficiary_first_name": "John",
"beneficiary_last_name": "Doe",
"beneficiary_country": "GB",
"beneficiary_address": "Smith street 23",
"beneficiary_postcode": "rh19 5ck",
"beneficiary_city": "London",
"beneficiary_state_or_province": "New York",
"created_at": "2017-09-14T14:46:10+00:00",
"active": true,
"user_id": "8083910448",
"your_reference": "Beneficiary_#123"
}This endpoint lists all active orders. Orders can be of type:
- “conversion”
- “payment”
Orders returned will NOT have a status of “conversion_completed”, “conversion_cancelled”, “payment_completed” and “payment_failed”.
Request parameters
sort the orders by creation date
page number
amount of orders return per page
Request headers
Responses
Body
What type of order the item is.
If the “order_type” is “conversion”, the ID of the conversion.
If “order_type” is payment, the ID of the payment
Array of payments with beneficiary details. ONLY present when “order_type” is “conversion”.
Original conversion details. ONLY present when “order_type” is “conversion”.
The payment details if the “order_type” is “payment”.
The total amount to be paid in.
The currency to be paid in.
The total amount to be paid out.
The currency to be paid out.
The date at which the payout will occur.
The date at which the order was created.
The current status of the order.
Indicates if a secondary transfer amount is required.
The todos for the order
The status for the primary transfer
Waiting for funds
Marked by client as done
Funds arrived
The status for the primary transfer
Waiting for funds
Marked by client as done
Funds arrived
Pagination object
Indicates which order the results are sorted
The returned page number
The amount of results per page
The total amount of results
GET https://api.forexfix.com/api/trade/order/list HTTP/1.1
Authorization: Bearer <auth_token>
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"conversion_id": "68035775189",
"order_type": "conversion",
"payments": [
{
"_id": "5b7abe08c83925027aed1bcf",
"amount": 6026.29,
"currency": "GBP",
"status": "waiting_for_primary",
"reference": "123",
"payment_date": "2018-08-21",
"created_at": "2018-08-20T13:11:36+00:00",
"beneficiary_id": "72188372060",
"conversion_id": "68035775189",
"payment_id": "28583800318",
"beneficiary": {
"payment_types": [
"regular"
],
"bank_account_holder_name": "GBP REAL",
"bank_account_currency": "GBP",
"bank_account_country": "GB",
"bank_name": "TEST BANK NAME",
"account_number": "1000000",
"beneficiary_country": "GB",
"beneficiary_entity_type": "company",
"beneficiary_company_name": "GBP REAL",
"beneficiary_address": "",
"created_at": "2018-08-20T13:11:20+00:00",
"bank_address": "TEST BANK ADDRESS, NOT USING EXTERNAL SERVICE, DEVELOPMENT ENVIRONMENT.",
"sort_code": "236972",
"beneficiary_id": "72188372060",
"active": true,
"client_id": "74561671",
"user_id": "4445446216"
}
}
],
"conversion": {
"partner_reference": "20180820-DWTFQG",
"partner_buy_amount": "6044.42",
"partner_rate": "0.8056",
"partner_sell_amount": "7503.00",
"currency_pair": "EURGBP",
"status": "waiting_for_primary",
"buy_currency": "GBP",
"sell_currency": "EUR",
"fixed_side": "sell",
"unique_request_id": "42092537479",
"execution_rate": "0.8032",
"settlement_date": "2018-08-21T13:00:00+00:00",
"conversion_date": "2018-08-21T00:00:00+00:00",
"secondary_transfer_required": false,
"transfer_currency": "EUR",
"unallocated_funds": "6026.29",
"created_at": "2018-08-20T13:08:44+00:00",
"updated_at": "2018-08-20T13:08:45+00:00",
"client_id": "74561671",
"user_id": "4445446216",
"comment": "",
"conversion_id": "68035775189",
"primary_transfer_date": "2018-08-21T13:00:00+00:00",
"primary_transfer_amount": "7503.00",
"secondary_transfer_date": "",
"secondary_transfer_amount": "0.00",
"ffix_commission_amount_gbp": "18.08",
"ffix_commission_amount_eur": 20.2,
"client_facing_rate": "0.8056",
"client_facing_buy_amount": "6026.29",
"client_facing_sell_amount": "7503.00",
"client_facing_commission": "18.13",
"pay_in_reference": "180509-00012 - N68035775189"
},
"payin_amount": "7503.00",
"payin_currency": "EUR",
"payout_amount": "6026.29",
"payout_currency": "GBP",
"execution_date": "2018-08-21T00:00:00+00:00",
"created_at": "2018-08-20T13:08:44+00:00",
"status": "waiting_for_primary",
"secondary_transfer_required": false,
"todos": {
"primary_status": "waiting_for_funds"
}
},
{
"payment_id": "59433898458",
"order_type": "payment",
"payment": {
"amount": 5000,
"currency": "GBP",
"status": "waiting_for_extra_funds",
"reference": "asd",
"reason": "payment to supplier",
"payment_type": "regular",
"payment_date": "2018-08-20",
"partner_reference": "180814-SFTFCG001",
"created_at": "2018-08-14T10:57:15+02:00",
"unique_request_id": "59433898458",
"client_id": "56231984",
"user_id": "4914428406",
"beneficiary_id": "17823204323",
"conversion_id": "",
"payment_id": "59433898458",
"beneficiary": {
"payment_types": [
"regular"
],
"bank_account_holder_name": "GBP test 2",
"bank_account_currency": "GBP",
"bank_account_country": "GB",
"bank_name": "TEST BANK NAME",
"account_number": "123456",
"beneficiary_country": "GB",
"beneficiary_entity_type": "company",
"beneficiary_company_name": "GBP test 2",
"beneficiary_address": "",
"created_at": "2018-08-09T15:53:52+00:00",
"bank_address": "TEST BANK ADDRESS, NOT USING EXTERNAL SERVICE, DEVELOPMENT ENVIRONMENT.",
"sort_code": "123456",
"beneficiary_email": "gerhard@forexfix.de",
"beneficiary_id": "17823204323",
"active": true,
"client_id": "56231984",
"user_id": "4914428406"
}
},
"payin_amount": 5000,
"payin_currency": "GBP",
"payout_amount": 5000,
"payout_currency": "GBP",
"execution_date": "2018-08-20",
"created_at": "2018-08-14T10:57:15+02:00",
"status": "waiting_for_extra_funds",
"todos": {
"primary_status": "waiting_for_funds"
}
}
],
"pagination": {
"sort": "desc",
"page": 1,
"per_page": 95,
"total": 1
}
}This endpoint lists order Receipts. Receipts are completed orders. Receipts are snapshots and can not be deleted or updated.
Request parameters
sort the orders by creation date
page number
The amount returned per page
Request headers
Responses
Body
What type of order the item is.
If the “order_type” is “conversion”, the ID of the conversion.
If “order_type” is payment, the ID of the payment
The payment details if the “order_type” is “payment”.
Original conversion details. ONLY present when “order_type” is “conversion”.
Array of payments with beneficiary details. ONLY present when “order_type” is “conversion”.
The total amount to be paid in.
The currency to be paid in.
The total amount to be paid out.
The currency to be paid out.
The date at which the payout will occur.
The date at which the order was created.
When the order was completed
The finished status of the order
GET https://api.forexfix.com/api/trade/order/historic/list HTTP/1.1
Authorization: Bearer <auth_token>
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"order_type": "conversion",
"payin_amount": "713.47",
"payin_currency": "EUR",
"payout_amount": "810.00",
"payout_currency": "USD",
"execution_date": "2018-09-06T00:00:00+00:00",
"created_at": "2018-08-10T13:58:07+00:00",
"status": "conversion_completed",
"conversion_id": "59166530470",
"conversion": {
"currency_pair": "EURUSD",
"status": "conversion_completed",
"buy_currency": "USD",
"sell_currency": "EUR",
"fixed_side": "buy",
"unique_request_id": "18438556394",
"settlement_date": "2018-09-06T15:30:00+00:00",
"conversion_date": "2018-09-06T00:00:00+00:00",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"unallocated_funds": "810.00",
"created_at": "2018-08-10T16:01:56+02:00",
"updated_at": "2018-08-10T13:58:07+00:00",
"user_id": "4914428406",
"comment": "",
"conversion_id": "59166530470",
"primary_transfer_date": "2018-08-15T15:58:08+02:00",
"primary_transfer_amount": "21.40",
"secondary_transfer_date": "2018-09-06T15:30:00+00:00",
"secondary_transfer_amount": "692.07",
"client_facing_rate": "1.1387",
"client_facing_buy_amount": "810.00",
"client_facing_sell_amount": "713.47",
"client_facing_commission": "2.13",
"pay_in_reference": "180809-00007 - N59166530470",
"payments": [],
"order_created_at": "2018-08-10T13:58:07+00:00"
},
"payments": [],
"completed_at": "2018-08-10T16:01:56+02:00"
},
{
"order_type": "conversion",
"payin_amount": "26424.87",
"payin_currency": "EUR",
"payout_amount": "30000.00",
"payout_currency": "USD",
"execution_date": "2018-09-07T00:00:00+00:00",
"created_at": "2018-08-10T12:45:33+00:00",
"status": "conversion_completed",
"conversion_id": "90368497442",
"conversion": {
"currency_pair": "EURUSD",
"status": "conversion_completed",
"buy_currency": "USD",
"sell_currency": "EUR",
"fixed_side": "buy",
"unique_request_id": "37421948187",
"settlement_date": "2018-09-07T15:30:00+00:00",
"conversion_date": "2018-09-07T00:00:00+00:00",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"unallocated_funds": "30000.00",
"created_at": "2018-08-10T14:59:23+02:00",
"updated_at": "2018-08-10T12:45:33+00:00",
"user_id": "4914428406",
"comment": "asdf",
"conversion_id": "90368497442",
"primary_transfer_date": "2018-08-15T12:48:16+00:00",
"primary_transfer_amount": "792.75",
"secondary_transfer_date": "2018-09-07T15:30:00+00:00",
"secondary_transfer_amount": "25632.12",
"ffix_commission_amount_gbp": "71.14",
"ffix_commission_amount_eur": 79.27,
"client_facing_rate": "1.1387",
"client_facing_buy_amount": "30000.00",
"client_facing_sell_amount": "26424.87",
"client_facing_commission": "79.04",
"pay_in_reference": "180809-00007 - N90368497442",
"payments": [],
"order_created_at": "2018-08-10T12:45:33+00:00"
},
"payments": [],
"completed_at": "2018-08-10T14:59:23+02:00"
}
],
"pagination": {
"sort": "desc",
"page": 1,
"per_page": 50,
"total": 12
}
}This endpoint lists all active conversions. conversions that do not have a status of “conversion_completed” and “conversion_cancelled”
Request parameters
sort the orders by creation date
page number
amount of orders return per page
Request headers
Responses
Body
sorting order
page number
Number of objects per page
Total number of objects
Reference used for transfering the funds
The sell and buy currencypair in an standardized format
Standardized currency pair of the order
Primary amount has to be payed
Secondary amount has to be payed (only with forwards)
Payin amount fully received -> Conversion will be converted on conversion date
Conversion has converted, payment will be fulfilled on payment date
Buy currency of the order
Sell currency of the order
Fixed Side
Sell side is fixed
Buy side is fixed
Rate including all charges
Date when the conversion happens
Indicates if a secondary payin amount is required (only if a forward)
Currency in which the payin amount has to be transfered
Timestamp when the order was created
Timestamp when the order was last updated
User Id of the order creator
Order comment
Id of the conversion
Date until the primary amount has to arrive
Amount of the primary payin transfer
Date until the secondary amount has to arrive. (Only for forwards)
Amount of the secondary payin transfer. (only for forwards)
Rate without fees
Buy amount. Including all fees if fixed_side is sell
Sell amount. Including all fees if fixed_side is buy
Comission of the conversion
Array of payments with beneficiary details for order
GET https://api.forexfix.com/api/trade/conversion/list HTTP/1.1
Authorization: Bearer <auth_token>
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"sort": "desc",
"page": 1,
"per_page": 50,
"total": 1
},
"results": [
{
"pay_in_reference": "20180118-CYPGNH",
"currency_pair": "EURUSD",
"status": "waiting_for_primary",
"buy_currency": "USD",
"sell_currency": "EUR",
"fixed_side": "buy",
"execution_rate": "1.1365",
"conversion_date": "2018-02-01T00:00:00+00:00",
"secondary_transfer_required": true,
"transfer_currency": "EUR",
"created_at": "2018-01-18T10:43:51+00:00",
"updated_at": "2018-01-18T10:43:51+00:00",
"user_id": "8065556952",
"comment": "1234",
"conversion_id": "59378979463",
"primary_transfer_date": "2018-01-22T16:30:00+00:00",
"primary_transfer_amount": "300.00",
"secondary_transfer_date": "2018-02-01T16:30:00+00:00",
"secondary_transfer_amount": "9700.00",
"client_facing_rate": "1.1388",
"client_facing_buy_amount": "11365.22",
"client_facing_sell_amount": "10000.00",
"client_facing_commission": "22.78",
"payments": [
{
"payment_id": "18830664793",
"conversion_id": "29419170714",
"beneficiary_id": "2965911077",
"amount": 10,
"currency": "GBP",
"status": "ready_to_send",
"reference": "Payment of invoice #12232",
"reason": "Client id #2234 invoice#12232",
"payment_type": "priority",
"payment_date": "2018-03-21",
"created_at": "2018-03-01T13:03:04+00:00",
"user_id": "8083910448",
"beneficiary": {
"beneficiary_id": "1061748205",
"bank_account_holder_name": "ABC Limited",
"bank_account_currency": "GBP",
"bank_account_country": "GB",
"account_number": "10004545",
"sort_code": "402141",
"bsb_code": "563",
"bic_swift": "",
"iban": "",
"beneficiary_entity_type": "individual",
"beneficiary_company_name": "ABC Limited",
"beneficiary_first_name": "John",
"beneficiary_last_name": "Doe",
"beneficiary_country": "GB",
"beneficiary_address": "Smith street 23",
"beneficiary_postcode": "rh19 5ck",
"beneficiary_city": "London",
"beneficiary_state_or_province": "New York",
"created_at": "2017-09-14T14:46:10+00:00",
"active": true,
"user_id": "8083910448"
},
"transferred_at": "2018-03-09T14:16:56+00:00"
}
]
}
]
}This endpoint returns notifications for the client.
Request headers
Request body
Sort the returned array
descending order (newest to oldest)
ascending order (oldest to newest)
The amount of notifications per page
The page number
Include the notifications that have notification types
Notification about the primary trasnfer
Notification about the secondary transfer
Notification that the primary transfer amount didn’t arrive on time at the settlement account
Notification that the secondary transfer amount didn’t arrive on time at the settlement account
Notification that the primary amount has been received
Notification that the secondary amount has been received
Notification 7-5 days before the conversion date that the secondary amount has to be provided soon
Notification 1 day before the conversion date that the secondary amount has to be provided soon
Notification that no payment has been added to an order
Notification that the payment failed (did not arrive at the beneficiaries account)
Notification that the conversion has settled and the funds are ready to be sent
Notification that the trade was cancelled
Notification that the payment is completed
Set this parameter to true in order to include inactive notifications
Exclude the notifications that have notification types
Notification about the primary trasnfer
Notification about the secondary transfer
Notification that the primary transfer amount didn’t arrive on time at the settlement account
Notification that the secondary transfer amount didn’t arrive on time at the settlement account
Notification that the primary amount has been received
Notification that the secondary amount has been received
Notification 7-5 days before the conversion date that the secondary amount has to be provided soon
Notification 1 day before the conversion date that the secondary amount has to be provided soon
Notification that no payment has been added to an order
Notification that the payment failed (did not arrive at the beneficiaries account)
Notification that the conversion has settled and the funds are ready to be sent
Notification that the trade was cancelled
Notification that the payment is completed
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “internal_service_error”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "internal_service_error",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/client/notifications HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"sort": "asc",
"per_page": 50,
"page_number": 1
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"sort": "desc",
"page": 1,
"per_page": 50,
"total": 1
},
"results": [
{
"_id": "5a5f854cc416e96a6ac2edc2",
"timestamp": "2018-01-16T16:51:56+00:00",
"client_id": "72583733",
"user_id": "8065556952",
"type": "notification_secondary_transfer_late",
"message": "You are required to provide the down-payment of EUR 30.00 by 19.01.2018 for order #48213571161.",
"status": "active",
"details": {
....
....
},
"status_user": "marked_as_done"
}
...
]
}This endpoint allows a client to mark a notification as done
Request headers
Request body
Id of the notification
Fill with “marked_as_done” if done, leave empty string if unmark
POST https://api.forexfix.com/api/client/notifications/update HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"id": "5aa6de17a3ea463986e3e08f",
"marked": "marked_as_done"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ok": true
}This endpoint returns the top most requested currencies for a client.
Request headers
Responses
Body
Count of how many times currency pair has been requested.
The starting currency pair.
The Ending currency pair.
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “internal_service_error”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "internal_service_error",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}GET https://api.forexfix.com/api/user/currencies/top HTTP/1.1
Authorization: Bearer <auth_token>
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"count": 1045,
"start_currency": "EUR",
"end_currency": "USD"
},
{
"count": 549,
"start_currency": "EUR",
"end_currency": "GBP"
},
{
"count": 86,
"start_currency": "EUR",
"end_currency": "CHF"
},
{
"count": 80,
"start_currency": "EUR",
"end_currency": "THB"
},
...
]Returns the limits of each currency for each transaction
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “internal_service_error”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "internal_service_error",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}GET https://api.forexfix.com/api/data/rates/limit HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"AED": {
"max": 472635.5,
"min": 9
},
....
"EUR": {
"max": 104475,
"min": 1.99
},
...
"ZWL": {
"max": 41485686.79,
"min": 790.2
},
"timestamp": "2018-03-14T15:01:05+00:00"
}This endpoint returns information about order dates. Orders cannot be placed on any of the dates specified in the “holidays” attribute of the response. Orders cannot be placed on the weekend, the cut off time for the weekend is between Friday 20:00GMT to Monday 06:00GMT.
Request headers
Request body
First currency of currency pair
Second currency of currencypair
Responses
Body
Holiday object indicating which dates are not available due to holidays
The key of the object is the date set to ‘true’ indicating a holiday on this date
The first available conversion date
The default conversion date
The final available conversion date
The next available conversion date AFTER the “first_conversion_date”
The next available conversion date AFTER the “next_available_conversion_date”
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_get_conversion_dates”
The possible error “reasons”:
- “currencies” - One of the currencies is not a valid currency
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_get_conversion_dates",
"message": "....",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/data/conversion_dates HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth_token>
{
"currency_start": "EUR",
"currency_end": "USD"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"holidays": {
...
"2018-09-03": true,
...
"2018-11-12": true,
...
},
"first_conversion_date": "2018-03-13",
"default_conversion_date": "2018-03-15",
"last_conversion_date": "2019-03-12",
"next_available_conversion_date": "2018-03-14",
"next_over_next_available_conversion_date": "2018-03-15"
}Returns all valid currencies from one side (buy or sell). The list can be filtered by the counter currency
Request body
The currency on the counter side (if buy_sell: buy then the sell_currency, if buy_sell: sell then the buy_currency)
Responses
Body
The error object follows the same structure as shown in API Error Object. The possible Error top level “code”:
- “unable_to_get_currencies”
With possible “unable_to_get_currencies” “reasons”:
- “counter_currencies_not_available” - They given counter currency code do not have any currencypairs,
- “buy_sell_type” - Has to be either buy or sell
Examples
{
"code": "unable_to_get_currencies",
"message": "...",
"reasons": [
...
],
"errors": [
...
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/data/currencies HTTP/1.1
Content-Type: application/json
{
"counter_currency": "USD",
"buy_sell": "sell"
}
HTTP/1.1 200 OK
Content-Type: application/json
[
...
{
"curreny_code": "EUR",
"currency_name": "Euro"
},
...
{
"curreny_code": "GBP",
"currency_name": "British pound sterling"
},
....
{
"curreny_code": "USD",
"currency_name": "US Dollar"
}
...
]This endpoint returns details for where to send the funds to.
Request headers
Request body
Transfer (pay in) currency for the funding (client sell currency)
Responses
Body
The bank account holder name
The bank name
The currency
bic swift code
iban
account number
sort code
client specific reference code
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “unable_to_get_settlement_accounts”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "unable_to_get_settlement_accounts",
"message": "...",
"reasons": [
"..."
],
"errors": [
"..."
],
"timestamp": "2018-03-08T16:05:59+00:00"
}POST https://api.forexfix.com/api/data/settlement_accounts HTTP/1.1
Authorization: Bearer <auth_token>
Content-Type: application/json
{
"currency": "EUR"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"bank_account_holder_name": "Client Segregation Account - EUR",
"bank_name": "Barclays Bank plc",
"currency": "EUR",
"bic_swift": "BARCGB22",
"iban": "xxxx xxxx xxxx xxxx xxxx xx",
"account_number": "74741277",
"sort_code": "200605",
"reference":"180305-00009 - N61676694380"
}This endpoint returns the available countries the payment can be sent to.
Responses
Body
The error object follows the same structure as shown in API Error Object
The possible Error top level “code”:
- “internal_service_error”
The possible error “reasons”:
- “internal_service_error” - There is a Forexfix internal service error
Examples
{
"code": "internal_service_error",
"message": "...",
"reasons": [
"..."
],
"errors": [
"..."
],
"timestamp": "2018-03-08T16:05:59+00:00"
}GET https://api.forexfix.com/api/data/payment-countries HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
[
...
{
"country_code": "GB",
"country_name": "United Kingdom of Great Britain and Northern Ireland"
}
...
{
"country_code": "DE",
"country_name": "Germany"
}
...
{
"country_code": "US",
"country_name": "United States of America"
}
...
]Id of the beneficiary
Name of the Bank account holder
Currency of the bank account
Country where the bank account was created
Account number of the bank account
Sort code
bsb code
Swift code of the bank account
IBAN of the bank account
Company Name of the beneficiary. Filled if entity_type is company
First name of beneficiary. Filled if entity_type is individual
Last name of beneficiary. Filled if entity_type is individual
Address of the beneficiary
Post code of the beneficiary address
City of the beneficiary
State (US, Mexico), Province (Canada) of the beneficiary
Beneficiary creation date
Is beneficiary active
The user_id of the creator
The client’s given reference
Id of the payment
Id of the connected conversion
Id of the beneificary
Acmount of the payment
Currency of the payment
Payment status
Payment is ready to send
Payment settled
Payment finished
Payment failed
Payment reference, visible on bank statement of beneficiary
Reason of the payment (e.g. paying suppliers)
Local or Swift payment
Payment through local payment engines
Payment through SWIFT payment system
Date when the payment will be processed
Payment creation date
User Id of the payment creator
Beneficiary of the payment
Date when the payment was released
Id of the payment
Id of the connected conversion
Id of the beneificary
Acmount of the payment
Currency of the payment
Payment status
Payment is ready to send
Payment settled
Payment completed
Failed payment
Payment reference, visible on bank statement of beneficiary
Reason of the payment (e.g. paying suppliers)
Local or Swift payment
Payment through local payment engines
Payment through SWIFT payment system
Date when the payment will be processed
Payment creation date
User Id of the payment creator
The name of the bank account holder
The currency of the bank account
The country where the bank account was created
account number
[cond required] Depended on bank_account_currency and bank_account_country
The 9 digit aba routing number for USD accounts
[cond required] Depended on bank_account_currency and bank_account_country
International SWIFT Code
[cond required] Depended on bank_account_currency and bank_account_country
IBAN Code of bank account
[cond required] Depended on bank_account_currency and bank_account_country
Sort Code for UK Accounts
[cond required] Depended on bank_account_currency and bank_account_country
BSB Code for Australian Accounts
[cond required] Depended on bank_account_currency and bank_account_country
Institution number for CAD Accounts
[cond required] Depended on bank_account_currency and bank_account_country
Bank branch code
[cond required] Depended on bank_account_currency and bank_account_country
Clabe for MXN accounts
[cond required] Depended on bank_account_currency and bank_account_country
Cnaps code for CNY accounts
[cond required] Depended on bank_account_currency and bank_account_country
IFSC for INR Accounts (not yet active)
[cond required] Depended on bank_account_currency and bank_account_country
Entitiy type of the beneficiary
Company name of the beneficiary
[cond_required] Required if entity_type is company
First name of the beneficiary
[cond_required] Required if entity_type is individual
Last name of the beneficiary
[cond_required] Required if entity_type is individual
Beneficiaries country of residence
Address of the beneficiary
[cond required] Depended on bank_account_currency and bank_account_country
Post code of the beneficiary address
[cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
City of the beneficiary
[cond required] Depended on bank_account_currency and bank_account_country
State (US, Mexico), Province (Canada) of the beneficiary
[cond required] Depended on bank_account_currency, bank_account_country and beneficiary_country
Date of brith if entity_type is individual or company founding date if entity_type is company
Reference used for transfering the funds
The sell and buy currencypair in an standardized format
The status of the conversion
Primary amount has to be payed
Secondary amount has to be payed (only with forwards)
Payin amount fully received -> Conversion will be converted on conversion date
Conversion has converted, payment will be fulfilled on payment date
Buy currency of the order
Sell currency of the order
Fixed Side
Sell side is fixed
Buy side is fixed
Rate including all charges
Date when the conversion happens
Indicates if a secondary payin amount is required (only if a forward)
Currency in which the payin amount has to be transfered
Timestamp when the order was created
Timestamp when the order was last updated
User Id of the order creator
Order comment
Id of the conversion
Date until the primary amount has to arrive
Amount of the primary payin transfer
Date until the secondary amount has to arrive. (Only for forwards)
Amount of the secondary payin transfer. (only for forwards)
Rate without fees
Buy amount. Including all fees if fixed_side is sell
Sell amount. Including all fees if fixed_side is buy
Comission of the conversion
Array of payments with beneficiary details for order
Reference used for transfering the funds
The sell and buy currencypair in an standardized format
The status of the conversion
Primary amount has to be payed
Secondary amount has to be payed (only with forwards)
Payin amount fully received -> Conversion will be converted on conversion date
Conversion has converted, payment will be fulfilled on payment date
Buy currency of the order
Sell currency of the order
Fixed Side
Sell side is fixed
Buy side is fixed
Rate including all charges
Date when the conversion happens
Indicates if a secondary payin amount is required (only if a forward)
Currency in which the payin amount has to be transfered
Timestamp when the order was created
Timestamp when the order was last updated
User Id of the order creator
Order comment
Id of the conversion
Date until the primary amount has to arrive
Amount of the primary payin transfer
Date until the secondary amount has to arrive. (Only for forwards)
Amount of the secondary payin transfer. (only for forwards)
Rate without fees
Buy amount. Including all fees if fixed_side is sell
Sell amount. Including all fees if fixed_side is buy
Comission of the conversion