Introduction

Base URL Sandbox

http://api-test.cleartreasury.co.uk/api

Base URL Live

http://api.cleartreasury.co.uk/api

Welcome to the Clear Treasury API.

With international payments being a daily necessity for many, we have developed our online payments platform to dramatically streamline the process.

Our aim is to make the Clear Treasury API as simple as possible for you to integrate into your process, product or software.

API access

Every call to the Clear Treasury API requires an authorization token that needs to be set in the header of every call.

Auth Token

Use your provided login credentials to access our back-office system and generate an authorization token.

The Token is valid for 6 months.

The resulting authorization token must then be sent in an Authorization header in every request.

Regenerating a token

Use your provided login credentials to access our back-office system and generate a new authorization token.

Authorization

curl -X GET http://api-test.cleartreasury.co.uk/api/quote \
     -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"

Once you have your authorization token, add it as a bearer token in an Authorization header to every request.

Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx

Clients

A client is a person or institution that has trades and payments associated to them.

Description

Before you're able to act on behalf of a client you will need to create one first.

Create a client

Create a new client in order to operate on their behalf.

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/clients \
     -H 'Authorization: Bearer <your auth token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "trader": "<your trader id>",
          "type": "CORPORATE",
          "name": "TEST Company Ltd",
          "address1": "TEST Company HQ",
          "postcode": "AA1 1AA",
          "city": "London",
          "country": "England",
          "company_number": "01234567",
          "company_sic": "64999",
          "web": "https://www.cleartreasury.co.uk/",
          "email": "test.company@example.com",
          "countries_of_interest_beneficiaries": [ "GB", "US" ],
          "countries_of_interest_remitters": [ "GB", "US" ],
          "currency_of_interest": [ "GBP", "USD" ],
          "reason": "Making an investment",
          "language": "<your provided language>",
          "contact_list": [
            {
              "first_name": "Test",
              "last_name": "Tester",
              "address1": "Tester House",
              "city": "London",
              "country": "England",
              "post_code": "BB2 2BB",
              "date_of_birth": "19700101",
              "email": "test.tester@example.com",
              "mobile_phone": "+447712345678",
              "telephone": "+441234567890"
            }
          ]
        }'

Example response:

[
  {
    "ClientName": "TEST Company name",
    "ClientRef": "C00000001",
    "ContactFirstName": "Test",
    "ContactLastName": "Tester",
    "Status": "New"
  }
]

Request

POST /clients

Name	Description	Required	Type	Additional information
trader	Your trader account ID	Yes	string	This will be provided to you at signup
type	The type of client	Yes	string	"CORPORATE" or "PRIVATE"
name	Client's name	No	string	Company name for CORPORATE client
address1	Address line 1	No	string	None
address2	Address line 2	No	string	None
address3	Address line 3	No	string	None
city	City	No	string	None
country	Country	No	string	None
postcode	Postcode	No	string	None
web	Website	No	string	None
email	Email	No	string	None
fax	Fax number	No	string	None
switchboard	Switchboard extension	No	string	None
ip	IP address	No	string	None
company_number	Company number	No	string	None
company_sic	Company SIC code	No	string	None
company_vat	Company VAT number	No	string	None
country_of_incorporation	Country of incorporation	No	string	None
legal_status	Legal status	No	string	None
trading_as_name	Trading as name	No	string	None
trading_address1	Trading address line 1	No	string	None
trading_address2	Trading address line 2	No	string	None
trading_address3	Trading address line 3	No	string	None
trading_city	Trading city	No	string	None
trading_country	Trading country	No	string	None
trading_postcode	Trading postcode	No	string	None
countries_of_interest_beneficiaries	The countries of the client's beneficiaries	No	Collection of string	None
countries_of_interest_remitters	The countries of the client's remitters	No	Collection of string	None
currency_of_interest	The countries the client wants to trade	No	Collection of string	None
expiry_date	Client expiry date	No	string	None
regulator_name	Name of the client's regulator	No	string	None
source	Source	No	string	None
reason	Reason for trading	No	string	None
comment	Free text comment	No	string	None
trader_commission	Trader's commission	No	string	None
cold_caller	Which cold caller made contact with the client	No	string	None
cold_caller_commission	Cold caller's commission	No	string	None
web_commission		No	string	None
activity		No	string	None
language	Your parent company's identifier within our system	No	string	This will be provided to you at signup
group_industry		No	string	None
sid		No	string	None
referer		No	string	None
affiliate_reference		No	string	None
non_uk_shareholder		No	string	None
kyc_ccy		No	string	None
kyc_max_volume		No	string	None
kyc_source_of_wealth		No	string	None
kyc_source		No	string	None
kyc_relationship_with_beneficiaries		No	string	None
kyc_nature		No	string	None
kyc_avg_volume		No	string	None
kyc_annual_volume		No	string	None
kyc_frequency		No	string	None
kyc_max_volume		No	string	None
kyc_ccy		No	string	None
kyc_source_of_wealth		No	string	None
kyc_source		No	string	None
kyc_relationship_with_beneficiaries		No	string	None
kyc_json		No	string	None
agree_marketing_conditions		No	integer	0 or 1
agree_marketing_conditions_affiliate		No	integer	0 or 1
unsubscribe_emails		No	string	None
contact_list		Yes	Collection of contact object	None

