Introduction

The Kantox API is designed to help you automate your integration with the Kantox platform. Our language-agnostic implementation allows you to pick your preferred programming language. It is based on REST principles enabling clients to simply make Create, Read, Update and Delete calls against Kantox FX platform resources.

Our API lets you automatically execute several types of FX transactions (spot, forward, conditional orders), foreign and same currency payments (international and local payments, early draws from forward trades). Other use cases for the API are: Dynamic Hedging, executing multiple same and foreign currency payments at once (Payments Hub), fetching mid-market exchange rates (FX Rate Feeder) and managing beneficiaries of your payments.

We’re introducing the main resources and operations here. For the list of API methods, parameters and responses, you will need to sign up for a demo account and request access to our product team by emailing api-access@kantox.com.

If you have a use case that would require new APIs or want to report any issue please reach out to product@kantox.com.

 


Getting Started

Once you have signed up for a demo account and requested access by email, one of our specialists will provide you credentials for a test account and we’ll set you up right away. Our preprod environment will let you validate and test your API integration before moving it into production.

Please refer to Authentication in order to understand how to log in and request access tokens.

Environments

For testing purposes, we provide a preprod environment that is similar to production. Requests made in this environment will never hit the banking networks and nor incur any cost.

Also, please note that objects created here (e.g. Beneficiaries) won’t be migrated to your final production account once approved. You may also need to adapt your company reference used in URL.

Preprod URL (Integration Testing): https://kantox-preprod.com/api

Once the integration is done, our Tech team may contact you for running Acceptance Tests before granting access to production. New credentials and a different URL will be provided.

Production URL: https://www.kantox.com/api

 


Authentication

An authentication token is required in all API calls. You can obtain one by using your API user credentials in a login call, as shown below:

  1. A login request with proper email and password will return a valid access token.
  2. All subsequent calls to the platform must contain the X-ACCESS-TOKEN HTTP header with the token obtained in the login request.
  3. Additionally, a logoff call is expected in order to invalidate the access token (optional). Kantox will otherwise invalidate the token after 10 minutes.

Important: All API requests must be made over HTTPS.

 


Companies

Clients of Kantox using the API may manage integrations for one or multiple Companies. Indeed the same API Client might manage FX transactions and payments for several subsidiary companies (in the context of a group of company with centralized cash management for example), or manage the API integration on behalf of several end-clients.

As a result, all API calls (except login and logoff calls) must include the relevant company identifier in their URL, even if your integration is only involving one company.

For example, to get mid-market rates, the URL should look like this:
GET api/companies/S2P33AZQ0/rates/midmarket_spot

In this case, S2P33AZQ0 is either kantoxCompanyRef or yourCompanyRef (see below). You can query this information via API but also will be provided when setting up your preprod or prod account.

We support two different types of company identifiers:

  • kantoxCompanyRef: internal unique identifier generated by Kantox for all Companies (you can query this value)
  • yourCompanyRef: optional external reference that you may define when you create a company.

Please note that for partners integrating Kantox as a white label, it is possible to create companies. Newly created companies will need to go through a legal check before being approved as Kantox clients. This API call is enabled by Kantox on a case by case basis, so if you are interested, please send us an email at api-access@kantox.com.

 


Beneficiaries Management

Before creating and executing FX transactions and payments, you need to record the details of the beneficiaries you want to pay using Kantox. We differentiate between:

  • External beneficiaries: every other entity or individual that you intend to pay (including subsidiaries of the company using Kantox API).
  • Company bank accounts: bank accounts that are under the name of the company using Kantox API.

Managing external beneficiaries

External beneficiaries can have one or many bank accounts. For instance, a speakers manufacturer based in Sweden could have SEK and USD bank accounts.

Here’s the basic flow to automatically submit beneficiaries information via API:

  1. Each beneficiary company / individual needs to be registered. You can provide a beneficiaryRef to identify the beneficiary. Due to Compliance and Payments regulations, it’s important to send valid values for all mandatory fields (e.g. registered / legal name for the beneficiary as companyName, full address, etc.).
  2. Once the beneficiary is created, it’s possible to attach one or many bank accounts. You will need to include the same beneficiaryRef to link the new bank account with the existent beneficiaries.

In case you don’t need to support multiple bank accounts per beneficiary, it’s also possible to combine this information in a single call. You can do this by defining the right values for the bankAccountDetails parameter. In that case, the beneficiary and related bank accounts will be created.

Note that if your company only manages a few beneficiary accounts (e.g. company bank accounts) then those beneficiaries can be manually imported via user interface.

