Why use the API?

# Scroll down for code samples, example requests and responses. Select a  -->
       # language for code samples from the tabs above or the mobile navigation  
 # menu. 

 

Welcome to the Torfx API documentation. Torfx Ltd is a UK-based international payment provider.

This API makes it easy for you to use standard REST web technologies to make FX Conversions. It exposes Resources and Operations that you can use to make currency conversions.

There are a few code examples (visible in the column to the right) which you can use to help you get started.

API Versioning

The current version of the API is v 1.0.

The API is constantly being updated to add features, make improvements, and fix bugs. Backwards incompatible changes will result in a version number increase. Examples of changes which may not result in a version increment are:

• Adding new resources to the API

• Adding new attributes to the response of an existing endpoint

• Changing the order of attributes of responses (JSON by definition is an object of unordered key/value pairs).

Getting Started

Before you start using the API, please take a moment to familiarise yourself with the following sections.

All Torfx's API resources follow modern RESTful standards which will speed up the learning curve for anyone familiar with these types of APIs.

The Torfx API provides a lot of functionality. You will probably need to call a sequence of Resources to accomplish a task. For instance, a typical task is "making a foreign exchange transaction" with the following steps:

This process consists of a sequence of requests to the API, which include:

1. Request an Access Token to interact with the API. All Resources are restricted to authenticated users so you will first need to get this token.
2. Request a fixed price Exchange Rate Quote
3. Accept the quotation and execute an FX Conversion order
4. Lookup the Recipient details
5. Make the Payment to the Recipient

More details can be found in the following sections:

Section	Purpose
Authenticate	First you need to Authenticate using your client credentials and get an Access Token. This token will authorise you to call the other Resources.
Customers	Lets you provide your customers' data.
Contacts	Allows you to create, update and delete contact details for Contacts.
Recipients	Enables you to manage your Recipient Account details. A Recipient is a person or institution who is the ultimate beneficiary of your payment.
Rates	Get up-to-the-minute foreign exchange (FX) market rates. For example, an exchange rate of 1.14 EUR to USD means that 1 Euro can be brought for 1.14 United States Dollar.
Quotes	Request fixed price quotations for a specified value of one currency.
Conversions	Enables you to trade one currency for another.
Balances	Lets you view Wallet balances.
Payments	Initiate Payments and Review their details. A payment is a transfer of money from your account to a Recipient. To pay a Recipient in a particular currency, you must hold funds in that currency in your wallet. Otherwise, you should use Conversions to exchange one currency for another before making a payment.
Statements	Lets you view your account statements.
References	Provides Reference Data which are sets of permissible values to be used by when making certain requests. For example, a list of the currencies you can buy and sell, or a list of supported transaction purposes.
Webhooks	Callbacks which you can use to get updates on your Requests.

The next sections describe the fundamental points you should understand in order to make successful requests.

Authentication

Authentication is the activity of proving your identity to the service. All API calls are restricted to authenticated users. To get a successful response, you have to provide an API Access Token in the header of the request.

To get an Access Token and use it in a request to a protected Resource:

  # Example of a Request: 
   curl 'https://api.currenciesdirect.com/auth/oauth/v2/token' -H 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials&client_id=l7323441a8e72a4dd48a70b0e7d7b42437&client_secret=aeade0da50175619b6f269928a088abc&scope=external' 

   # Example of a response body: 
   { 
     "access_token": "dadadb2c-1ae2-48a2-a5dc-506e0432067b", 
     "token_type": "Bearer", 
     "expires_in": 300, 
     "scope": "external" 
   } 

   # Format of the Authorization header: 
   { "Authorization: Bearer dadadb2c-1ae2-48a2-a5dc-506e0432067b" } 

   # The resulting request will look similar to this: 
   curl -X POST https://api.currenciesdirect.com/v1/customers -H 'Content-Type: application/json' -H 'Authorization: Bearer dadadb2c-1ae2-48a2-a5dc-506e0432067b' 
 

1. Send an email to API Support requesting credentials to access to our API. Please specify the resources you require access to, the purpose of the access and the planned frequency of the requests you intend to make. When you are approved as a user, you will receive credentials in the form of a client_id and client_secret. Treat these with care as they are like your username and password for the API. They protect your data against requests from malicious users.
2. Make a HTTPS request to the Authenticate Resource including the credentials in the request body. See Get an Access Token for a full description of the parameters in the request body and header.
3. If the details are correct the server will respond with an access_token in the response body. The access_token is in GUID format.
4. Make a request to a Torfx Resource adding the access_token to the Authorization Header. The token should be prefixed with the word "Authorization" and the scheme "Bearer". Refer to RFC6750 for more information on Bearer Token Authorization.

Permissions and Scopes

Permissions restrict which areas of your account your API key will be able to access.

When you register for API access, Torfx assign a Scope to your account based upon your requirements. This Scope may only allow access to some of the API Resources or may only allow certain operations (for example read-only access to Contacts information). If you make a request to a resource or perform an operation which you are not permitted to access, the server will respond with an error and a HTTP response code of 403.

Requests

All requests should be made over HTTPS using the method (GET, POST, PUT or DELETE) and parameters defined by the endpoint. HTTP connections are not accepted as they are not confidential. You should also ensure that you are connected to the API using a valid Server SSL Certificate.

Request Headers

You should provide the following two HTTP header fields in each request:

Field	Description
Content-Type	The API consumes and produces JSON. This means that you should set the Content-Type header to application/json to ensure that your requests are properly accepted and processed by the API. The one exception to this rule is when making an Authenticate Request to the OAuth2 Authentication Server, when the Content-Type header should be application/x-www-form-urlencoded.
Authorization	Torfx API Resources are protected using an Access Token. This Access Token is a GUID formatted string. Refer to Authentication for details on obtaining this token. The token should be prefixed with the word "Authorization" and the scheme "Bearer", as seen in this example. { "Authorization: Bearer dadadb2c-1ae2-48a2-a5dc-506e0432067b" }

Responses

Torfx APIs responses will be in JSON format.

HTTP Status Codes

HTTP Status Codes are included in HTTP responses to indicate the status of the request.

The following table shows the codes we used in this API:

Status	Meaning	Description	Schema
200	OK	OK. Everything worked as expected.	Specialised to each Request
201	Created	Created. We will return a 201 after a successful POST where a resource was created.	Specialised to each Request
204	No Content	Indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.	None
400	Bad Request	Malformed request. You will receive this error if the request query parameters are not found or the request body does not validate with the schema. The error code will help you determine the cause of the issue. See (Error Codes)[#error-codes].	generalError
401	Unauthorized	Unauthorized. You have not included a valid Access token, it has expired, or you entered incorrect credentials.	generalError
404	Not Found	Not Found. Resource was not found.	generalError
422	Unprocessable Entity	Unprocessable entity. This can be caused by a number of validation issues. Such as trying to enter a duplicate record, or a country code which is not supported.	generalError
429	Too Many Requests	Exceeded the rate limit for requests.	generalError
500	Internal Server Error	Something has gone wrong on the website's server, but the server could not be more specific on what the exact problem is.	generalError
503	Service Unavailable	The backend server is not available or is under maintenance.	generalError

Rate Limiting

Each user (as identified by their Access Token) can make a limited number of requests per second. If you are making more requests than this limit allows, you will start to receive responses with 429 HTTP Status Codes, and should reduce the rate at which you are making API Requests.

Data Formats

Time Zones

The Time Zone of the API is UTC.

Date and Timestamp

To avoid confusion, dates and timestamps are in yyyy-mm-dd format in accordance with the ISO8601 standard. For example:

• Date: 2019-01-15
• Timestamp: 2019-01-15T16:32:05Z

Currency Codes

Currency Codes are in ISO4217 three letter format. For example, "GBP" for the UK Pound.

Country Code

Country Codes are in ISO3166-1 alpha-3 letter format. For example, "GBR" for the UK.

Pagination

Some API Operations can return large arrays of results (for example, getting a complete list of customers which could be 1000+ long). To prevent these large sets of data causing performance issues, such as HTTP timeouts, they are sorted in chronological order and split into smaller portions. When this happens, the response will include a JSON pagination object with parameters to allow you to page through the results. These parameters are:

Parameter	Function
next_page	Link to the next page of results.
previous_page	Link to the previous page of results.
total_pages	Total count of the number of pages.
total_records	Total count of the number of records in the entire set of data.

For example:

{ "meta_data": { "next_page": "customers/0101000000191708/recipients?page=5&limit=50", "total_pages": "6", "total_records": "267" } } As can be seen in the above example, the dividing of information into pages is controlled via limit and page query parameters:

Parameter	Function
page	Page number you wish to retrieve.
limit	Maximum number of records in a page.

Errors

Errors sent from the API will be accompanied by a JSON body with the following keys:

Key	Value
description	Human readable message which corresponds to the client error.
code	Underscored delimited string.

Example Error Response:

Status-Code: 400 Bad Request.

{ "description": "Invalid user", "code": "1001" }

You can find more information on specific errors in the Error Codes.

Base URLs

There are two services available, with the following base URLs:

• https://sandbox.currenciesdirect.com

• https://api.currenciesdirect.com

If you have a question about the API, please join us on slack channel by clicking here.

For terms of service see Terms of service.

APIs

This section provides a reference guide for all the Resources available in this API. Resources are webservices that are accessible at a URL using HTTP requests. When called they will return a JSON data object that represents some Business Entity (such as a GET HTTP request to the Contact Resource returns a Contact data object). Each Resource will allow at least one Operation on its data object. We support four HTTP methods: Post, Get, Put and Delete; for the Operations Create, Read, Update and Delete respectively.

Authenticate

Request an Access Token to Authenticate.

Customers

The Customer resource allows you to create, update and delete all your customers' data.

Register a Customer

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/customers \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/customers', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/customers

Add a new Customer record. The process for adding a new Customer record is asynchronous. So, it returns a unique identifier which you can use to get the finalised Customer record with a GET call to the Customers resource. You can also subscribe to Webhooks for updates on the Customer's status

Body parameter

{ 
   "customer_type": "Personal", 
   "company": { 
     "name": "Currencies Direct Ltd.", 
     "type": "Limited", 
     "vat_number": "7878768678", 
     "registration_number": "7878768678", 
     "country_of_incorporation": "IND", 
     "address": { 
       "unit_number": "Floor 45", 
       "street_number": "1", 
       "street": "Canada Square, Canary Wharf", 
       "street_type": "Square", 
       "post_code": "E14 5AA", 
       "city": "London", 
       "civic_number": "12345", 
       "state": "England", 
       "country": "GBR" 
     } 
   }, 
   "contacts": [ 
     { 
       "first_name": "Carlos", 
       "middle_name": "", 
       "last_name": "Lopez", 
       "date_of_birth": "1980-02-14", 
       "occupation": "Software Engineer", 
       "nationality": "United States of America", 
       "email": "[email protected]", 
       "phone_number": "(020)123456789", 
       "mobile_number": "+44-987654321", 
       "primary_contact": true, 
       "authorize_to_trade": true, 
       "address": { 
         "unit_number": "", 
         "street_number": "468", 
         "street": "Bissonnet Plaza, El Campo", 
         "street_type": "Plaza", 
         "post_code": 77023, 
         "city": "Houston", 
         "civic_number": "", 
         "state": "Texas", 
         "country": "USA" 
       }, 
       "proof_of_identity": { 
         "passport": { 
           "number": "12345", 
           "name_at_citizenship": "Lopez", 
           "family_name_at_birth": "Lopez", 
           "place_of_birth": "Houston, USA", 
           "expiry_date": "2025-09-30", 
           "issuing_country": "USA" 
         } 
       } 
     } 
   ], 
   "additional_details": { 
     "client_reference_id": "987564823645", 
     "campaign": "987564823645", 
     "campaign_reference": "987564823645", 
     "interested_currencies_to_sell": [ 
       "GBP", 
       "USD" 
     ], 
     "interested_currencies_to_buy": [ 
       "GBP", 
       "USD" 
     ] 
   } 
 } 
 

Parameters

Name	In	Type	Required	Description
customer_type	body	string	true	Registering customer type
company	body	object	false	Only required for Business Customer. These are the details of your Company.
» name	body	string	true	Name of the company
» type	body	string	true	Company type
» vat_number	body	string	false	Company's VAT number
» registration_number	body	string	true	Company's registration number
» country_of_incorporation	body	string	true	Country where the company is registered
» address	body	object	true	Container for address details.
»» unit_number	body	string	false	Unit number
»» street_number	body	string	false	Street number
»» street	body	string	false	Street name
»» street_type	body	string	false	Type of street.
»» post_code	body	string	true	Postcode or zip code
»» city	body	string	true	City name
»» civic_number	body	string	false	Civic number
»» state	body	string	false	State
»» country	body	string	true	Contact country code
contacts	body	[object]	true	This is an array with a minimum of one Contact object and maximum of two.
» first_name	body	string	true	First name of this contact person.
» middle_name	body	string	false	Middle name of this contact person.
» last_name	body	string	true	Last name of this contact person.
» date_of_birth	body	string	true	DOB of contact person
» occupation	body	string	false	Occupation of the contact
» nationality	body	string	false	Nationality of the contact
» email	body	string	true	Email address of the contact person
» phone_number	body	string	false	Contact phone number
» mobile_number	body	string	true	mobile number of the contact
» primary_contact	body	boolean	true	Primary contact for the customer account
» authorize_to_trade	body	boolean	true	Whether the customer is authorised to trade with us.
» address	body	object	true	Container for address details.
»» unit_number	body	string	false	Unit number
»» street_number	body	string	false	Street number
»» street	body	string	false	Street name
»» street_type	body	string	false	Street type
»» post_code	body	string	true	Postcode or zip code
»» city	body	string	true	City name
»» civic_number	body	string	false	Civic number
»» state	body	string	false	State
»» country	body	string	true	Contact country code
» proof_of_identity	body	object	false	Proof of identity
»» oneOf
»»» passport	body	object	false	Container for passport details.
»»»» number	body	string	true	Passport number
»»»» name_at_citizenship	body	string	false	Name as per citizenship
»»»» family_name_at_birth	body	string	false	Family name at the time of birth
»»»» place_of_birth	body	string	true	Place of birth
»»»» expiry_date	body	string	true	Expiry date
»»»» issuing_country	body	string	true	Passport issuing country
»» xor
»»» medicare	body	object	false	Container for Medicare details.
»»»» card_number	body	string	true	Medicare card number
»»»» reference_number	body	string	true	Medicare reference number
»» xor
»»» nationalId	body	object	false	Container for National Id details.
»»»» id	body	string	true	National id number
»»»» type	body	string	true	National id type
»» xor
»»» drivingLicence	body	object	false	Container for Driving Licence details.
»»»» number	body	string	true	Driving licence number
»»»» card_number	body	string	false	Driving licence card number
»»»» state_code	body	string	false	Driving licence state code
»»»» version	body	string	false	Driving licence version number
»»»» expiry_date	body	string	true	Driving licence expiry date
»»»» issuing_country	body	string	true	Driving licence issuing country
additional_details	body	object	false	Any additional information you would like to share with us
» client_reference_id	body	string	false	Unique reference id that you want to assign to this customer for your own purposes.
» campaign	body	string	false	Name of Campaign during which this customer first became involved.
» campaign_reference	body	string	false	Campaign reference.
» interested_currencies_to_sell	body	[string]	false	Currencies that the customer is interested in selling.
» interested_currencies_to_buy	body	[string]	false	Currencies that the customer is interested in buying.

Example responses

200 Response

{ 
   "client_reference_id": "987564823645", 
   "unique_identifier": "6d23072a-ac3e-4146-9b83-7ad384d65707" 
 } 
 

Responses

Status Code 200

Ok. The customer object was created and is pending review. The returned temporary customer number can be used to check for the Customer ID.

Name	Type	Description
client_reference_id	string	Unique reference id that you want to assign to this customer for your own purposes.
unique_identifier	string	A unique identifier which you can use to get the finalised Customer record with a GET call to the Customers resource.

Get Customer's ID

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers?uniqueIdentifier=string \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers', 
   method: 'get', 
   data: '?uniqueIdentifier=string', 
   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers', params={ 
   'uniqueIdentifier': 'string' 
 }, headers = headers) 

 print r.json() 

 