Contact Object

Name	Description	Required	Type	Additional information
title	Title	No	string	None.
first_name	First name	Yes	string	None.
middle_name	Middle name	Yes	string	None.
last_name	Last name	No	string	None.
date_of_birth	Date of birth	No	string	None.
nationality	Nationality	No	string	None.
job_title	Job title	No	string	None.
address1	Address line 1	No	string	None.
address2	Address line 2	No	string	None.
address3	Address line 3	No	string	None.
city	City	No	string	None.
country	Country	No	string	None.
post_code	Postcode	No	string	None.
email	Email address	No	string	None.
fax	Fax number	No	string	None.
mobile_phone	Mobile phone number	No	string	None.
telephone	Telephone number	No	string	None.
web	Website	No	string	None.

Response

ClientRef is needed for all future requests when operating as a trader on behalf of a client.

Status determines the client's ability to trade.

A client will automatically be marked as New at the point of creation in the system.
A client cannot trade until their status is Active. A client's status is changed from New to Active after successfully passing our compliance checks.

Name	Description	Type
ClientName	Company name of the client	string
ClientRef	Unique reference of the client. This is autogenerated initially but can be updated by you later	string
ContactFirstName	First name of the client's contact	string
ContactLastName	Last name of the client's contact	string
Status	Trading status of the client	string

List all clients

Retrieve a list of all the clients you have access to.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/clients \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "ClientName": "TEST Company Ltd",
    "ClientRef": "C00000002",
    "ContactFirstName": "Test",
    "ContactLastName": "Tester",
    "Status": "New"
  },
  {
    "ClientName": "Testing Company PLC",
    "ClientRef": "C00000001",
    "ContactFirstName": "Test",
    "ContactLastName": "Tester",
    "Status": "Active"
  }
]

Request

GET /clients

Response

Name	Description	Type
ClientName	Company name of the client	string
ClientRef	Unique reference of the client	string
ContactFirstName	First name of the client's contact	string
ContactLastName	Last name of the client's contact	string
Status	Trading status of the client	string

Get a client

Retrieve a single client by client reference.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/clients/{client_ref} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

{
  "ClientName": "TEST Company Ltd",
  "ClientRef": "C00000002",
  "ContactFirstName": "Test",
  "ContactLastName": "Tester",
  "Status": "New"
}

Request

GET /clients/{client_ref}

Name	Description	Required	Type
client_ref	Unique reference of the client	Yes	string

Response

Name	Description	Type
ClientName	Company name of the client	string
ClientRef	Unique reference of the client	string
ContactFirstName	First name of the client's contact	string
ContactLastName	Last name of the client's contact	string
Status	Trading status of the client	string

Quotes

There are four steps to executing a trade:

Step 1: Create a quote

Step 2: Book a trade

Step 3: Create a beneficiary

Step 4: Instruct a payment

Description

A quote can be used to create a trade. Quotes expire after 30 seconds. During that time you can refresh the price and the 30 second expiry time will be restarted, renewing its life for another 30 seconds.