Managing company bank accounts

Managing company bank accounts follows a simpler process than managing an external beneficiary bank account. In order to create a company bank account, you just need to create a bank account without providing the BeneficiaryRef parameter. The bank account created will be considered by default as belonging to the company identified in the API request.

Bank Accounts Verification

Kantox will run several checks in background to ensure a given beneficiary and bank account is verified. Payments won’t be completed if the associated bank account is not verified.

Here’s a summary of possible status and workflow:

  • Unverified: default status when the bank account is created
  • Verified: bank account was successfully verified
  • Validate Error (Invalid): there was some error while trying to validate the bank account
  • Suspended: account is not longer available, clients or Kantox (e.g. due to Anti-Money-Laundering policies) can request cancellation at any time

Important: We recommend to verify the bank account status before using it in any type of Trade or Transaction. You can check this by calling the GET bank_accounts API a few seconds after registering any new bank account. We’ll provide details if any error is found while validating any bank account.

 


FX Transactions

Kantox lets you make different types of FX transactions (listed and defined in the next section) through the API. Every type of transaction has its specificities, but they all follow a common logic:

  1. Post: the API client creates an order including the details of the transaction
  2. Execution: the order is executed (at this point, the exchange rate is fixed – execution can be simultaneous with creation)
  3. Settlement: before the date chosen, you must transfer the funds to Kantox so we can make the conversion.
  4. Payment: once the conversion is made, we pay out to the beneficiary you have chosen for the transaction

This typically translates in the following workflow (transaction status):

  • Created: the order was successfully requested but it’s not yet executed
  • Awaiting Funds: the order was executed and settlement instructions were generated. Kantox is expecting funds (aka. Pay-In) before given settlement date & time or the Order may incur in rollover fees.
  • Funds Received: Kantox has received funds for the order and will proceed with settlement and final payment to selected beneficiary.
  • Settlement: FX exchange was successfully completed but final payment (aka. Payout) has not yet been issued. This is usually a short period until payment is authorized.
  • Completed: Order is cleared and funds were sent to selected beneficiary bank account.

Additionally, the following status are also possible in specific situations:

  • Cancelled: We only cancel orders upon written client request.
  • Rolled: Value date of the original order has been updated as per customer request (e.g. transform a 30-day order into 90-day forward).
  • Netted: Order has been netted against other orders in the platform (e.g. a forward contract netted against a reverse spot on value date)

Types of orders

Kantox supports many different FX and payment orders types:

  • Spot: this is an FX transaction that has a value date within the next 3 business days following execution
  • Forwards (flexible and non-flexible): a forward is an FX transaction that has a value date set more than 3 business days after execution. A flexible forward is a forward on which you can anticipate the settlement, making one or several early draws.
  • Early Draws: this lets you anticipate part of the settlement of a forward. The currency conversion will be made at the rate of the forward, and the amount exchanged will be subtracted from the amount to be settled at maturity.
  • Conditional Orders: the execution of a conditional order is tied to the market exchange rate reaching a limit that you have set. You also define beforehand what type of maturity (spot, forward, etc) you would like the order to have when it will be executed.

Spot & Forward Orders

It’s highly recommended to request a quote before trying to execute Spot or Forward orders. This way, users can be aware of the estimated counter value for the Order and will also mitigate potential problems when executing the orders (e.g. invalid value date, currency is non-quotable, etc).

The basic flow to execute an Order would be as follow:

  1. Request a quote by providing: market direction (buy or sell), currency (the currency you buy/sell) and counter currency, amount and preferred value date.
  2. If the “quote” succeeds, then you can execute the order confirming the same parameters and also include:
    • Beneficiary bank account reference: (i.e. where to send funds once converted)
    • Unique reference for the order: (optional), it may help with reporting, etc. Kantox will also generate a unique reference.
    • Comments: (optional) notes that you want to be included in the payment reference.
  3. If  the “create order” call succeeds, then there are two possible flows:
    • Option 1: Check if orderStatus is executed, this means the Order was successfully executed and settlement instructions were generated.
    • Option 2: Else, if orderStatus is created, this means the Order was successfully created but it couldn’t be instantly executed. Kantox will re-try the execution or notify Support team to close the Order manually (e.g. because the Order amount is higher than defined limit for the Company). No settlement instructions will be generated until it is executed.
  4. Once the order status is executed, it needs to be settled by your company. Settlement instructions can also be retrieved via API (see Settlement instructions).

A “rejectOnFail” param is also supported. If it’s set to “true” then Kantox won’t retry to execute the Order and an error will be returned if it cannot be executed instantly.