GET /v1/customers

Get a Customer's ID using the unique identifier provided by the Create Customer POST request.

Parameters

Name	In	Type	Required	Description
uniqueIdentifier	query	string	true	Unique ID for this Customer provided by the CreateCustomers operation.

Example responses

200 Response

{ 
     "customer_id": "0045698757" 
 } 
 

Responses

Name	Type	Description
customer_id	string	Unique customer id to be used in all future API calls.

Get Customer

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}

Review a Customer's details.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

{ 
   "customer_type": "Business", 
   "status": "Active", 
   "company": { 
     "name": "Robin Hood Ltd", 
     "type": "Pvt Ltd", 
     "vat_number": "7979797979", 
     "registration_number": "13123121", 
     "country_of_incorporation": "GBR", 
     "address": { 
       "unit_number": "12", 
       "street": "London Road", 
       "street_type": "Canary Wharf", 
       "post_code": "E14 5AB", 
       "city": "LONDON", 
       "country": "GBR" 
     } 
   }, 
   "contacts": [ 
     { 
       "first_name": "Robin", 
       "middle_name": "Junior", 
       "last_name": "Hood", 
       "date_of_birth": "2072-04-30", 
       "occupation": "Analyst", 
       "nationality": "British", 
       "email": "[email protected]", 
       "phone_number": "+44-2020202020", 
       "mobile_number": "+44-8080808080", 
       "primary_contact": true, 
       "authorize_to_trade": true, 
       "status": "Inactive", 
       "documents_required": [ 
         { 
           "document_type": "POA", 
           "uri": "/v1/customers/0005924291/contacts/731561/documents/123443455454-78955" 
         }, 
         { 
           "document_type": "POI", 
           "uri": "/v1/customers/0005924291/contacts/731561/documents/123443455454-78955" 
         } 
       ], 
       "address": { 
         "unit_number": "12", 
         "street": "London Road", 
         "street_type": "High Street", 
         "post_code": "E14 4DF", 
         "city": "LONDON", 
         "country": "GBR" 
       } 
     } 
   ] 
 } 

 

Responses

Name	Type	Description
customer_type	string	Registering customer type
status	string	Whether the customer is active or inactive.
documents_required	object	When there are outstanding documents for a Customer, this is an array of document objects.
» document_type	string	Type of document required. Either POI or POA; for Proof-of-Identity or Proof-of-Address.
» uri	string	URI to call when sending the document back to Torfx.
company	object	Returned for Business Customer. These are the details of your Company.
» name	string	Name of the company
» type	string	Company type
» vat_number	string	Company's VAT number
» registration_number	string	Company's registration number
» country_of_incorporation	string	Country where the company is registered
» address	object	Container for address details.
»» unit_number	string	Unit number
»» street_number	string	Street number
»» street	string	Street name
»» street_type	string	Type of street.
»» post_code	string	Postcode or zip code
»» city	string	City name
»» civic_number	string	Civic number
»» state	string	State
»» country	string	Contact country code
contacts	[object]	This is an array with a minimum of one Contact object
» first_name	string	First name of this contact person.
» middle_name	string	Middle name of this contact person.
» last_name	string	Last name of this contact person.
» date_of_birth	string	DOB of contact person
» occupation	string	Occupation of the contact
» nationality	string	Nationality of the contact
» email	string	Email address of the contact person
» phone_number	string	Contact phone number
» mobile_number	string	mobile number of the contact
» primary_contact	boolean	Primary contact for the customer account
» authorize_to_trade	boolean	Whether the customer is authorised to trade with us.
» status	string	Whether the Contact is active or inactive.
» documents_required	object	When there are outstanding documents for a Contact, this is an array of document objects.
»» document_type	string	Type of document required. Either POI or POA; for Proof-of-Identity or Proof-of-Address.
»» uri	string	URI to call when sending the document back to Torfx.
» address	object	Container for address details.
»» unit_number	string	Unit number
»» street_number	string	Street number
»» street	string	Street name
»» street_type	string	Street type
»» post_code	string	Postcode or zip code
»» city	string	City name
»» civic_number	string	Civic number
»» state	string	State
»» country	string	Contact country code
» proof_of_identity	object	Proof of identity if provided by customer
»» oneOf
»»» passport	object	Container for passport details.
»»»» number	string	Passport number
»»»» name_at_citizenship	string	Name as per citizenship
»»»» family_name_at_birth	string	Family name at the time of birth
»»»» place_of_birth	string	Place of birth
»»»» expiry_date	string	Expiry date
»»»» issuing_country	string	Passport issuing country
»» xor
»»» medicare	object	Container for Medicare details.
»»»» card_number	string	Medicare card number
»»»» reference_number	string	Medicare reference number
»» xor
»»» nationalId	object	Container for National Id details.
»»»» id	string	National id number
»»»» type	string	National id type
»» xor
»»» drivingLicence	object	Container for Driving Licence details.
»»»» number	string	Driving licence number
»»»» card_number	string	Driving licence card number
»»»» state_code	string	Driving licence state code
»»»» version	string	Driving licence version number
»»»» expiry_date	string	Driving licence expiry date
»»»» issuing_country	string	Driving licence issuing country

Contacts

The Contacts resource allows you to create, update and delete your contact details, and related information.

Add a Contact

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/customers/{customerId}/contacts

Add a Contact to a Customer. When a Contact is created it has a status of Inactive. To get Customer Status updates you can subscribe to the webfeed using the Webhooks Resource.

Body parameter

[ 
   { 
     "first_name": "Carlos", 
     "middle_name": "", 
     "last_name": "Lopez", 
     "date_of_birth": "1980-02-14", 
     "occupation": "Software Engineer", 
     "nationality": "United States of America", 
     "email": "[email protected]", 
     "phone_number": "(020)123456789", 
     "mobile_number": "+44-987654321", 
     "primary_contact": true, 
     "authorize_to_trade": true, 
     "address": { 
       "unit_number": "", 
       "street_number": "468", 
       "street": "Bissonnet Plaza, El Campo", 
       "street_type": "Plaza", 
       "post_code": 77023, 
       "city": "Houston", 
       "civic_number": "", 
       "state": "Texas", 
       "country": "USA" 
     }, 
     "proof_of_identity": { 
       "passport": { 
         "number": "12345", 
         "name_at_citizenship": "Lopez", 
         "family_name_at_birth": "Lopez", 
         "place_of_birth": "Houston, USA", 
         "expiry_date": "2025-09-30", 
         "issuing_country": "USA" 
       } 
     } 
   } 
 ] 
 

Parameters