Once a quote expires you'll need to place a new quote.

The rate returned is always in the sell-buy direction.

You need the returned quote ID and client_rate as inputs to create a trade in step 2.

Place a Quote

You need to have placed a quote before you can book a trade in step 2.

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/quotes \
     -H 'Authorization: Bearer <your auth token>' \
     -H 'Content-Type: application/json' \
     -d '{
            "currency_sell": "GBP",
            "currency_buy": "EUR",
            "sell_amount": 500.00,
            "value_date": "20200101",
            "client_ref": "<client reference>"
        }'

Example response:

{
  "ID": "0001",
  "sell_amount": 500.0,
  "buy_amount": 599.85,
  "quote_rate": 1.1997028,
  "value_date": "20200101",
  "currency_buy": "EUR",
  "currency_sell": "GBP",
  "fee_ccy": 0.0,
  "fee": 0.0
}

Request

POST /quotes

Name	Description	Required	Type	Aditional Info
currency_sell	The currency the end customer is wanting to sell	Yes	string	ISO 3 letter currency
currency_buy	The currency the end customer is wanting to sell	Yes	string	ISO 3 letter currency
sell_amount	Amount being sold	Yes	decimal	None
buy_amount	Amount being bought	Yes	decimal	None
value_date	Date the currency will be bought/sold	No	string	yyyyMMdd format
client_ref	Unique reference of the client	Yes	string	None

Response

The quote ID and quote_rate is needed for booking a trade in step 3.

The rate returned is always in the sell/buy direction.

Name	Description	Type
ID	Quote ID	string
sell_amount	Amount being sold	decimal
buy_amount	Amount being bought	decimal
quote_rate	Quote Rate. Always in sell/buy direction	decimal
currency_sell	Currency beign sold	string
currency_buy	Currency being bought	string
value_date	Date that the currency will be bought/sold	string
fee	Charge amount	decimal
fee_ccy	Charge Currency	decimal

Refreshed the price for a quote

You can request a new price for a previously placed quote.

Quotes expire after 30 seconds. During that time you can refresh the price of a quote to renew its life for another 30 seconds.

Once a quote expires you'll need to place a new quote.

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/quotes?quote_id={quote_id} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

{
  "ID": "0001",
  "sell_amount": 500.0,
  "buy_amount": 599.85,
  "quote_rate": 1.1997028,
  "value_date": "20200101",
  "currency_buy": "EUR",
  "currency_sell": "GBP",
  "fee_ccy": 0.0,
  "fee": 0.0
}

Request

POST /quotes?quote_id={quote_id}

Name	Description	Required	Type
quote_id	Quote ID	Yes	integer

Response

Name	Description	Type
ID	Quote ID	string
sell_amount	Sell Amount	decimal
buy_amount	Sell Amount	decimal
client_rate	Client Rate	decimal
currency_sell	Sell Currency	string
currency_buy	Buy Currency	string
value_date	yyyyMMdd Date	string
fee_ccy	Charge Currency	decimal
fee	Charge amount	decimal

Get a placed quote

Get the details of a previously placed quote

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/quotes/{quote_id} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

{
  "ID": "0001",
  "sell_amount": 500.0,
  "buy_amount": 599.85,
  "quote_rate": 1.1997028,
  "value_date": "20200101",
  "currency_buy": "EUR",
  "currency_sell": "GBP",
  "fee_ccy": 0.0,
  "fee": 0.0
}

Request

GET /quotes/{quote_id}

Name	Description	Required	Type
quote_id	Quote ID	Yes	integer

Response

Name	Description	Type
ID	Quote ID	string
sell_amount	Amount being sold	decimal
buy_amount	Amount being bought	decimal
quote_rate	Quote Rate. Always in sell/buy direction	decimal
currency_sell	Currency beign sold	string
currency_buy	Currency being bought	string
value_date	Date that the currency will be bought/sold	string
fee	Charge amount	decimal
fee_ccy	Charge Currency	decimal

Beneficiaries

There are four steps to executing a trade:

Step 1: Create a quote

Step 2: Book a trade

Step 3: Create a beneficiary

Step 4: Instruct a payment

Description