Requesting Early Draws

Executing a flexible forward follows the exact same workflow as the one described in the section above, this means, that’s recommended to perform a Quote request first and then execute the Order.

You can request early draws using the API:

  1. Request a draw by providing these parameters: reference of the parent order, amount to draw, currency to draw, value date and beneficiary to be paid.
  2. If orderStatus=created, this means the draw was successfully created. Our Support team will receive an alert to execute it manually (there is still a very small manual task to be processed on our side for draws).
  3. Once the draw status is executed, it needs to be settled by your company. Settlement instructions can also be retrieved via the API (see Settlement instructions section below).

It’s important to highlight that Early Draws can only be requested via API (will be executed soon after requested) and are not executed instantly.

Creating Conditional Orders

Requesting Conditional Orders follows a similar process as with regular Spot or Forward Orders:

  1. A few additional parameters are needed to post a Conditional Order:
    • Maturity: could be defined as Spot (two business days after execution), Forward (any number of days after execution) or a Fixed Date.
    • Expiration: date until the Order should be live in the market. If maturity is a fixed date, then max expiration date is two days before maturity (to ensure payment will be issued on selected value date).
    • Stop Loss and/or Take Profit limits: depending on the limits defined, the Order type would be a Take Profit, Stop Loss or One-Cancels-the-Other.
  2. Once it is requested, it is possible to verify the Order was accepted and introduced in market. You can check the order status using the GET conditional_orders call.

It is also possible to request the Order cancellation using the DELETE method.

Settlement instructions

You can get Settlement Instructions from the API, either by making a call for a specific order, call using some filters, or a general call to get all your pending transactions’ settlement instructions.

In the response, Kantox will specify:

  • Bank account details: BIC/SWIFT, IBAN, etc. where funds need to be transferred
  • Amount and currency to be sent: this is also known as pay-in information
  • Settlement Datetime: deadline to send funds to Kantox

The settlement instructions will also be sent by email to all approved Kantox users in your company.

 


Rates

Our Rates API lets you grab the mid-market exchange rates at the time of your request. This is useful if your company only needs information about the rates, but not to transact right away (for example to compute prices dynamically in foreign currency, for accounting purposes, etc).

Mid-market spot

Use GET /rates/midmarket_spot to obtain the last known mid-market rate for a given currencyPair.

Mid-market forwards

Use GET /rates/midmarket_forward to obtain the last known mid-market rate for a given curencyPair and valueDate.

 


Dynamic Hedging

Kantox Dynamic Hedging allows your company to keep its FX risk exposure in multiple currency pairs under full control.

All you need to is define a hedging strategy through a set of business rules and to provide us with regular exposure data from your system. The defined policy will be automatically executed, including the complete trading and international payments processes. The main outcomes of this solution are:

  • No more human monitoring is required.
  • FX risk is more completely and precisely monitored, from the moment you send us the exposure data (aka entries).
  • The number of actual FX hedges will be limited thanks to our approach: we accumulate entries and hedge them only if the conditions defined in your business rules are met. This means less administrative management for the finance team.
  • The finance team will be able to control hedges and their mark-to-market position to make Hedge Accounting easier.

Learn more about Dynamic Hedging and talk to our experts!


Payments Hub

The Kantox API lets you execute multiple payments (cross-currency or same currency) with a single request. This way, your company will only have to send the aggregate amount once to Kantox for settlement instead of processing the payments one by one.
This is particularly useful for companies looking to execute mass payments, as it will considerably simplify the payment process for the finance team.

Key concepts

  • Payment Order: these are the individual payments to be made to your beneficiary after settlement. The basic parameters to be provided for each payment order are: payIn currency (the currency that you will deliver to Kantox), a payOut currency (the one delivered to the beneficiary), an amount (in the payOut currency), beneficiary bank account associated (bank account reference of a previously registered beneficiary, see Beneficiaries Management section for more information).
  • Batch Order: Kantox will automatically group your payment orders with the same currency pair, market direction and value date under the same Batch Order. The reference of the associated Batch Order is passed to you every time a Payment Order is successfully posted. Batch Orders are the transaction to be requested once you are done posting your payment orders.
  • Settlement: A single settlement instruction will be generated for each Batch order, no matter how many payment orders are grouped within the Batch Order.

At any time, it’s possible to list all pending or completed payments (including filters by any parameter) for reporting and reconciliation purposes.

Learn more about Payments Hub and talk to our experts!

 


Handling Errors

Kantox uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error on Kantox servers.

We’ll provide an explanation and details for any error you may encounter while integrating the API.