Name	In	Type	Required	Description
first_name	body	string	true	First name of this contact person.
middle_name	body	string	false	Middle name of this contact person.
last_name	body	string	true	Last name of this contact person.
date_of_birth	body	string	true	DOB of contact person
occupation	body	string	false	Occupation of the contact
nationality	body	string	true	Nationality of the contact
email	body	string	true	Email address of the contact person
phone_number	body	string	false	Contact phone number
mobile_number	body	string	false	Mobile number of the contact
primary_contact	body	boolean	true	Primary contact for the customer account
authorize_to_trade	body	boolean	true	Whether the customer is authorised to trade with us.
address	body	object	true	Container for address details.
» unit_number	body	string	false	Unit number
» street_number	body	string	false	Street number
» street	body	string	false	Street name
» street_type	body	string	false	Street type
» post_code	body	string	true	Postcode or zip code
» city	body	string	true	City name
» civic_number	body	string	false	Civic number
» state	body	string	false	State
» country	body	string	true	Contact country code
proof_of_identity	body	object	false	Proof of identity
» oneOf
»» passport	body	object	false	Container for passport details.
»»» number	body	string	true	Passport number
»»» name_at_citizenship	body	string	false	Name as per citizenship
»»» family_name_at_birth	body	string	false	Family name at the time of birth
»»» place_of_birth	body	string	true	Place of birth
»»» expiry_date	body	string	true	Expiry date
»»» issuing_country	body	string	true	Passport issuing country
» xor
»» medicare	body	object	false	Container for Medicare details.
»»» card_number	body	string	true	Medicare card number
»»» reference_number	body	string	true	Medicare reference number
» xor
»» nationalId	body	object	false	Container for National Id details.
»»» id	body	string	true	National id number
»»» type	body	string	true	National id type
» xor
»» drivingLicence	body	object	false	Container for Driving Licence details.
»»» number	body	string	true	Driving licence number
»»» card_number	body	string	false	Driving licence card number
»»» state_code	body	string	false	Driving licence state code
»»» version	body	string	false	Driving licence version number
»»» expiry_date	body	string	true	Driving licence expiry date
»»» issuing_country	body	string	true	Driving licence issuing country
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

{ 
   "customer_id": "0201563989" 
 } 
 

Responses

Status Code 200

Ok.

Name	Type	Description
customer_id	string	ID of Customer to whom the Recipient belongs. You should be retrieving the contacts that you just added using this id

Update a Contact

Code samples

# You can also use wget 
 curl -X PUT https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId} \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}', 
   method: 'put', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.put('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}', params={ 

 }, headers = headers) 

 print r.json() 

 

PUT /v1/customers/{customerId}/contacts/{contactId}

Update the details of a Contact who belongs to this Customer.

Body parameter

{ 
   "occupation": "Software Engineer", 
   "phone_number": "(020)123456789", 
   "mobile_number": "+44-987654321", 
   "primary_contact": true, 
   "authorize_to_trade": true, 
   "address": { 
     "unit_number": "", 
     "street_number": "468", 
     "street": "Bissonnet Plaza, El Campo", 
     "street_type": "Plaza", 
     "post_code": 77023, 
     "city": "Houston", 
     "civic_number": "", 
     "state": "Texas", 
     "country": "USA" 
   } 
 } 
 

Parameters

Name	In	Type	Required	Description
occupation	body	string	false	Occupation of the contact
phone_number	body	string	false	Contact phone number
mobile_number	body	string	false	Mobile number of the contact
primary_contact	body	boolean	false	Primary contact for the customer account
authorize_to_trade	body	boolean	false	Whether the customer is authorised to trade with us.
address	body	object	false	Container for address details.
» unit_number	body	string	false	Unit number
» street_number	body	string	false	Street number
» street	body	string	false	Street name
» street_type	body	string	false	Street type
» post_code	body	string	true	Postcode or zip code
» city	body	string	true	City name
» civic_number	body	string	false	Civic number
» state	body	string	false	State
» country	body	string	true	Contact country code
customerId	path	string	true	Unique Customer Identifier
contactId	path	string	true	Unique ID for this contact.

Example responses

200 Response

{ 
   "customer_id": 34000247, 
   "contact_id": 12345678 
 } 
 

Responses

Status Code 200

Ok.

Name	Type	Description
customer_id	string	ID of Customer related to the Contact.
contact_id	string	ID of Contact.

Remove a Contact

Code samples

# You can also use wget 
 curl -X DELETE https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId} \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}', 
   method: 'delete', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.delete('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}', params={ 

 }, headers = headers) 

 print r.json() 

 

DELETE /v1/customers/{customerId}/contacts/{contactId}

Remove a Contact from this Customer.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
contactId	path	string	true	Unique ID for this contact.

Recipients

This resource allows you to manage your Recipient Account details. The Recipient is a person or institution who is the final beneficiary of your payment.

Create Recipient

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/customers/{customerId}/recipients

To make a transfer, you'll need to add details of the Recipient's account. There are a number of parameters which you can use to specify this account, but generally, Recipient data objects consist of:

General Information

• Recipient personal details
• Legal structure (Individual/ Corporation)
• Contact information
• Country Code (ISO3166-1 alpha-3)

Recipient Bank Account Details

Recipient Bank Account Details vary for different countries. For example, the IBAN number is sufficient for most European and Nordic countries but you need Account Number, Routing Code Type, Routing Code Value and Bank Country Code to send money to the US.

In total there are four different variations of Recipient Bank Account Details possible. These are:

• IBAN
• Account Number, Swift Code
• Account Number, Swift Code, Routing Code Type and Routing Code Value
• Account Number, Routing Code Type, Routing Code Value and Bank Country Code

You will also need to provide the code for the currency of the bank account in ISO 4217 three letter format (e.g. GBP for UK pound).

Address Data

• State (US, Canada, Brazil)
• City
• Address line
• Postcode
• Request
  

Body parameter

{ 
   "name": "Bob Nighy", 
   "nick_name": "Bob", 
   "type": "Individual", 
   "email": "[email protected]", 
   "phone_number": "(020)123456789", 
   "mobile_number": "+44-987654321", 
   "client_reference_id": "937564823645", 
   "country_code": "GBR", 
   "address": { 
     "address_line": "3 Stable Mews, Westminster", 
     "city": "London", 
     "state": "England", 
     "post_code": "WC1" 
   }, 
   "recipient_bank_details": { 
     "currency": "USD", 
     "iban": "GB29NWBK60161331926819" 
   } 
 } 
 

Parameters

Name	In	Type	Required	Description
name	body	string	true	Name of the Recipient.
nick_name	body	string	false	Optional Recipient's nickname. This can be used to find a Recipient's details quickly using the search functionality.
type	body	string	true	Organisational type of a Recipient; whether an Individual or Corporate.
email	body	string	false	Email address of a Recipient, which may be used in case of an issue with a transaction.
phone_number	body	string	false	Recipient's phone number.
mobile_number	body	string	false	Recipient's mobile number.
client_reference_id	body	string	false	A Reference Id that you can assign to this Recipient, for your records.
country_code	body	string	true	Three letter Country Code of the Recipient (as specified in ISO 3166-1 alpha-3).
address	body	object	false	Container for address details.
» address_line	body	string	true	First line of the postal address of the Recipient.
» city	body	string	true	Recipient's city, town, or village.
» state	body	string	true	Recipient's state, country, province or a prefecture.
» post_code	body	string	true	Recipient's postal code, zip code or pin code.
recipient_bank_details	body	object	true	Bank details of the Recipient.
» allOf
»» currency	body	string	true	Three letter Currency Code (as specified by ISO4217).
» and
»» oneOf
»»» iban	body	string	true	Recipient IBAN as per their bank records.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» swift_code	body	string	true	Swift Code of the Recipient's bank account.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» swift_code	body	string	true	Swift Code of the Recipient's bank account.
»»» routing_code_type	body	string	true	Recipient routing code type:
»»» routing_code_value	body	string	true	Routing Code of the Recipient's bank account.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» routing_code_type	body	string	true	Recipient routing code type:
»»» routing_code_value	body	string	true	Routing Code of the Recipient's bank account.
»»» bank_country_code	body	string	true	Recipient bank country code
customerId	path	string	true	Unique Customer Identifier

Example responses

201 Response

{ 
   "client_reference_id": "937564823645", 
   "recipient_id": "743512" 
 } 
 

Responses

Status Code 201

Successfully created a Recipient's account.

Name	Type	Description
client_reference_id	string	Unique client reference to identify this Recipient in future.
recipient_id	string(int32)	Unique recipient reference id which can be used to identify/retrieve recipient in future.

Get Recipients

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/recipients

Get the details of all active Recipients for this Customer.

Parameters

Name	In	Type	Required	Description
page	query	number(int32)	false	For queries that return arrays of data. Including this optional query parameter causes the set of results to be paginated by this number of pages.
limit	query	number(int32)	false	For queries that return arrays of data. Adding this optional query parameter causes the set of results to be split into pages of this size. Default is 50.
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

{ 
   "recipients": [ 
     { 
       "recipient_id": 743513, 
       "name": "Bob Nigh", 
       "type": "Individual", 
       "country_code": "GBR", 
       "nick_name": "Bob", 
       "email": "[email protected]", 
       "phone_number": "(020)123456789", 
       "mobile_number": "+44-987654321", 
       "client_reference_id": "937564823645", 
       "address": { 
         "address_line": "3 Stable Mews, Westminster", 
         "city": "London", 
         "state": "London", 
         "post_code": "TW3 4DF" 
       }, 
       "recipient_bank_details": { 
         "currency_code": "USD", 
         "bank_name": "NATIONAL WESTMINSTER BANK PLC", 
         "country_code": "GBR", 
         "iban": "GB29NWBK60161331926819" 
       }, 
       "status": "ACTIVE", 
       "last_updated": "2019-01-21T09:27:30Z" 
     } 
   ], 
   "meta_data": { 
     "next_page": "v1/customers/0202000005923566/recipients?page=5&limit=20", 
     "previous_page": "v1/customers/0202000005923566/recipients?page=3&limit=20", 
     "total_pages": "5", 
     "total_records": "98" 
   } 
 } 
 

Responses

Status Code 200

Ok. A Recipient or Recipients were found and their data is returned in the response body.

Name	Type	Description
recipients	[object]	Array for the Recipients.
» recipient_id	string	The Payee ID used to identify this Recipient.
» name	string	Name of the Recipient as per their bank records.
» type	string	Type of the recipient to be chosen from enum list
» country_code	string	Recipient's Country Code (as specified in ISO 3166-1 alpha-3).
» nick_name	string	Recipient's nickname. This can be used to find a Recipient's details quickly using the search functionality.
» email	string	email id to which you want to receive the communications
» phone_number	string	Payee phone number
» mobile_number	string	Payee mobile number
» client_reference_id	string	Unique client reference to identify this Recipient in future.
» address	object	Container for address details.
»» address_line	string	First line of the postal address of the Recipient.
»» city	string	Recipient's city, town, or village.
»» state	string	Recipient's state, country, province or a prefecture.
»» post_code	string	Payee postal code, zip code or pin code.
» recipient_bank_details	object	Container for recipient bank details.
»» allOf
»»» currency_code	string	Recipient's Currency Code (per ISO4217).
»»» bank_name	string	Name of Recipient's Bank
»»» country_code	string	Country Code of the Recipient's Bank (as specified in ISO 3166-1 alpha-3).
»» and
»»» oneOf
»»»» iban	string	Recipient IBAN as per their bank records.
»»» xor
»»»» account_number	string	Recipient's bank account number as per their statement.
»»»» swift_code	string	Swift Code of the Recipient's bank account.
»»»» routing_code_type	string	Recipient routing code type: * IFSC - Indian Financial System Code, * SORT - Sort Code for British and Irish banks, * BRANCH - Branch Code, * CNAPS - China National Advanced Payment System, * ABA - American Bankers Association used in the United States, * BSB - Bank State Branch used in Australia, * Transit - used for Canada.
»»»» routing_code_value	string	Routing Code of the Recipient's bank account.
»»» xor
»»»» account_number	string	Recipient's bank account number as per their statement.
»»»» routing_code_type	string	Recipient routing code type: * IFSC - Indian Financial System Code, * SORT - Sort Code for British and Irish banks, * BRANCH - Branch Code, * CNAPS - China National Advanced Payment System, * ABA - American Bankers Association used in the United States, * BSB - Bank State Branch used in Australia, * Transit - used for Canada.
»»»» routing_code_value	string	Routing Code of the Recipient's bank account.
»»»» country_code	string	Recipient bank country code.
» status	string	Status of this record.
» last_updated	string(datetime)	Last modification timestamp.
meta_data	object	Container for metadata.
» next_page	string(uri)	URL to next page of data. This field is omitted for the last page.
» previous_page	string(uri)	URL to the previous page of data. This field is omitted for the first page.
» total_pages	string(int32)	Number of pages of available data.
» total_records	string(int32)	Number of records of available data.