A beneficiary is a person or institution who is the ultimate recipient of your payment.

You need the returned beneficiary id as an input to instruct a payment in step 4.

Create a beneficiary

Create a new beneficiary in order to instruct a payment to them.

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/beneficiaries \
     -H 'Authorization: Bearer <your auth token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "account_name": "Bank account",
          "account_number": "01234567",
          "address": "Test bank house",
          "bank_name": "Test bank",
          "currency": "GBP",
          "sort_code": "001122",
          "swift": "AAAAUK12345XXX",
          "country_code": "GB",
          "email": "test.beneficiary@example.com",
          "beneficiary_address": "Test beneficiary house, Beneton, England",
          "client_ref": "<client reference>"
        }'

Example response:

{
  "message": "Beneficiary added to client's list ",
  "id": 24538
}

Request

POST /beneficiaries

Name	Description	Required	Type	Additional information
client_ref	Client reference to associate the beneficiary with	Yes	string
intermediary	SWIFT code of the intermediary bank account	No	string	Max length 50
account_name	Bank account name	Yes	string
account_number	Bank account number	Yes	string
sort_code	Bank account sort code	No	string	6 digits. No spaces or special characters
bankname	Bank name	No	string
address	Bank Address	No	string
swift	Bank SWIFT code	No	string
cnaps	CNAPS account number	No	string
country_code	Country code	Yes	string	ISO 2 letter country code
currency	Currency	No	string	ISO 3 letter currency code
email	Email address	No	string
ben_address	Contact address	No	string
notes	Noteworthy information	No	string

Response

The id is needed when instructing a payment.

Name	Description	Type
id	Beneficiary ID	integer
message	Information about the beneficiary creation	string

List all beneficiaries

Get a list of beneficiaries you have access to.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/beneficiaries?client_ref={client_ref} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "intermediary": "",
    "account_name": "Test bank account",
    "account_number": "94907814",
    "address": "1 Test Bank Avenue, UK, AA1 1AA",
    "bankname": "Test bank",
    "currency": "GBP",
    "notes": "",
    "sort_code": "001122",
    "swift": "AAAAUK12345XXX",
    "country_code": "GB",
    "email": "test@example.com",
    "ben_address": "1 test road, UK, BB2 2BB",
    "id": "1",
    "client_ref": "<client reference>"
  }
]

Request

GET /beneficiaries?client_ref={client_ref}

Name	Description	Required	Type
beneficiary_id	Unique ID of the beneficiary	Yes	string

Response

Beneficiary id is needed for booking a trade.

Name	Description	Type	Additional information
intermediary	SWIFT code of the intermediary bank account	string	Max length 50
account_name	Bank account name	string
account_number	Bank account number	string
sort_code	Bank account sort code	string	6 digits. No spaces or special characters
bankname	Bank name	string
address	Bank Address	string
swift	Bank SWIFT code	string
cnaps	CNAPS account number	string
country_code	Country code	string	ISO 2 letter country code
currency	Currency	string	ISO 3 letter currency code
email	Email address	string
ben_address	Contact address	string
notes	Noteworthy information	string
id	Unique ID of the beneficiary	string
client_ref	Client reference to associate the beneficiary with	string

Get a beneficiary

Retrieve a single beneficiary by beneficiary ID.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/beneficiaries/{beneficiary_id} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

{
  "client_ref": "C00000001",
  "id": "1",
  "intermediary": "",
  "account_name": "Test bank account",
  "account_number": "01234567",
  "address": "",
  "bankname": "",
  "currency": "GBP",
  "notes": "Added from API 01/01/2020 00:00:00",
  "sort_code": "001122",
  "swift": "AAAAUK12345XXX",
  "country_code": "GB",
  "email": "test.beneficiary@example.com",
  "ben_address": "",
  "cnaps": ""
}

Request

GET /beneficiaries/{beneficiary_id}

Name	Description	Required	Type
beneficiary_id	Unique ID of the beneficiary	Yes	string

Response