Get a Recipient

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId}', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId}', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/recipients/{recipientId}

Get the details of a Recipient's account using the Customer ID and Payee ID as parameters. This call will also return details of inactive recipients.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
recipientId	path	string	true	Unique Recipient Identifier.

Example responses

200 Response

{ 
   "recipient_id": 743513, 
   "name": "Bob Nigh", 
   "type": "Individual", 
   "country_code": "GBR", 
   "email": "[email protected]", 
   "phone_number": "(020)123456789", 
   "mobile_number": "+44-987654321", 
   "client_reference_id": "937564823645", 
   "last_updated": "2019-01-21T09:27:30Z", 
   "status": "ACTIVE", 
   "address": { 
     "address_line": "3 Stable Mews, Westminster", 
     "city": "London", 
     "state": "London", 
     "post_code": "TW3 4DF" 
   }, 
   "recipient_bank_details": { 
     "currency_code": "USD", 
     "bank_name": "NATIONAL WESTMINSTER BANK PLC", 
     "country_code": "GBR", 
     "iban": "GB29NWBK60161331926819" 
   } 
 } 
 

Responses

Status Code 200

Ok. The Recipient was found and their data is returned in the response body.

Name	Type	Description
recipient_id	string	The Payee ID used to identify this Recipient.
name	string	Name of the Recipient as per their bank records.
type	string	Type of the recipient to be chosen from enum list
country_code	string	Recipient's Country Code (as specified in ISO 3166-1 alpha-3).
email	string	email id to which you want to receive the communications
phone_number	string	Payee phone number
mobile_number	string	Payee mobile number
client_reference_id	string	Unique client reference to identify this Recipient in future.
last_updated	string(datetime)	Last modification timestamp.
status	string	Status of this record.
address	object	Container for address details.
» address_line	string	First line of the postal address of the Recipient.
» city	string	Recipient's city, town, or village.
» state	string	Recipient's state, country, province or a prefecture.
» post_code	string	Payee postal code, zip code or pin code.
recipient_bank_details	object	none
» allOf
»» currency_code	string	Recipient's Currency Code (per ISO4217).
»» bank_name	string	Name of Recipient's Bank
»» country_code	string	Country Code of the Recipient's Bank (as specified in ISO 3166-1 alpha-3).
» and
»» oneOf
»»» iban	string	Recipient IBAN as per their bank records.
»» xor
»»» account_number	string	Recipient's bank account number as per their statement.
»»» swift_code	string	Swift Code of the Recipient's bank account.
»»» routing_code_type	string	Recipient routing code type: * IFSC - Indian Financial System Code, * SORT - Sort Code for British and Irish banks, * BRANCH - Branch Code, * CNAPS - China National Advanced Payment System, * ABA - American Bankers Association used in the United States, * BSB - Bank State Branch used in Australia, * Transit - used for Canada.
»»» routing_code_value	string	Routing Code of the Recipient's bank account.
»» xor
»»» account_number	string	Recipient's bank account number as per their statement.
»»» routing_code_type	string	Recipient routing code type: * IFSC - Indian Financial System Code, * SORT - Sort Code for British and Irish banks, * BRANCH - Branch Code, * CNAPS - China National Advanced Payment System, * ABA - American Bankers Association used in the United States, * BSB - Bank State Branch used in Australia, * Transit - used for Canada.
»»» routing_code_value	string	Routing Code of the Recipient's bank account.
»»» country_code	string	Recipient bank country code

Update Recipient

Code samples

# You can also use wget 
 curl -X PUT https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId} \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId}', 
   method: 'put', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.put('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId}', params={ 

 }, headers = headers) 

 print r.json() 

 

PUT /v1/customers/{customerId}/recipients/{recipientId}

Update a Recipient's account

Body parameter

{ 
   "name": "Bob Nigh", 
   "nick_name": "Bob", 
   "type": "Individual", 
   "email": "[email protected]", 
   "phone_number": "(020)123456789", 
   "mobile_number": "+44-987654321", 
   "country_code": "GBR", 
   "address": { 
     "address_line": "3/4 Stable Mews, Westminster", 
     "city": "London", 
     "state": "London", 
     "post_code": "TW3 4DF" 
   }, 
   "recipient_bank_details": { 
     "currency": "USD", 
     "currency_code": "USD", 
     "country_code": "GBR", 
     "iban": "GB29NWBK60161331926819" 
   } 
 } 
 

Parameters

Name	In	Type	Required	Description
name	body	string	false	Name of the Recipient as per their bank records.
nick_name	body	string	false	Recipient's nickname. This can be used to find a Recipient's details quickly using the search functionality.
type	body	string	false	Type of the recipient to be chosen from enum list
email	body	string	false	email id to which you want to receive the communications
phone_number	body	string	false	Payee phone number
mobile_number	body	string	false	Payee mobile number
country_code	body	string	false	Recipient's Country Code (as specified in ISO 3166-1 alpha-3).
address	body	object	false	Container for address details.
» address_line	body	string	true	First line of the postal address of the Recipient.
» city	body	string	true	Recipient's city, town, or village.
» state	body	string	true	Recipient's state, country, province or a prefecture.
» post_code	body	string	true	Payee postal code, zip code or pin code.
recipient_bank_details	body	object	false	none
» allOf
»» currency	body	string	true	Recipient's Currency Code (per ISO4217).
» and
»» oneOf
»»» iban	body	string	true	Recipient IBAN as per their bank records.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» swift_code	body	string	true	Swift Code of the Recipient's bank account.
»»» routing_code_type	body	string	false	Recipient routing code type: * IFSC - Indian Financial System Code, * SORT - Sort Code for British and Irish banks, * BRANCH - Branch Code, * CNAPS - China National Advanced Payment System, * ABA - American Bankers Association used in the United States, * BSB - Bank State Branch used in Australia, * Transit - used for Canada.
»»» routing_code_value	body	string	false	Routing Code of the Recipient's bank account.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» routing_code_type	body	string	true	Recipient routing code type:
»»» routing_code_value	body	string	true	Routing Code of the Recipient's bank account.
»»» bank_country_code	body	string	true	Recipient bank country code
customerId	path	string	true	Unique Customer Identifier
recipientId	path	string	true	Unique Recipient Identifier.

Example responses

200 Response

{ 
   "recipient_id": "743512" 
 } 
 

Responses

Status Code 200

Successfully updated a Recipient's account.

Name	Type	Description
recipient_id	string	Recipient Id of the record which was amended.

Delete Recipient

Code samples

# You can also use wget 
 curl -X DELETE https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId}', 
   method: 'delete', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.delete('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/recipients/{recipientId}', params={ 

 }, headers = headers) 

 print r.json() 

 

DELETE /v1/customers/{customerId}/recipients/{recipientId}

This will set the status of the Recipient to inactive.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
recipientId	path	string	true	Unique Recipient Identifier.

Example responses

200 Response

{ 
   "code": "000", 
   "description": "Operation completed successfully" 
 } 
 

Responses

Status Code 200

Successfully deleted a Recipient's account.

Name	Type	Description
code	string	Code should be '000'.
description	string	Message should be 'Operation completed successfully'.

Rates

Get current foreign exchange rates.

Get Exchange Rates

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/rates?pair=USDGBP \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/rates', 
   method: 'get', 
   data: '?pair=USDGBP', 
   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/rates', params={ 
   'pair': 'USDGBP' 
 }, headers = headers) 

 print r.json() 

 

GET /v1/rates

Retrieve the current Market Exchange Rates for one or more currency pairs (such as USDGBP). This information is constantly being updated.

Parameters

Name	In	Type	Required	Description
pair	query	string	true	A pair of three letter Currency Codes (as specified by ISO4217). You can provide a series of currency pairs (e.g. ?pair=USDGBP&pair=USDEUR&pair=EURINR&pair=EURAUD) to reduce the number of requests you make.

Example responses

200 Response

[ 
   { 
     "Quote": "1.30741", 
     "Time": "Wed Apr 10 11:26:32 BST 2019", 
     "Name": "GBPUSD" 
   }, 
   { 
     "Quote": "0.88695", 
     "Time": "Wed Apr 10 11:25:59 BST 2019", 
     "Name": "USDEUR" 
   }, 
   { 
     "Quote": "78.1134", 
     "Time": "Wed Apr 10 11:26:32 BST 2019", 
     "Name": "EURINR" 
   }, 
   { 
     "Quote": "1.57695", 
     "Time": "Wed Apr 10 11:26:32 BST 2019", 
     "Name": "EURAUD" 
   } 
 ] 
 

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

Name	Type	Description
Name	string	The Currency Code pair.
Time	string	Timestamp of the currency rate.
Quote	string	Price of the currencies pair.

Quotes

Get fixed price quotations.

Get Quotation

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/quotes \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/quotes', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/quotes', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/customers/{customerId}/quotes

Request a fixed price quotation. This is will be given for the exchange of an amount of one currency for another. For instance, sell 1000 GBP and buy EUR. The response will contain the Quote details and expiration timestamp.

Body parameter

{ 
   "sell_currency": "GBP", 
   "buy_currency": "USD", 
   "amount": 1000.45, 
   "fixed_side": "BUY" 
 } 
 

Parameters

Name	In	Type	Required	Description
sell_currency	body	string	true	Three letter Currency Code (ISO4217) you want to sell.
buy_currency	body	string	true	Three letter Currency Code (ISO4217) you want to buy.
amount	body	number	true	Amount you want to exchange. Note: If the fixed_side is 'SELL' (the default) this amount relates to the sell_currency. If the fixed_side is 'BUY' it relates to the buy_currency.
fixed_side	body	string	false	Which side of the payment you want to fix. The default is SELL. See amount.
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

{ 
   "quote_id": "548eb44b-5e1b-45fb-86eb-88eb5bcaa781", 
   "customer_id": "0202000005923566", 
   "sell_currency": "GBP", 
   "buy_currency": "USD", 
   "amount": 1000.45, 
   "fixed_side": "BUY", 
   "quote_details": { 
     "quote_price": 775.78, 
     "quote_rate": 1.2896, 
     "expiry": "2018-09-26T09:51:47.991+01:00" 
   } 
 } 
 

Responses

Status Code 200

Ok. A quotation was created and returned in the response body.

Name	Type	Description
quote_id	string(guid)	Unique ID for this quotation.
customer_id	string	ID of Customer to whom the Recipient belongs.
sell_currency	string	Currency (ISO currency code) you want to sell
buy_currency	string	Currency (ISO currency code) you want to buy
amount	number	Amount you want to exchange. Note: If the fixed_side is 'SELL' (the default) this amount relates to the sell_currency. If the fixed_side is 'BUY' it relates to the buy_currency.
fixed_side	string	Which side of the payment you want to fix. The default is SELL. See amount.
quote_details	object	Container for quote details.
» quote_price	number	Total for this exchange. Note: If the fixed_side is 'SELL' (the default) this amount relates to the buy_currency. If the fixed_side is 'BUY' it relates to the sell_currency.
» quote_rate	number	Rate of this quote.
» expiry	string(dateTime)	Timestamp for the expiration of this quote.

Conversions

Execute a Forex Exchange, swapping one currency for another.

Request Conversion

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/customers/{customerId}/conversions

This will execute the exchange of one currency for another in accordance with a Quote. For instance, if you requested a quotation to sell 1000 GBP and buy EUR and then called this Resource with the quote_id (and prior to the quote's expiry), then the exchange will be fulfilled. A successful response will contain the conversion_id which you can use to check for status updates. Note: Once requested, you should ensure that your wallet balance is sufficient to fund this conversion.

Body parameter

{ 
   "quote_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375" 
 } 
 

Parameters

Name	In	Type	Required	Description
client_reference_id	query	string	false	Unique reference id that you want to assign to this conversions for your own purposes. This can be used to retrieve the Conversion details and also as a way of preventing duplicate requests.
quote_id	body	string(guid)	true	ID of Quote to be used as the basis for the Conversion (see Quotes). Note: You can only request one conversion from a quote.
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

{ 
     "conversion_id": 2907898, 
     "instruction_number": "0202000005923566-000000011", 
     "selling_currency": "GBP", 
     "buying_currency": "EUR", 
     "selling_amount": "2.3", 
     "buying_amount": "2.57", 
     "agreed_rate": 1.1181, 
     "booking_datetime": "2018-10-19T10:51:13Z", 
     "status": "OPEN", 
     "value_date": "2018-10-19" 
 } 
 

Responses

Status Code 200

Ok. The forex conversion request was successful. Note: If you don't send funds within 24 hours, your transfer may be delayed, and you may incur additional charges as per our terms and conditions.

Name	Type	Description
conversion_id	string	ID of this currency exchange for future reference.
instruction_number	string	Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}
selling_currency	string	ISO Code for the currency being sold.
buying_currency	string	ISO Code for the currency being bought.
selling_amount	number(currency)	Amount of the currency being sold.
buying_amount	number(currency)	Amount of the currency being bought.
agreed_rate	number(int32)	Exchange rate. Amount of bought currency for each unit of sold currency.
booking_datetime	string(datetime)	Timestamp of this request / deal.
status	string	Status of this transaction
value_date	string(date)	This is the estimated date for the delivery of the funds into your wallet or (if making an outbound Payment) the Recipient's Bank Account. It is dependent upon a few conditions, such as a) the time of day of the request, b) whether there is sufficient cleared funds in your account, c) the currency and d) the payment processing route to the bank account.

View Conversions

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/conversions

Retrieve details of all your previous conversions.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
page	query	number(int32)	false	For queries that return arrays of data. Including this optional query parameter causes the set of results to be paginated by this number of pages.
limit	query	number(int32)	false	For queries that return arrays of data. Adding this optional query parameter causes the set of results to be split into pages of this size. Default is 50.

Example responses

200 Response

{ 
   "fx_conversions": [ 
     { 
       "conversion_id": 2907898, 
       "instruction_number": "0202000005923566-000000011", 
       "selling_currency": "GBP", 
       "buying_currency": "EUR", 
       "selling_amount": 2.3, 
       "buying_amount": 2.57, 
       "agreed_rate": 1.1181, 
       "booking_datetime": "2018-10-19T10:51:13Z", 
       "status": "pending", 
       "value_date": "2018-10-19" 
     } 
   ], 
   "meta_data": { 
     "next_page": "v1/customers/02020000123456789/conversions?page=2&limit=50", 
     "total_pages": "2", 
     "total_records": "98" 
   } 
 } 
 

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

Name	Type	Description
fx_conversions	[object]	Array of Conversion objects.
» conversion_id	string(int32)	ID of this currency exchange for future reference.
» instruction_number	string	Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}
» selling_currency	string	ISO Code for the currency being sold.
» buying_currency	string	ISO Code for the currency being bought.
» selling_amount	string	Amount of the currency being sold.
» buying_amount	string	Amount of the currency being bought.
» agreed_rate	string	Exchange rate. Amount of bought currency for each unit of sold currency.
» booking_datetime	string(datetime)	Timestamp of this request / deal.
» status	string	Status of this transaction
» value_date	string(date)	This is the estimated date for the delivery of the funds into your wallet or (if making an outbound Payment) the Recipient's Bank Account. It is dependent upon a few conditions, such as a) the time of day of the request, b) whether there is sufficient cleared funds in your account, c) the currency and d) the payment processing route to the bank account.
meta_data	object	Container for metadata.
» next_page	string(uri)	URL to next page of data. This field is omitted for the last page.
» previous_page	string(uri)	URL to the previous page of data. This field is omitted for the first page.
» total_pages	string(int32)	Number of pages of available data.
» total_records	string(int32)	Number of records of available data.

Get a Conversion

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions/{conversionId} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions/{conversionId}', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/conversions/{conversionId}', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/conversions/{conversionId}

Retrieve details of a previously requested currency conversion.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
conversionId	path	string	true	Unique Conversion ID, provided in the original request for a Conversion.

Example responses

200 Response

{ 
   "conversion_id": 2907898, 
   "instruction_number": "0202000005923566-000000011", 
   "selling_currency": "GBP", 
   "buying_currency": "EUR", 
   "selling_amount": 2.3, 
   "buying_amount": 2.57, 
   "agreed_rate": 1.1181, 
   "booking_datetime": "2018-10-19T10:51:13Z", 
   "status": "OPEN", 
   "value_date": "2018-10-19" 
 } 
 

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

Name	Type	Description
conversion_id	string	ID of this currency exchange for future reference.
instruction_number	string	Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}
selling_currency	string	ISO Code for the currency being sold.
buying_currency	string	ISO Code for the currency being bought.
selling_amount	string	Amount of the currency being sold.
buying_amount	string	Amount of the currency being bought.
agreed_rate	string	Exchange rate. Amount of bought currency for each unit of sold currency.
booking_datetime	string(datetime)	Timestamp of this request / deal.
status	string	Status of this transaction
value_date	string	This is the estimated date for the delivery of the funds into your wallet or (if making an outbound Payment) the Recipient's Bank Account. It is dependent upon a few conditions, such as a) the time of day of the request, b) whether there is sufficient cleared funds in your account, c) the currency and d) the payment processing route to the bank account.

Balances

Get your Wallet Balances.

Get Balances

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/balances \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/balances', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/balances', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/balances

Get wallet balances for all of your activated currencies.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

[ 
   { 
     "currency": "EUR", 
     "total_balance": 14302, 
     "available_balance": 14280, 
     "outstanding_balance": 0 
   }, 
   { 
     "currency": "GBP", 
     "total_balance": 0, 
     "available_balance": 0, 
     "outstanding_balance": 7375.73 
   }, 
   { 
     "currency": "NZD", 
     "total_balance": 2554.19, 
     "available_balance": 0, 
     "outstanding_balance": 0 
   }, 
   { 
     "currency": "USD", 
     "total_balance": 17040, 
     "available_balance": 17000, 
     "outstanding_balance": 0 
   } 
 ] 
 

Responses

Status Code 200

Ok. The response body contains an array of wallets' balances.

Name	Type	Description
currency	string	Three letter Currency Code (ISO4217).
total_balance	number(float)	Total balance is the amount of cleared funds in your account and includes any pending payments.
available_balance	number(float)	Available balance is the cleared funds minus any funds which are committed to an outgoing payment.
outstanding_balance	number(float)	Outstanding balance is the amount which you are expected to pay for pending orders.

Get a Balance

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/balances/{currencyCode} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/balances/{currencyCode}', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/balances/{currencyCode}', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/balances/{currencyCode}

Get wallet balances for a single currency.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
currencyCode	path	string	true	Three letter Currency Code (as specified by ISO4217).

Example responses

200 Response

{ 
   "currency": "INR", 
   "total_balance": 51749.42, 
   "available_balance": 50549.42, 
   "outstanding_balance": 1200 
 } 
 

Responses

Status Code 200

Ok. The response body contains balances for a single currency.

Name	Type	Description
currency	string	Three letter Currency Code (ISO4217).
total_balance	number(float)	Total balance is the amount of cleared funds in your account and includes any pending payments.
available_balance	number(float)	Available balance is the cleared funds minus any funds which are committed to an outgoing payment.
outstanding_balance	number(float)	Outstanding balance is the amount which you are expected to pay for pending orders.

Payments

Initiate Payments and Review their details.

Make a Payment

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/customers/{customerId}/payments

This will initiate the process of sending money to a Recipient. As preparation for this call you could make a GET request to the Recipients resource to check that the recipient has not been deleted. As this is an asynchronous request it will return with a success status code, a payment_id and a status of pending. To check the status of the payment you should make a GET call to the Payments resource.

Body parameter

{ 
   "client_reference_id": "987564823645", 
   "recipient_id": "743512", 
   "purpose_of_transaction": "PENSION", 
   "amount": 1.91, 
   "payment_reference": "saving 225" 
 } 
 

Parameters

Name	In	Type	Required	Description
client_reference_id	body	string	false	Unique reference id that you want to assign to this payment for your own purposes. This can be used to retrieve the Payment details and also as a way of preventing duplicate requests.
recipient_id	body	string	true	The Payee ID used to identify this Recipient.
purpose_of_transaction	body	string	true	Purpose of the transaction. A list of possible values can be obtained with a GET request to the transaction-purpose resource
amount	body	number(float)	true	Amount of the payment.
payment_reference	body	string	true	Description to appear on the Recipient's bank statement.
customerId	path	string	true	Unique Customer Identifier

Example responses

200 Response

{ 
   "payment_id": "2908362", 
   "instruction_number": "0202000005923566-000000011", 
   "currency_code": "string", 
   "amount": 51749.42, 
   "recipient_details": { 
     "recipient_id": 743512, 
     "recipient_name": "Bob Nighy", 
     "country_code": "GBR" 
   }, 
   "status": "PENDING", 
   "payment_reference": "saving 225", 
   "created_datetime": "2019-01-24T12:38:46Z", 
   "payment_date": "2019-01-24" 
 } 
 

Responses

Status Code 200

Ok. A payment was initiated.

Name	Type	Description
payment_id	string	Payment ID
instruction_number	string	Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}
currency_code	string	Recipient's Currency Code (per ISO4217).
amount	number(float)	Amount being debited.
recipient_details	object	Container for recipient details.
» recipient_id	string(int32)	Unique recipient reference id which can be used to identify/retrieve recipient in future.
» recipient_name	string	Name of the Recipient.
» country_code	string	Three letter Country Code of the Recipient (as specified in ISO 3166-1 alpha-3).
status	string	Status of this payment.
payment_reference	string	Description to appear on the Recipient's bank statement.
created_datetime	string(datetime)	Timestamp of the payment
payment_date	string(date)	Date when the payment was completed.

Review Payments

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/payments

Review all your Payments.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
page	query	number(int32)	false	For queries that return arrays of data. Including this optional query parameter causes the set of results to be paginated by this number of pages.
limit	query	number(int32)	false	For queries that return arrays of data. Adding this optional query parameter causes the set of results to be split into pages of this size. Default is 50.

Example responses

200 Response