Name	Description	Type	Additional information
intermediary	SWIFT code of the intermediary bank account	string	Max length 50
account_name	Bank account name	string
account_number	Bank account number	string
sort_code	Bank account sort code	string	6 digits. No spaces or special characters
bankname	Bank name	string
address	Bank Address	string
swift	Bank SWIFT code	string
cnaps	CNAPS account number	string
country_code	Country code	string	ISO 2 letter country code
currency	Currency	string	ISO 3 letter currency code
email	Email address	string
ben_address	Contact address	string
notes	Noteworthy information	string
id	Unique ID of the beneficiary	string
client_ref	Client reference to associate the beneficiary with	string

Book a Trade

There are four steps to executing a trade:

Step 1: Create a quote

Step 2: Book a trade

Step 3: Create a beneficiary

Step 4: Instruct a payment

Description

Trade is a payment order to a beneficiary account based on a quote.

Once created, a trade needs to be funded by the value_date.

Book trade

Book a trade by verifying acceptance of a quote.

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/trades \
     -H 'Authorization: Bearer <your auth token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "quote_id": <quote id>,
          "client_ref": "<client reference>",
          "client_rate": <client rate>,
          "quote_rate": <quoted rate>
        }'

Example response:

{
  "ID": 1,
  "trade_ref": "0000001",
  "trade_date": "20200101",
  "value_date": "20200101",
  "currency_bought": "EUR",
  "currency_sold": "GBP",
  "rate": 1.1997028,
  "bought_amount": 599.85,
  "sold_amount": 500.0,
  "payment_fee": 0,
  "trade_type": "Spot",
  "our_account_name": "string",
  "our_bank_name": "string",
  "our_iban": "string",
  "our_sort_code": "string",
  "our_swift_code": "string"
}

Request

POST /trades

Name	Description	Type	Additional information
quote_id	ID of the quote	integer	None
source_of_funds	Where the funds are coming from	string	None
reason_for_trading	Reson for the trade	string	None
client_ref	Unique reference of the client being traded on behalf of	string	None
client_rate	The rate given to the client	decimal	None
quote_rate	The rate of the original quote	decimal	None

Response

The trade_ref is needed for instructing a payment in step 4.

Name	Description	Type	Additional information
id	Unique ID	integer	None
trade_ref	Unique reference	integer	None
trade_date	Date the trade was made	string	None
value_date	Date the currency will be bought or sold	string	yyyyMMDD format
currency_bought	Currency being bought	string	ISO 3 letter currency code
currency_sold	Currency being sold	string	ISO 3 letter currency code
bought_amount	Amount being bought	decimal	None
sold_amount	Amount being sold	decimal	None
rate	Rate of the trade	decimal	None
payment_fee	Payment fee	decimal	None
trade_type	Type of trade	string	"Spot" or "Forward"
our_account_name	Our bank account name	string	None
our_bank_name	Our bank name	string	None
our_iban	Our IBAN	string	None
our_sort_code	Our sort code	string	None
our_swift_code	Our SWIFT code	string	None
message	Information about the trade	string	None

Payment Instructions

There are four steps to executing a trade:

Step 1: Create a quote

Step 2: Book a trade

Step 3: Create a beneficiary

Step 4: Instruct a payment

Description

This API call is the final step for executing trades.

Instruct a payment

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/payments \
     -H 'Authorization: Bearer <your auth token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "beneficiary_id": "<beneficiary id>",
          "trade_ref": "<trade id>",
          "currency": "GBP",
          "amount": "500",
          "purpose": "Making an investment",
          "payment_reference": ""
        }'

Example response:

{
  "PaymentGuid": "<GUID>"
}

Request

POST /payments?client_ref={client_ref}

Trade reference: If this payment is not linked to a trade leave it blank, or set it to "auto" to attempt to automatically retrieve an available trade.

Name	Description	Required	Type	Additional information
client_ref	Client reference you're instructing the payment on behalf of	Yes	string	client_ref
beneficiary_id	ID of the beneficiary	Yes	string	id
trade_ref	Reference of the trade used to instruct this payment	Yes	string	trade_id, "auto", or ""
currency	Currency of the payment	Yes	string	ISO 3 letter currency code
amount	Amount to be instructed	Yes	string
purpose	Reason for the payment	No	string
payment_reference	Reference to attach to the payment for your records	No	string

Response

Name	Description	Type
PaymentGuid	The unique ID of the payment	string