{ 
     "payments": [ 
         { 
             "payment_id": "2932478", 
             "instruction_number": "0202000005924291-000000164", 
             "currency_code": "USD", 
             "amount": 10, 
             "recipient_details": { 
                 "recipient_name": "Chaitanya Naidu", 
                 "recipient_account_number": "457037479121", 
                 "country_code": "USA" 
             }, 
             "status": "INPROCESS", 
             "payment_reference": "987564823645", 
             "created_datetime": "2019-05-20T16:42:12Z", 
             "payment_date": "2019-05-20" 
         }, 
         { 
             "payment_id": "2932470", 
             "instruction_number": "0202000005924291-000000162", 
             "currency_code": "USD", 
             "amount": 10, 
             "recipient_details": { 
                 "recipient_name": "Chaitanya Naidu", 
                 "recipient_account_number": "457037479121", 
                 "country_code": "USA" 
             }, 
             "status": "INPROCESS", 
             "payment_reference": "987564823645", 
             "created_datetime": "2019-05-20T14:07:12Z", 
             "payment_date": "2019-05-20" 
         }, 
         { 
             "payment_id": "2932232", 
             "instruction_number": "0202000005924291-000000161", 
             "currency_code": "USD", 
             "amount": 1.91, 
             "recipient_details": { 
                 "recipient_name": "Chaitanya Naidu", 
                 "recipient_account_number": "457037479121", 
                 "country_code": "USA" 
             }, 
             "status": "INPROCESS", 
             "payment_reference": "saving 22", 
             "created_datetime": "2019-05-20T12:27:12Z", 
             "payment_date": "2019-05-20" 
         }, 
         { 
             "payment_id": "2932072", 
             "instruction_number": "0202000005924291-000000160", 
             "currency_code": "USD", 
             "amount": 1.91, 
             "recipient_details": { 
                 "recipient_name": "Chaitanya Naidu", 
                 "recipient_account_number": "457037479121", 
                 "country_code": "USA" 
             }, 
             "status": "INPROCESS", 
             "payment_reference": "saving 22", 
             "created_datetime": "2019-05-20T11:12:48Z", 
             "payment_date": "2019-05-20" 
         }, 
         { 
             "payment_id": "2907561", 
             "instruction_number": "0202000005924291-000000065", 
             "currency_code": "GBP", 
             "amount": 24.59, 
             "recipient_details": { 
                 "recipient_name": "James NJJJ", 
                 "recipient_account_number": "15487623", 
                 "country_code": "GBR" 
             }, 
             "status": "CANCELLED", 
             "payment_reference": "", 
             "created_datetime": "2019-01-21T15:14:18Z", 
             "payment_date": "2019-01-21" 
         } 
     ], 
     "meta_data": { 
         "next_page": "/v1/customers/0202000005924291/payments?page=2&limit=5", 
         "total_records": "38", 
         "total_pages": "8" 
     } 
 } 
 

Responses

Status Code 200

Ok. The response will contain a list of Payment Instructions.

Name	Type	Description
payments	[object]	Array of Payment instructions.
» payment_id	string	Payment ID
» instruction_number	string	Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}
» currency_code	string	Recipient's Currency Code (per ISO4217).
» amount	number(float)	Amount being debited.
» recipient_details	object	Container for recipient details.
»» recipient_id	integer(int32)	Unique recipient reference id which can be used to identify/retrieve recipient in future.
»» recipient_name	string	Name of the Recipient.
»» recipient_account_number	string	IBAN or account number of the recipient.
»» country_code	string	Three letter Country Code of the Recipient (as specified in ISO 3166-1 alpha-3).
» status	string	Status of this payment.
» payment_reference	string	Description to appear on the Recipient's bank statement.
» created_datetime	string(datetime)	Timestamp of the payment
» payment_date	string(date)	Date when the payment was completed.
meta_data	object	Container for metadata.
» next_page	string(uri)	URL to next page of data. This field is omitted for the last page.
» previous_page	string(uri)	URL to the previous page of data. This field is omitted for the first page.
» total_pages	string(int32)	Number of pages of available data.
» total_records	string(int32)	Number of records of available data.

View a Payment

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments/{paymentId} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments/{paymentId}', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/payments/{paymentId}', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/payments/{paymentId}

View a Single Payment.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
paymentId	path	string	true	Unique Payment Identifier

Example responses

200 Response

{ 
   "payment_id": "2908362", 
   "instruction_number": "0202000005923566-000000011", 
   "currency_code": "string", 
   "amount": 51749.42, 
   "recipient_details": { 
     "recipient_id": 743512, 
     "recipient_name": "Bob Nighy", 
     "recipient_account_number": "457037479121", 
     "country_code": "GBR" 
   }, 
   "status": "AWAITINGBANKAPPROVAL", 
   "payment_reference": "saving 225", 
   "created_datetime": "2019-01-24T12:38:46Z", -->
   "payment_date": "2019-01-24" 
 } 
 

Responses

Status Code 200

Ok. The response will contain details of the requested Payment Instruction.

Name	Type	Description
payment_id	string	Payment ID
instruction_number	string	Unique client reference to identify this conversion in future. The format will be {customerId}-{sequenceNumber}
currency_code	string	Recipient's Currency Code (per ISO4217).
amount	number(float)	Amount being debited.
recipient_details	object	Container for recipient details.
» recipient_id	integer(int32)	Unique recipient reference id which can be used to identify/retrieve recipient in future.
» recipient_name	string	Name of the Recipient.
» recipient_account_number	string	IBAN or account number of the recipient.
» country_code	string	Three letter Country Code of the Recipient (as specified in ISO 3166-1 alpha-3).
status	string	Status of this payment.
payment_reference	string	Description to appear on the Recipient's bank statement.
created_datetime	string(datetime)	Timestamp of the payment
payment_date	string(date)	Date when the payment was completed.

Statements

View currency level statements to know the transaction done in the past or View collection account statements to know the credits and fees deducted for every etailer payments in

View Statements

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/statements/{currencyCode} \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/statements/{currencyCode}', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/statements/{currencyCode}', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/statements/{currencyCode}

Get a Statement for an Account for a single currency. You can also provide a range of dates to restrict the results to a certain period.

Parameters

Name	In	Type	Required	Description
from	query	string(date)	false	Last date to include in the statement (in yyyy-mm-dd format per ISO8601).
to	query	string(date)	false	First date to include in the statement (in yyyy-mm-dd format per ISO8601).
page	query	number(int32)	false	For queries that return arrays of data. Including this optional query parameter causes the set of results to be paginated by this number of pages.
limit	query	number(int32)	false	For queries that return arrays of data. Adding this optional query parameter causes the set of results to be split into pages of this size. Default is 50.
customerId	path	string	true	Unique Customer Identifier
currencyCode	path	string	true	Three letter Currency Code (as specified by ISO4217).

Example responses

200 Response

{ 
   "transactions": [ 
     { 
       "datetime": "2019-01-22T00:01:15Z", 
       "type": "DR", 
       "description": "Selling Wallet has been deducted for Forex ticket execution and Instruction Number:0202000005923566-000000010", 
       "amount": 349 
     }, 
     { 
       "datetime": "2019-01-22T00:01:12Z", 
       "type": "DR", 
       "description": "Selling Wallet has been deducted for Forex ticket execution and Instruction Number:0202000005923566-000000009", 
       "amount": 349 
     }, 
     { 
       "datetime": "2019-01-17T06:11:22Z", 
       "type": "CR", 
       "description": "Credit Received via Bank Ref:200062", 
       "amount": 15000 
     } 
   ], 
   "meta_data": { 
     "total_records": "3", 
     "total_pages": "1" 
   } 
 } 
 

Responses

Status Code 200

OK

Name	Type	Description
transactions	[object]	Array of transactions.
» datetime	string(datetime)	Timestamp of the statement line.
» amount	number(float)	Amount being debited or credited.
» type	string	Whether a credit (CR) or debit (DR).
» description	string	Description of the line in the statement.
meta_data	object	Container for metadata.
» next_page	string(uri)	URL to next page of data. This field is omitted for the last page.
» previous_page	string(uri)	URL to the previous page of data. This field is omitted for the first page.
» total_pages	string(int32)	Number of pages of available data.
» total_records	string(int32)	Number of records of available data.

Collection Account Statements

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/collection-accounts/{accountNumber}/statements \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/collection-accounts/{accountNumber}/statements', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/collection-accounts/{accountNumber}/statements', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/customers/{customerId}/collection-accounts/{accountNumber}/statements

Get a Statement for an collection account. You can also provide a range of dates to restrict the results to a certain period.

Parameters

Name	In	Type	Required	Description
from	query	string(date)	false	Last date to include in the statement (in yyyy-mm-dd format per ISO8601).
to	query	string(date)	false	First date to include in the statement (in yyyy-mm-dd format per ISO8601).
page	query	number(int32)	false	For queries that return arrays of data. Including this optional query parameter causes the set of results to be paginated by this number of pages.
limit	query	number(int32)	false	For queries that return arrays of data. Adding this optional query parameter causes the set of results to be split into pages of this size. Default is 50.
customerId	path	string	true	Unique Customer Identifier
accountNumber	path	string	true	Collection account number assigned to the the customer.

Example responses

200 Response

{ 
   "transactions": [ 
     { 
       "amount": 23000, 
       "currency":"GBP", 
       "datetime": "2019-01-22T00:01:12Z", 
       "type": "CR", 
       "fee":23   
     }, 
     { 
       "amount": 45000, 
       "currency":"EUR", 
       "datetime": "2019-02-14T06:45:19Z", 
       "type": "CR", 
       "fee":45   
     }, 
     { 
       "amount": 1200, 
       "currency":"USD", 
       "datetime": "2019-02-21T18:08:06Z", 
       "type": "CR", 
       "fee":12   
     } 
   ], 
   "meta_data": { 
     "total_records": "3", 
     "total_pages": "1" 
   } 
 } 
 

Responses

Status Code 200

OK

Name	Type	Description
transactions	[object]	Array of transactions.
» amount	number(float)	Amount being debited or credited.
» currency	string	Three letter Currency Code (as specified by ISO4217).
» datetime	string(datetime)	Timestamp of the statement line.
» type	string	Whether a credit (CR) or debit (DR).
» fee	number(float)	Fee charged for the service.
meta_data	object	Container for metadata.
» next_page	string(uri)	URL to next page of data. This field is omitted for the last page.
» previous_page	string(uri)	URL to the previous page of data. This field is omitted for the first page.
» total_pages	string(int32)	Number of pages of available data.
» total_records	string(int32)	Number of records of available data.

References

You can use this resource to lookup reference data. Such as a list of the currencies you can buy and sell.

Currencies

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/references/currencies \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/references/currencies', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests -->
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/references/currencies', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/references/currencies

Get a list of supported currencies for your organisation.

Example responses

200 Response

{ 
     "settlement_currencies": [ 
         "AED", 
         "AUD", 
         "CAD", 
         "CHF", 
         "CZK", 
         "DKK", 
         "EUR", 
         "GBP", 
         "HKD", 
         "JPY", 
         "NOK", 
         "NZD", 
         "PLN", 
         "SAR", 
         "SEK", 
         "SGD", 
         "TRY", 
         "USD", 
         "ZAR" 
     ], 
     "quote_currencies": [ 
         "AED", 
         "AUD", 
         "BGN", 
         "CAD", 
         "CHF", 
         "CNY", 
         "CZK", 
         "DKK", 
         "EGP", 
         "EUR", 
         "GBP", 
         "HKD", 
         "HRK", 
         "HUF", 
         "ILS", 
         "INR", 
         "JPY", 
         "LTL", 
         "MAD", 
         "MXN", 
         "NOK", 
         "NZD", 
         "PHP", 
         "PLN", 
         "RON", 
         "SAR", 
         "SEK", 
         "SGD", 
         "THB", 
         "TRY", 
         "USD", 
         "ZAR" 
     ] 
 } 
 

Responses

Status Code 200

The response will contain two arrays. One for base currencies and one for quote currencies.

Name	Type	Description
settlement_currencies	[string]	array of settlement currencies.
quote_currencies	[string]	array of quote currencies.

Transaction Purposes

Code samples

# You can also use wget 
 curl -X GET https://sandbox.currenciesdirect.com/v1/references/transaction-purpose \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/references/transaction-purpose', 
   method: 'get', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.get('https://sandbox.currenciesdirect.com/v1/references/transaction-purpose', params={ 

 }, headers = headers) 

 print r.json() 

 

GET /v1/references/transaction-purpose

Get a list of transaction purposes.

Example responses

200 Response

[ 
     { 
         "country_code": "All", 
         "transaction_purposes": [ 
             "PENSION", 
             "STUDY_FEES", 
             "CAR_BOAT_PLANE", 
             "EMIGRATION", 
             "LAND", 
             "MORTGAGE", 
             "BILL_PAYMENTS", 
             "BUILDING_REPAIRS_PROPERTY_MAINTENANCE", 
             "PROPERTY_SALE", 
             "LIVING_FUNDS", 
             "OTHERS", 
             "BUSINESS_INVOICES", 
             "BUYING_PRODUCTS_SERVICES", 
             "CHARITABLE_DONATION", 
             "FREIGHT", 
             "INVESTMENT", 
             "PROPERTY_PURCHASE", 
             "SALARY", 
             "TRAVEL_EXPENSES", 
             "INHERITANCE", 
             "SENDING_TO_FAMILY", 
             "EXPORT_PROCEEDS", 
             "ECOMMERCE_SALE" 
         ] 
     } 
 ] 
 

Responses

Status Code 200

The response will contain an array of purposes.

Name	Type	Description
country_code	string	Country Code where these Purposes apply (as specified in ISO 3166-1 alpha-3).
transaction_purposes	[string]	Array of transaction purposes.

Webhooks

Callbacks which you can use to get updates on your Requests.

Subscribe for Updates

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/webhooks \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/webhooks', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/webhooks', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/webhooks

Presently Torfx send out status updates via email. Webhooks allow you to subscribe to Customer Status updates. You will then receive these updates sent to your API as a JSON object. This makes it easy to keep up-to-date with the statuses of Customers and Contacts.

Body parameter

{ 
   "event_type": "CUSTOMER STATUS", 
   "endpoint": "https://yourhostname.com/xyz/v1/notifications" 
 } 
 

Parameters

Name	In	Type	Required	Description
event_type	body	string	true	Event type of webhook subscription. Currently Customer Status is the only event which is permitted.
endpoint	body	string	true	This is the URI of your webservice, which we will call with the updates.

Example responses

200 Response

{ 
   "id": 1234567 
 } 
 

Responses

Status Code 200

Ok. You successfully subscribed to a feed.

Name	Type	Description
id	string(int32)	Unique subscription Identifier.

Status Updates

The statuses or both Customer and Contracts can change to Active or Inactive. For instance, when a Customer is first created it will have a status of "Inactive" until the required documents have been uploaded and checked. A change of status could also be the result of a modification to existing data. For instance, a Contact could upload a new Proof of Identity document, which would cause their status to become "Inactive" until the document has been reviewed.

Callback Request Body

Body parameter - Active Account

{ 
   "customer_id": "0201000005926289", 
   "status": "active", 
   "unique_identifier": "2df806d1-028f-405e-8a53-332b7b039d7b", 
   "contacts": [ 
     { 
       "contact_id": "4349165556", 
       "first_name": "Saurabh", 
       "middle_name": "Rajendra", 
       "last_name": "Sarcar", 
       "status": "active" 
     } 
   ] 
 } 
 

Body parameter - In-Active Account

{ 
   "customer_id": "0201000005926289", 
   "status": "inactive", 
   "unique_identifier": "a8509765-a76d-4c20-9ebf-c2b0f08ab187", 
   "reason_for_inactive": "Identity document", 
   "documents_required": [ 
     { 
       "document_type": "POI", 
       "uri": "/v1/customers/0201000005926289/contacts/4349165556/documents/0011q00000DA0MfAAL-0011q00000ab0xdf46" 
     } 
   ], 
   "contacts": [ 
     { 
       "contact_id": "4349165556", 
       "first_name": "Saurabh", 
       "middle_name": "Rajendra", 
       "last_name": "Sarcar", 
       "status": "active", 
       "documents_required": [ 
         { 
           "document_type": "POI", 
           "uri": "/v1/customers/0201000005926289/contacts/4349165556/documents/0011q00000DA0MfAAL-0011q00000ab0xdf46" 
         } 
       ], 
     } 
   ] 
 } 
 

Once you have subscribed to the "Customer Status" data-feed, Torfx will send a callback POST request to your designated API endpoint when there is an update to one of your Customer's Statuses. These POST requests will have a JSON object in the data payload. The JSON object will have the following parameters:

Parameters

Name	In	Type	Required	Description
customer_type	body	string	true	Registering customer type.
status	body	string	true	Whether the customer is active or inactive.
unique_identifier	body	string	false	When the customer is active, this is the Unique ID for this Customer provided by the (Add a Customer record)[#add-a-customer-record] operation.
reason_for_inactive	body	string	false	When the customer is inactive this will be the reason for it being inactive.
documents_required	body	object	false	When there are outstanding documents for a Customer, this is an array of document objects.
» document_type	body	string	false	Type of document required. Either POI or POA; for Proof-of-Identity or Proof-of-Address.
» uri	body	string	false	URI to call when sending the document back to Torfx.
contacts	body	object	true	Object containing an array of contacts.
» contact_id	body	string	true	Unique ID for this contact.
» first_name	body	string	true	First name of this contact person.
» middle_name	body	string	true	Middle name of this contact person.
» last_name	body	string	true	Last name of this contact person.
» status	body	string	true	Whether the Contact is active or inactive.
» documents_required	body	object	false	When there are outstanding documents for a Contact, this is an array of document objects.
»» document_type	body	string	false	Type of document required. Either POI or POA; for Proof-of-Identity or Proof-of-Address.
»» uri	body	string	false	URI to call when sending the document back to Torfx.

Schemas

generalError

{ 
   "code": "string", 
   "description": "string" 
 } 

 

Properties

Name	Type	Description
code	string	Generated code specific to this error.
description	string	Details of the error. Refer to Error Codes for guidance resolving issues.

Third-Party Service Provider

Abstract

Open Banking is the name of a secure set of technologies and standards which allow customers to give companies other than their payment service provider permission to securely access their accounts. This means customers can, if they choose, easily use financial services from different types of regulated companies without the need to share credentials with any third parties. They may, for example, choose to aggregate a view of all of their accounts through one provider or allow a company to analyse their account data to offer automated tax returns, budgeting advice or cheaper overdrafts.

Note: Every company using Open Banking to deliver their services has to be authorised by the Financial Conduct Authority (FCA) or another European Regulator.

Introduction

With the increasing use of distributed web services and cloud computing, third-party applications can benefit from access to these server-hosted resources.

In the traditional client-server authentication model, the client requests an access-restricted resource (protected resource) on the server by authenticating with the server using the end user’s credentials. In order to provide third-party applications access to restricted resources, the end user shares their credentials with the third party. This creates several problems and limitations:

• Third-party applications must store the resource owner’s credentials for future use
• Servers are required to support password authentication, despite the security weaknesses inherent in passwords.
• Third-party applications gain overly broad access to the resource owner’s protected resources, leaving end users without any ability to restrict duration or access to a limited subset of resources.
• End users cannot revoke access to an individual third party without revoking access to all third parties, and must do so by changing the third party’s password.
• Compromise of any third-party application results in compromise of the end-user’s password and all of the data protected by that password.

Open Banking provides a standard method for resource owners (an end-user) to delegate access of protected financial data to a third-party client without sharing their credentials. This client (acting on behalf of the user) can then request access to resources controlled by the resource owner, but hosted on our servers using different credentials than those of the resource owner. This is an access token – a string denoting a specific scope, lifetime, and other access attributes

Our servers will verify the resource owner authorization, and the identity of the client making the request.

Terminology

Term	Definition
Third-Party Service Provider	The Third Party application that wants to access the protected information.
Resource server	API or system which holds the data. An HTTP server capable of accepting authenticated requests.
Authorization server	The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
Protected resource	An access-restricted resource that can be obtained from the server using an OAuth-authenticated request.
Resource owner	End user who owns the data that the application wants to get to.
Credentials	Credentials are a pair of a unique identifier and a matching shared secret. OAuth defines three classes of credentials: client, temporary, and token, used to identify and authenticate the client making the request, the authorization request, and the access grant, respectively.
Access token	A unique identifier issued by the server and used by the client to associate authenticated requests with the resource owner whose authorization is requested or has been

Example

Jane, an end-user (resource owner) can grant an accountancy service (client) access to her private statements stored at an account information sharing service (server), without sharing her username and password with the account information service. Instead, she authenticates directly with the account information service which issues the accountancy service delegation-specific credentials.

Jane wants to do her tax return and has a lot of information stored on www.torfx.com (server). She would like to use the accountancy.example.com website (client) to calculate the tax on her currency transactions. Typically, Jane signs into www.torfx.com using her username and password.

However, Jane does not wish to share her username and password with the accountancy.example.com website, which needs her statements’ data in order to do the calculations. In order to provide its users with better service, accountancy.example.com has signed up for a set of www.torfx.com client credentials ahead of time:

• Client ID: e8b0186cfbfe
• Client Shared-Secret: e44c7261-3c6c-44aa-9189-54ecd5f0b1c8

The complete process involves the following steps:

1. Jane logs in to her accountancy.example.com account and asks to collate her tax return. She specifies that she wants to include data from Torfx. The client responds with a request to link to our service.

2. Before accountancy.example.com can ask Jane to grant it access to her Torfx account, it must first request a one time token to identify the delegation request. To do so, the client sends the following HTTPS request to the server:

   POST /token HTTP/1.1

   Host: www.api.currenciesdirect.com

   grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope={{scope}}&callback_url="http%3A%2F%2Faccountancy.example.com%2Fready"

3. The Authorisation Server replies to the client with a redirect_url to the login page (on our consent server) and the one_time_token in the body of the HTTP response:

   HTTP/1.1 200 OK

   Content-Type: application/x-www-form-urlencoded

   redirect_url="https%3A%2F%2Fwww.currenciesdirect.com%2Fauthorize%3Fone_time_token%3Dhh5s93j4hdidpola"

4. The Third-Party Service Provider sends a redirect response to the Browser, with the one_time_token as a parameter

5. The Browser makes a request for the Consent Server login page, over TLS/HTTPS, and passes the one_time_token.

6. To obtain Jane’s approval for accessing her account information the Consent server presents the login page to the Browser, and sets a session cookie. For instance:

   https://online.torfx.com/CustomerPortal/login.htm?one_time_token=hh5s93j4hdidpola

   The Browser renders the login page and requests Jane sign in using her username and password.

7. Jane enters her login credentials for Torfx, and clicks enter.

8. The Browser submits the login request to the Consent Server, and includes the session cookie.

9. If successful, the Consent Server sends a consent page which asks Jane to approve granting accountancy.example.com access to her account information. The Browser renders the Consent page and requests Jane select which the scope of her consent.

10. Jane approves the request

11. The Browser sends the consent as a request to the Consent Server and includes the session cookie.

12. The Consent server sends a redirect to the browser together with the consent_id.

13. The Browser redirects to the Third-Party Service Provider’s callback_url, including the consent_id as a parameter. E.g:

    http://accountancy.example.com/ready?one_time_token=hh5s93j4hdidpola&consent_id=hfdp7dh39dks9884

14. The callback request informs the client that Jane completed the authorization process. The Third-Party Service Provider extracts the consent_id a.

15. The Third-Party Service Provider makes a POST request to the Authorisation Server to get an API access token using its client credentials:

    POST /token HTTP/1.1 Host: www.api.currenciesdirect.com Authorization: Basic ZThiMDE4NmNmYmZlOmU0NGM3MjYxLTNjNmMtNDRhYS05MTg5LTU0ZWNkNWYwYjFjOA==, one_time_token="hh5s93j4hdidpola", consent_id="hfdp7dh39dks9884"

16. The Authorisation server validates the request and replies with an API access token in the body of the HTTP response:

    HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded access_token=a815f20b-2132-48cb-9c81-d14a6835722f

    The Authorisation returns the access_token.

17. The Third-Party Service Provider can now use the access_token to make a request to the protected resource server.

    GET customers/0202000005924291/statements/USD?page=1&limit=100 HTTP/1.1 Host: api.currenciesdirect.com Authorization: Basic ZThiMDE4NmNmYmZlOmU0NGM3MjYxLTNjNmMtNDRhYS05MTg5LTU0ZWNkNWYwYjFjOA==, access_token="a815f20b-2132-48cb-9c81-d14a6835722f"

18. The Resource Server sends a request to the Authorisation Server to check the access_token is still valid and has the correct scope to view the requested information.

19. The Authorisation Server responds to the Resource Server detailing whether the access_token and scope are valid for the Third-Party Service Provider’s request.

20. The resource Server responds with the requested information. accountancy.example.com is able to continue accessing Jane’s information using the same set of token credentials for the duration of Jane’s authorization, or until Jane revokes access.

Authenticate a TSP

Request an Access Token to Authenticate. This is a modified version of the Token resource used for other APIs.

Get an OAuth Access Token

Code samples

# You can also use wget
curl -X POST https://sandbox.currenciesdirect.com/auth/oauth/v2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json'

var headers = {
  'Content-Type':'application/x-www-form-urlencoded',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/auth/oauth/v2/token',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

import requests
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

r = requests.post('https://sandbox.currenciesdirect.com/auth/oauth/v2/token', params={

}, headers = headers)

print r.json()

POST /auth/oauth/v2/token

To access any of the other API resources you will first need to obtain a token. Make a POST request to this Resource. Figure: Authentication If you provided all the Request Body parameters, you should receive an Access Token in the response body.

Body parameter

grant_type: client_credentials
client_id: l7323441a8e72a4dd48a70b0e7d7b42437
client_secret: aeade0da50175619b6f269928a088abc
scope: external

Parameters

Name	In	Type	Required	Description
grant_type	body	any	true	The type of authorisation code being requested. For our purposes it will be an Access Token request, so this will be client_credentials.
client_id	body	any	true	The client_id provided when you requested access to the API from Torfx.
client_secret	body	any	true	The client_secret associated with your client_id.
scope	body	any	true	Should be set to the external scope.

Example responses

200 Response

{
  "access_token": "dadadb2c-1ae2-48a2-a5dc-506e0432067b",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "external"
}

Responses

Status Code 200

Ok. The response body will contain the token you need to make requests to the other resources.

Name	Type	Description
access_token	string(guid)	This GUID is a token that you should use to make the Bearer {access_token} Authorisation HTTP header required to call other resources.
token_type	string	Bearer
expires_in	number(int32)	Expiry time in seconds.
scope	string	Scope of access. This should be external.

Scope of TSP Access Tokens

There are two types of Third-Party Service Provider.

• Account Information Service Providers (AISP) who provide account information services as an online service to provide consolidated information on one or more payment accounts held by a payment service user with one or more payment service provider(s).
• Payment Initiation Services Provider (PISP) who carries out regulated payment services.

APIs

Consent invitation

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/tsp/invitation \ 
   -H 'Content-Type: application/json' \ 
   -H 'Accept: application/json' \ 
   -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
    'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/tsp/invitation', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/tsp/invitation', params={ 

 }, headers = headers) 

 print r.json() 

 