Get a payment

Get payment instruction by ID

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/payments/{id}?client_ref={{client_ref}} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

{
  "beneficiary_id": "2",
  "currency": "GBP",
  "purpose": "Making an investment",
  "fee": "SHA",
  "amount": "200.00",
  "trade_ref": "<trade reference>",
  "payment_guid": "<your GUID>",
  "client_ref": "<client reference>",
  "status": "Pending"
}

Request

GET /payments/{payment_guid}

Name	Description	Required	Type
payment_guid	Unique ID of the payment	yes	string

Response

Name	Description	Type
beneficiary_id	Beneficiary ID	string
currency	Currency	string
purpose	Purpose	string
fee	Fee	string
amount	Amount	string
trade_ref	Trade reference	string
payment_guid	Payment GUID	string
client_ref	Client reference	string
status	Payment status	string

Statements

Retrieve a Statement

Retrieve a statement for a given currency, optionally filtered by inclusive from and to dates.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/statement?ccy={ccy}&fromDate={fromDate}&toDate={toDate} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "sDate": "2020-01-01T00:00:00",
    "Ref": "AA00000000",
    "Description": "Currency Bought (GBP) ",
    "Debit": 0.0,
    "Credit": 1000.0,
    "Balance": 1000.0
  }
]

Request

GET /statement?ccy={ccy}&fromDate={fromDate}&toDate={toDate}client_ref={client_ref}

Name	Description	Required	Type
ccy	The currency of the statements to filter by	Yes	string
fromDate	Inclusive from date. In yyyyMMdd format	No	string
toDate	Inclusive to date. In yyyyMMdd format	No	string
client_ref	Client reference when making calls as a trader on behalf of a client	No	string

Response

Name	Description	Type
sDate	The date of the statement	date
Ref	The reference of the statement	string
Description	Whether the currency is being bought or sold and which currency it is	string
Debit	The amount debited	decimal
Credit	The amount credited	decimal
Balance	The balance of the statement	decimal

Trade History

List all trades by client

Retrieve a list of all trades made by a client.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/trades?client_ref={client_ref} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "id": 000001,
    "trade_date": "20200130",
    "value_date": "20200130",
    "currency_bought": "EUR",
    "currency_sold": "GBP",
    "client_rate": 1.2994149,
    "bank_rate": 0.0,
    "bought_amount": 416.87,
    "sold_amount": 500.0,
    "payment_fee": 0.0,
    "trade_ref": "A00000000",
    "trade_type": "Spot Trade",
    "status": "FILLED",
    "beneficiary": null,
    "client_ref": "C00000001",
    "instructed_amount": 0.0,
    "received_amount": 0.0,
    "paid_amount": 0.0
  }
]

Request

GET /trades?client_ref={client_ref}

Name	Description	Required	Type
client_ref	Unique reference of client	Yes	string

Response

Name	Description	Type
id	Trade ID	integer
trade_date	Date the trade was booked	string
value_date	Date the currency will be bought/sold	string
currency_bought	Currency bought	string
currency_sold	Currency sold	string
client_rate	Rate agreed with the client	decimal
bank_rate	Rate given by the bank	decimal
bought_amount	Amount bought	decimal
sold_amount	Amount sold	decimal
payment_fee	Payment fee	decimal
trade_ref	Reference of the trade	string
trade_type	Type of trade	string
status	Trade status	string
beneficiary	Beneficiary ID	string
client_ref	Client reference	string
instructed_amount	Amount instructed	decimal
received_amount	Amount received	decimal
paid_amount	Amount paid	decimal

Retrieve a Trade list between two dates

Retrieve a list of trades between inclusive from and to dates.

Example request:

curl -X POST http://api-test.cleartreasury.co.uk/api/trades?from_date={from_date}&to_date={to_date} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "id": 000001,
    "trade_date": "20200130",
    "value_date": "20200130",
    "currency_bought": "EUR",
    "currency_sold": "GBP",
    "client_rate": 1.2994149,
    "bank_rate": 0.0,
    "bought_amount": 416.87,
    "sold_amount": 500.0,
    "payment_fee": 0.0,
    "trade_ref": "A00000000",
    "trade_type": "Spot Trade",
    "status": "FILLED",
    "beneficiary": null,
    "client_ref": "C00000001",
    "instructed_amount": 0.0,
    "received_amount": 0.0,
    "paid_amount": 0.0
  }
]