POST /v1/tsp/invitation

Third party service provider (TSP) will call this api only in case when they don't have valid consent from the resource owner. TSP will provide redirect url in request body which will be used to pass resource owner's consent to TSP.

Body parameter

{ 
  "redirect_uri":"/v1/tsp/invitation" 
 } 
 

Parameters

Name	In	Type	Required	Description
redirect_uri	body	string	true	Resource owner's consent will be passed to this endpoint.

Example responses

200 Response

{ 
     "invitation_id": "2fed3391-f03d-433f-be29-41441096a0d8", 
     "redirect_url": "http://uat.currenciesdirect.com/CustomerPortal/landingPage.htm?invitationId=2fed3391-f03d-433f-be29-41441096a0d8" 
 } 
 

Responses

Name	Type	Description
invitation_id	string	Unique id to identify consent invitation.
redirect_url	string	Login page url which will be presented to resource owner to login.

Initiate Payment Instructions

Code samples

# You can also use wget 
 curl -X POST https://sandbox.currenciesdirect.com/v1/tsp/payments \ 
    -H 'Content-Type: application/json' \ 
    -H 'Accept: application/json' \ 
    -H 'Authorization: Bearer {access-token}' 

 

var headers = { 
   'Content-Type':'application/json', 
   'Accept':'application/json', 
   'Authorization':'Bearer {access-token}' 

 }; 

 $.ajax({ 
   url: 'https://sandbox.currenciesdirect.com/v1/tsp/payments', 
   method: 'post', 

   headers: headers, 
   success: function(data) { 
     console.log(JSON.stringify(data)); 
   } 
 }) 

 

import requests 
 headers = { 
   'Content-Type': 'application/json', 
   'Accept': 'application/json', 
   'Authorization': 'Bearer {access-token}' 
 } 

 r = requests.post('https://sandbox.currenciesdirect.com/v1/tsp/payments', params={ 

 }, headers = headers) 

 print r.json() 

 

TSP can initiate a transfer by calling Initiate Payment instruction with details of the Recipient's account and payment information, if all information is correct and valid then API will mark the request with a unique id and will redirect TSP to Torfx online portal login page.

To make a transfer, you'll need to add details of the Recipient's account. There are a number of parameters which you can use to specify this account, but generally, Recipient data objects consist of:

General Information

• Recipient personal details
• Legal structure (Individual/ Corporation)
• Contact information
• Country Code (ISO3166-1 alpha-3)

Recipient Bank Account Details

Recipient Bank Account Details vary for different countries. For example, the IBAN number is sufficient for most European and Nordic countries but you need Account Number, Routing Code Type, Routing Code Value and Bank Country Code to send money to the US.

In total there are four different variations of Recipient Bank Account Details possible. These are:

• IBAN
• Account Number, Swift Code
• Account Number, Swift Code, Routing Code Type and Routing Code Value
• Account Number, Routing Code Type, Routing Code Value and Bank Country Code

You will also need to provide the code for the currency of the bank account in ISO 4217 three letter format (e.g. GBP for UK pound).

Address Data

• State (US, Canada, Brazil)
• City
• Address line
• Postcode
• Request
  

POST /v1/tsp/payments

This api will initiate customer payment ,for payment initiation customer need to provide payment information.

Body parameter

{  
 "recipient_details":{  
     "name":"David shlok",  
     "type":"Individual",  
     "country_code":"GBR",  
     "address":{  
         "address_line":"Bissonnet Street, Texas City",  
         "city":"London",  
         "state":"London",  
         "post_code":"TW3 4DF"  
         },  
     "recipient_bank_details":{  


 "account_number": "21135117",  
 "routing_code_value": "401517",  
 "routing_code_type": "SORT",  
 "bank_country_code": "GBR",  
 "currency": "GBP"  
         }  
     },  
  "payment_reference": "abc123",  
  "purpose_of_transaction": "EMIGRATION",  
  "amount": 50,  
  "redirect_uri":"/TSP/Payment/PaymentConfirmation",  
  "client_reference_id": "ABCDEFGHIJKLMNO"  
 } 

 

Parameters

Name	In	Type	Required	Description
name	body	string	true	Name of the Recipient.
type	body	string	true	Organisational type of a Recipient; whether an Individual or Corporate.
client_reference_id	body	string	false	A Reference Id that you can assign to this Recipient, for your records.
country_code	body	string	true	Three letter Country Code of the Recipient (as specified in ISO 3166-1 alpha-3).
address	body	object	false	Container for address details.
» address_line	body	string	true	First line of the postal address of the Recipient.
» city	body	string	true	Recipient's city, town, or village.
» state	body	string	true	Recipient's state, country, province or a prefecture.
» post_code	body	string	true	Recipient's postal code, zip code or pin code.
recipient_bank_details	body	object	true	Bank details of the Recipient.
» allOf
»» currency	body	string	true	Three letter Currency Code (as specified by ISO4217).
» and
»» oneOf
»»» iban	body	string	true	Recipient IBAN as per their bank records.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» swift_code	body	string	true	Swift Code of the Recipient's bank account.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» swift_code	body	string	true	Swift Code of the Recipient's bank account.
»»» routing_code_type	body	string	true	Recipient routing code type:
»»» routing_code_value	body	string	true	Routing Code of the Recipient's bank account.
»» xor
»»» account_number	body	string	true	Recipient's bank account number as per their statement.
»»» routing_code_type	body	string	true	Recipient routing code type:
»»» routing_code_value	body	string	true	Routing Code of the Recipient's bank account.
»»» bank_country_code	body	string	true	Recipient bank country code
payment_reference	path	string	true	Customer can send their payment reference(any related info).
redirect_uri	body	string	true	Redirect url for the payment initiate .

Example responses

200 Response

{ 
     "invitation_id": "5aecbcfc-e56f-40ae-81b7-7d98c90076c7", 
     "redirect_url": "https://test1.currenciesdirect.com/CustomerPortal/landingPage.htm?invitationId=5aecbcfc-e56f-40ae-81b7-7d98c90076c7" 
 } 
 

Responses

Name	Type	Description
invitation_id	string	Unique consent id to identify this consent request in process.
redirect_url	string	Redirect Url with consent id which can be redirect to landing page for next payment process

Error Codes

The HTTP status and error code will help you determine the cause of the issue.

HTTP Status	Error Code	Description
xxx	000	Success
xxx	999	Error
400	1001	Json fields depth is not matching with expected value
400	1002	$.name: does not match the pattern
400	1002	$.type: does not match the pattern
400	1003	Required fields of payee bank detail not provided
xxx	5998	Request message is not valid
xxx	5901	Mandatory fields Missing
xxx	5902	Duplicate Payee, Fields that are duplicate [Payee Account ID, Nickname, Payment Code, Organisation]
xxx	5904	Not able to create payee
xxx	5907	Currency not available.
xxx	5908	Organization not available.
xxx	5909	Payment method not available.
xxx	5910	User not available.
xxx	5911	Not able to Save data
xxx	5906	Country not available.
xxx	5997	Records does not exists
xxx	5996	User not authorized
xxx	5905	Not able to update payee
xxx	5906	Country not available.
xxx	5908	Organization not available.
xxx	5909	Payment method not available.
xxx	5910	User not available.
xxx	5911	Not able to Save data
xxx	5912	LookUp type not available

All errors follow the GeneralError schema.

Glossary

Term	Definition
Recipient	is a person or institution who is the ultimate beneficiary of a payment. The Recipient Resource enables you to create, update and delete Recipient data.
Resource	Resources are specialised web services that are accessible at an Endpoint (or URL) using HTTP requests. Their purpose is to expose a JSON data object that represents some Business Entity (such as Contact data) and allow at least one Operation on that data object. We support four HTTP Methods: Get, Post, Put and Delete; for the Operations Create, Read, Update and Delete respectively.
Operation	An action defined by a HTTP Verb (e.g. POST) that is intended to retrieve or make a change on a Resource.