Request

GET /trades?from_date={from_date}&to_date={to_date}

Name	Description	Required	Type
from_date	From date	Yes	string
to_date	To date	Yes	string

Response

Name	Description	Type
id	Trade ID	integer
trade_date	Date the trade was booked	string
value_date	Date the currency will be bought/sold	string
currency_bought	Currency bought	string
currency_sold	Currency sold	string
client_rate	Rate agreed with the client	decimal
bank_rate	Rate given by the bank	decimal
bought_amount	Amount bought	decimal
sold_amount	Amount sold	decimal
payment_fee	Payment fee	decimal
trade_ref	Reference of the trade	string
trade_type	Type of trade	string
status	Trade status	string
beneficiary	Beneficiary ID	string
client_ref	Client reference	string
instructed_amount	Amount instructed	decimal
received_amount	Amount received	decimal
paid_amount	Amount paid	decimal

Get a trade

Retrieve a single trade.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/trades/{trade_ref} \
     -H 'Authorization: Bearer <your auth token>'

Example response:

{
  "id": 000001,
  "trade_date": "20200130",
  "value_date": "20200130",
  "currency_bought": "EUR",
  "currency_sold": "GBP",
  "client_rate": 1.2994149,
  "bank_rate": 0.0,
  "bought_amount": 416.87,
  "sold_amount": 500.0,
  "payment_fee": 0.0,
  "trade_ref": "A00000000",
  "trade_type": "Spot Trade",
  "status": "FILLED",
  "beneficiary": null,
  "client_ref": "C00000001",
  "instructed_amount": 0.0,
  "received_amount": 0.0,
  "paid_amount": 0.0
}

Request

GET /trades/{trade_ref}

Name	Description	Required	Type
trade_ref	Unique reference of the trade	Yes	string

Response

Name	Description	Type
id	Trade ID	integer
trade_date	Date the trade was booked	string
value_date	Date the currency will be bought/sold	string
currency_bought	Currency bought	string
currency_sold	Currency sold	string
client_rate	Rate agreed with the client	decimal
bank_rate	Rate given by the bank	decimal
bought_amount	Amount bought	decimal
sold_amount	Amount sold	decimal
payment_fee	Payment fee	decimal
trade_ref	Unique reference of the trade	string
trade_type	Type of trade	string
status	Trade status	string
beneficiary	Beneficiary ID	string
client_ref	Client reference	string
instructed_amount	Amount instructed	decimal
received_amount	Amount received	decimal
paid_amount	Amount paid	decimal

-->

Countries and Currencies

There are certain countries and currencies we don't currently work with.

Description

These are informational read-only endpoints for listing the countries and currencies we accept.

List all countries

List of allowed countries we accept for clients or beneficiaries.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/countries \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "CountryName": "Afghanistan",
    "ISO2": "AF",
    "ISO3": "AFG",
    "RiskScore": 0.0
  },
  {
    "CountryName": "Albania",
    "ISO2": "AL",
    "ISO3": "ALB",
    "RiskScore": 0.0
  },
  ...{
    "CountryName": "Zambia",
    "ISO2": "ZM",
    "ISO3": "ZMB",
    "RiskScore": 0.0
  },
  {
    "CountryName": "Zimbabwe",
    "ISO2": "ZW",
    "ISO3": "ZWE",
    "RiskScore": 0.0
  }
]

Request

GET /countries

Response

Name	Description	Type
CountryName	Full name of the country	string
ISO2	2 letter ISO country code	string
ISO3	3 letter ISO country code	string
RiskScore	Compliance risk score for this country	decimal

List all currencies

List of allowed currencies we accept for trades and payments.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/currencies \
     -H 'Authorization: Bearer <your auth token>'

Example response:

[
  {
    "CurrencyCode": "GBP",
    "CurrencyName": "Sterling Pounds",
    "CurrencyFractionalName": "Penny",
    "NumberOfDayToDeliver": "0",
    "CutOffTime": "170000"
  },
  {
    "CurrencyCode": "EUR",
    "CurrencyName": "Euro",
    "CurrencyFractionalName": "cent",
    "NumberOfDayToDeliver": "0",
    "CutOffTime": "150000"
  },
  ...{
    "CurrencyCode": "OMR",
    "CurrencyName": "Omani Rial",
    "CurrencyFractionalName": "OMR",
    "NumberOfDayToDeliver": "1",
    "CutOffTime": "143000"
  },
  {
    "CurrencyCode": "RUB",
    "CurrencyName": "Russian Ruble",
    "CurrencyFractionalName": "kopeyka",
    "NumberOfDayToDeliver": "0",
    "CutOffTime": "000000"
  }
]

Request

GET /currencies

Response

Name	Description	Type
CurrencyCode	3 letter ISO country code	string
CurrencyName	Full name of the currency	string
CurrencyFractionalName	Name of the fractional currency	string
NumberOfDayToDeliver	Number of days the currency will take to be delivered	string
CutOffTime	Time by which a payment needs to be successfully initiated for same-day execution	string

Payment methods

Different countries have different details required for making payments to them.

Description

This is an informational read-only endpoint for listing the payment methods for the countries and currencies we accept.

Get payment methods for a country

Retrieve the payment methods of a country.

Example request:

curl -X GET http://api-test.cleartreasury.co.uk/api/paymentmethod \
     -H 'Authorization: Bearer <your auth token>'
     -d '{
          "CountryCode": "GB",
          "CCY": "GBP"
        }'

Example response:

[
  {
    "CountryName": "United Kingdom",
    "CCY": "GBP",
    "RequiredField": "(Account Number, SortCode, Beneficiary Address) OR (IBAN, SWIFT)"
  }
]

Request

GET /paymentmethod

Name	Description	Type
CountryName	The full name of the country	string
CCY	The currency	string
RequiredField	Required fields when instructing payments of the requested currency to the country	string

Response

Name	Description	Type
CountryName	Full name of the country	string
ISO2	2 letter ISO country code	string
ISO3	3 letter ISO country code	string
RiskScore	Compliance risk score for this country	decimal

Errors

We use common HTTP status codes included in the response header to indicate success or failure.

We follow RFC 7807 - Problem Details for HTTP APIs for formatting our response objects.

HTTP Status Codes

Error Code	Meaning
200	OK. Successful request
201	OK. Resource created.
400	Bad Request. The request could not be understood by the server due to malformed syntax.
401	Unauthorized. Your API key is invalid or has expired.
403	Forbidden. You do not have permissions to access the resource.
404	Not Found. The specified resource could not be found.
405	Method Not Allowed. You tried to access a resource with an invalid method.
406	Not Acceptable. You requested a format that isn't JSON.
410	Gone. The value requested has been removed from our servers or has expired.
418	I'm a teapot
429	Too Many Requests. You're requesting too many values! Slow down!
500	Internal Server Error. We had a problem with our server. Try again later.
503	Service Unavailable. We're temporarily offline for maintenance. Please try again later.

Validation Errors

Example Validation Error:

{
  "Type": "https://api-docs.cleartreasury.co.uk/#errors",
  "Title": "Problem creating resource",
  "Status": 400,
  "Detail": "There is a problem creating the resource",
  "Instance": "/error/00000",
  "invalid_params": [
    {
      "name": "param",
      "reason": "Param needs to be supplied"
    }
  ]
}

Data validation or violation of business rules related errors. Response could contain multiple errors.

Authentication Errors

Example Authentication Error:

{
  "Type": "https://api-docs.cleartreasury.co.uk/#errors",
  "Title": "Unauthorized",
  "Status": 401,
  "Detail": "You must be authorized to access this resource"
}

Your authorization token is either not valid or has expired.

Get in touch with us to to request a new token.

System Errors

Example System Error:

{
  "Type": "https://api-docs.cleartreasury.co.uk/#errors",
  "Title": "Internal Server Error",
  "Status": 500,
  "Detail": "No message available",
  "Instance": "/error/00000"
}

Something went wrong in our side.

Please contact support quoting the Instance URI.