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 Currencies Direct API documentation. Currencies Direct 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 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 Currencies Direct's API resources follow modern RESTful standards which will speed up the learning curve for anyone familiar with these types of APIs.

The Currencies Direct 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. Email your Account Manager requesting credentials to access 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 Currencies Direct 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, Currencies Direct 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	Currencies Direct 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

Currencies Direct 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

A valid token is required to access the API calls. It is not possible to access APIs without a valid token.

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 Currencies Direct.
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.

Customers

The customer resource allows you to integrate all the available customer resources from Currencies Direct. These resources are designed for you to create, update, and delete customer’s 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": "John",
      "last_name": "Lopez",
      "date_of_birth": "1980-02-14",
      "employment_status": "Full-time",
      "industry": "Technology and Software",
      "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": "321",
        "street_number": "468",
        "street": "Bissonnet Plaza, El Campo",
        "street_type": "Plaza",
        "post_code": "77023",
        "city": "Houston",
        "civic_number": "741",
        "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"
    ],
    "etv":"5000-10000",
    "ccy_pair":"GBPUSD"
  }
}

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
» employment_status	body	string	false	Employment status of the contact
» industry	body	string	false	Employment industry 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
»»» national_id	body	object	false	Container for National Id details.
»»»» id	body	string	true	National id number
»»»» type	body	string	true	National id type
»» xor
»»» driving_license	body	object	false	Container for Driving License details.
»»»» number	body	string	true	Driving licence number
»»»» card_number	body	string	false	Driving license card number
»»»» state_code	body	string	false	Driving license state code
»»»» version	body	string	false	Driving license version number
»»»» expiry_date	body	string	true	Driving license expiry date
»»»» issuing_country	body	string	true	Driving license 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.
» etv	body	[string]	true	Estimated transaction value
»				Possible values:
»				Under 2,000
»				2,000 - 5,000
»				2,000 - 10,000
»				5,000 - 10,000
»				10,000 - 25,000
»				25,000 - 50,000
»				50,000 - 100,000
»				100,000 - 250,000
»				over 250,000
» ccy_pair	body	[string]	true	default currency pair, selling currency code followed by buying currency code

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}/details \
  -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}/details',
  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}/details', params={

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/details

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",      
      "employment_status": "Full-time",
      "industry": "Technology and Software",
      "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 Currencies Direct.
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
» employment_status	string	Employment status of the contact
» industry	string	Employment industry 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 Currencies Direct.
» 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

Upload documents

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}/documents/{accountSFID}-{contactSFID} \
  -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}/contacts/{contactId}/documents/{accountSFID}-{contactSFID}',
  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}/contacts/{contactId}/documents/{accountSFID}-{contactSFID}', params={

}, headers = headers)

print r.json()

POST v1/customers/{customerId}/contacts/{contactId}/documents/{accountSFID}-{contactSFID}

Upload Customer's POI/POA documents.

Parameters

Name	In	Type	Required	Description
document_type	body	string	true	type of document(POI/POA)
file_type	body	string	true	type of file(pdf/jpeg/jpg/png)
base64_encoded_stream	body	string	true	file in base 64 encoded string
comments	body	string	false	client's comment

Example responses

200 Response

{
  "document_type": "POI",
  "file_type": "PDF",
  "base64_encoded_stream": "iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAMAAAAJbSJIAAAA0lBMVEUsREzlcgD////pcwAoQ03tdABLTEAbQk4oQUmnYC0qQkofO0SQmp4kPkcTND4lQ01kdHoALThuen/19fbHzM5XZ203TVXb3+Du8PFAVVzo6uuyubwVQU+rsrQAKjVIXGLbcADRbRGXoaTV2dpwUznYbwiBWDK/aBQ3Rkm8wsSIlJgxSVDJaxN4VjNVTUC0ZR1ESUSXXSliUDuyYyg3SER7iI2mYSOTXC2GWTCNWy0hRElzVDhSTEFBSEmeXya8Zx1gT0CGVzdQS0aQXCpuUj0ACh2saxM1AAAQYUlEQVR4nO1dC3eiuhZGwMIBARVFRawotfXV+pjSh22105n7///S3TsJKGpnaqtj7OJb60wrhZgvO/uZkCMIKVKkSJEiRYoUKVKkSJEiRYoUKVKkSJEixX4hW5YSwbLkY3dnr5AtxfOU8fTy/j+KyeX0DC99D57AbnxxP/Kz2ay0BHzyF5OnMbA8dge/BsvrTifDTEaSMpuAi35r8rvrnS5JRbiZtzLbyK3QzLTuXuHOE4SsCNdXW2W3Kcvh40A5NZWUve69n5VWaVDtY8BPKySzmfnYOymOSneeSdDLdq5Gk+uLM4rp9eTHVUdKjEDmbuwdu9sfhiU8dKQlu0xrdHnzIhAvSIGeUXh5vh6taqnkT7onYnOU16tYOlKmM5+Ctdzi+YCoJ7xOVkhmWxen4CEtZTlBJWk0Vf7o10GYr3eZaEDg/hn3YlSeO9lIJP797AO+zvJmD62YY2bKt+eQrYdIgFLnvvtRF2B1L1ux3OcCxzNVFu4ifv78ZRfzr3TvI+MkLW65nany7Crq5dXNju5N9sYj5iKlzphTitYtE4OUefhErCl7v/3o+RsulVG5YbokDc8+10GrO4q08YlDitZrJMH5px23LDxSQyVxSNEaRxJ8/EoQrVxE7v+CM4ryLDKF11+LLpUbn0mRL3MjC0PaL//LNiKeDD5XFK0frFevX++V9UYpSsMuP65feWBT9GYfw26NO1Sj77hRReuV+fk9WQdrzCzqJS8UmZWRHvaVwipTNmScqKJCg9F9TirlmqkiFwytKe3NYp85gTUnOVj2kYd52qWOYr/+S2at+uPj21PvkY729X5H2zojzUqjowtRHvt0ju67UOZNJJpJHVuIHst5998RCx3/8RnKz9Ss3++/1mldYJ31x7FnqTcnc6l1iADLuh7682NHbvJMOoSZYbA879gSFJR7wnDYPXZHDoZui4jwkovQ4xCwpsRp+cfux+GgkLRQmh9dWw4FmSZy0rFd1uFgPWVJAnA66367gsYzEhfx/2FAM1//+ftO0hsSsbW+rwiVn9/ckkZq+PvbunvBo2r49m3VUJhlvnlMKp8dJrnnB9YTUcPJ9zU0yqNEUsPva2gUUirK7mEthlfQUnf2+4bdgkUW3bMvx+7H4WCRrSX+93UWKcNvgJTh6YMyzGwwlL+GY1B5B8wfrnsLq3v2FXCyrk3AGK7VMKzH7NdwdyQ6W0Ar+tmLxKDLN9EO4c+Co0DXuiS5xYOVvPhVhhxVRegOBekukR9aF19m+IsbhvIt6dAiOUtfWD8/A/IkT8mKR6i0XhKmxloQyS7+2x10EaTDkYP1qENMjjnNi6WRp+wKtjXhBz8ijFLg5OKhfEsVcec9fHK3s8U2HxfWU4aKK3GVSnb3fTDKA12L5KmwxRbXOsnNBJT3+uT9e2NUhJwVtjy6M2ut6K20iGiHu3WV7cvxj733IglmVZIeUbCuP7EX06L7LTkTYbT45M/Wrl/tvE1KtuhqcueFKxEChqRfT8lpar1Gm0M/3F2FvkqS5WZTcAQ2Ta/W+qVM6L7Cq49SjB5YcOQpKOQxDbTO1nvGdtuPPrapVplHr1jwNkejmulGHMIU9GMUZUYwk+Enb1qCbRnKrK8hepeM4vCv70BZ1oi2sW6Tyd+OL1SvtS2ugev30buEF39+EdF7Zq/IZDfakK2L69ujmx7m/DLTdVGxreg4hV/ef9XLmk0yEcH1CS2/DCGhOn6YSnbybotgrPv4hdmH7RxlRXiKX43d1FiinlLr6MlUFMFsejLvMU7bO/fjdZWSLat7OYxfb77bGAP2Is7Rd0HHZdPMbKMn3oUfv2efGV3eeh4eq4BQPG/2NPKjgge+VbvRrkf18/gyjDyDtNi0CVZ3tDxcQcr6o8nPC8TP+1EnuzwUIzs82yTIgoAD7T7eDQq1KdLDZl9k62l5QAYp3kQ/V4/DuBc2rQl780la/AsGfwNkdpnt9hSgvMxXOW5A8u+et0gpes1Sej66KUVYv2lvWtsSA1kZT7YfokTUE/htsyS0nsVPMsWyV3AZ253C7HqUya6xxON4rh6628MBj6Ya0hU3JQ12lgLkBttNu6UIF3fkyJ3opC//6sd113onFPBYoMqBp4hgvbH3Wt+PtIHky9vvy8fHu8fHh4vn8eD9Q13id255emFd+Z35G0Vy5I7FTtz7U0StPLC2+Np7rFyzBGH01QOtvAnzkvy850zh/WK+rvWlU4JkZmS2pCtHR5THSq0vHDqgjFkMyGFBA/Ml1jn/+rMnYyjT6HCNBV91U4YoJZSkO+szErCUX+8mi5zAixaApc50Z4Mje2fDbGxk+CSIZ6/E+dLobDeOSnceRz2P3BmZJZSbKKmV/Mkfqhcbz3XjU/qkDk+OfhMrByFlO48fO85MVrqXywPbrt64JojqdBmf2Jb157feXwqCsuXN7ltxtp+dnMChtMpSjNDjq5/jracmEgC92+tFnHbA3VuyfQ4hWxetJUfJv7p87eKpyKs0ZTw9Wbj5ufCXWZXUudyS7fMJa3mCHhFNprX4NX0bd4WZ4nmeMpt1X96mj4vW6hmukO2/cK6BCXhrmT3khJI/XCx+IBaLYWctJcZs/7QOoQWLM7vvZNeqF8m9QStCRpN0WvwQsmJNR/46yQ3AHF48CdwGMX+BZY0vF50/HAgtSZ2rh7dPRbG8AEzm+Pd86GfWp6ZEziufX4yVUxXfEugXutOf81HLj7fJ+q3F/Of09rucrC/Q/y+Ch47iFjEjv34fdgnwtlk9RYoUKVKk+BQ0QwcY6sG/Rzv0N2yHajrFfrudC2umcdAvMgY1/aBf8A70Zr0qElRLef2Ao6yWXTs87Bhug6a3xRX05MNR1PuiWPrnQtSEHvAKwlrBrIUl+NVVD0ZRLdti+M8Z6kCwWjR1MDKqbuZdUSwebh6pqvDPJylOHHup/nqtXnI0wVixOLrJLCzYW5Ndh7EwdXrNhN+MpdTJBXNVmfFeuIV+ME1t9aqafOwQtlzTbVHMr0wcDftg5CuxIPVc0CRfbAzyjaCUh+uq0WyXgjY8pQ/CehA08rFkdCfsBUEvjMcM7s2VgqBdVsktjRLRAU3Hq6V2jQ2FqhahnXpY27+dQxHWzY2rJbHC+qzVqmIDu2sWXTREcLMx6BGbdA7XmA2ulCkjM8cu2LkCbYndC5peNkEPRbGvowDr7GqDiNGoVSI7N9g3RT0Q7fLG3DCAIUto1SZlaLaJM+mVVbVpY4dLfZ0Y4VKvHohsHphIp1IqYX97OG46mBbRLvVKSDyno6XJ6YIqwGC5vV4PrgZg6rQBfC7VeyV7/6ZWU6FHm20iQzXB0IDRF9sDA4bchP6XmiqEQCE83ETdDG3QZRUmNAxCCOqqMoOlOtDnhqODzuJgFBhDGFaxASpJBAwjgRMpxHacdqWxZ0uk1thg/40hWtwcsRJGEXgZ0A9NropVBzukmcC1rguFqmjn8SbNhJsCXTPIUyq5pRjUTcoQR6ZB2lJNcE95A0RfJQqo6sa+TS0qRvsDMsR5VBGIiugNkfo0lFifPQtSqYIQQbhU/QQTxKSh4ONZZ4AgKUMtEF2HNm/AhboJDO3Bgdzkhxk61UjWZh0kh1xh/KumToFCLOr5FcowDoIJ/5RXhUIYmvCdjXP24HlFdAs4S90izNIDhBpq82OzFBk2lgyJwSvYotvPUfTbOB3zy2gBjZAGgnQTtpEyhBnciB+EaXquDTCWsnvhwNw7R2JpNqf+hxiei0m0NxiqlWhqJxj21x48F9RBg3iZatvZe8iD3iK/0eqHGdpLgEv8IMMw8ZyNc0gzm330FaLb3HdYgz3pFRKXtI/OUlcM/leIYarGlllqO1tnaf585UH6Jx2cjosWeM8MSdRWXGlVhZgFGbqsa9ip7QzRAi5HHMdljWHC2pKomzKEiGFF9zX2H/alAN6ltnchYuTdjMNBvVaCXmJQxWhjL3NbGaJbqxfi59RNhgZ4WzfSLL3ZVKm3gPGzWZQHonMwMKBBK4krNiOsL1OEcbP7EIdoGsQpGHz2dexrxQHamu7Ahaa6jaGgQ3AToj+HKCZnN/QNhhr6jNIA2zH0frVqGJRhmcRCJDKoBW7ZaFYqTRoowHDX9m9OiakOcjVNq4UYYQbQyQL84oaGQcIvmFJbGWJ/xUbNgC5DE70tDDWM8LAdowl3VHWDRW0NvIrxS7+KES1MWxusqG707W0x5NcpmokqRrsA3VcdEuwTEx5AvrOVIY2rxWpAInFZ22QIUgxIO8xMsrhUKJDUokKSlT7EpUXaDn4sHyRDhrTXpfTcBkvsVKNNL7ltFefhoBrFPiAAN47EmB8TK32YZRg+RJ4H1Rsrh5rer7B2wIJhWkIqUXo+oElWr6mTdno2S7EOFbzpTjnM9YtlJ866QQPzYS7MO9QIqeU+E5zm9JfGQNNr+X67WKZRpR4W4z8M+nl6lz4oh+2oHTXfZzZFKxfhC5vs+7CdENrRDlfj0FQDC8KrWq4ZoBlxqKjG5lbTV61d4rmVzECL6has6egOPfmg8M7HFClSpPhWMBlWq76CvvMS1bFW1T6Aeo+g3g6dmNag4e64gqQ6DqeeQF/Jx+1e3mTeH4KYnSq3EMtU954V7QeYO1WCIKjYJKpqYARHkuLSTv3FiHWzksAFkGH+HNSwMCB5R4loo9EMd1tk5JwhTRcgAc9Xo/JnvBxFgi1W+tT1hDWiWwPoFcIQK4/8zdQlQ/wAs5MkP0a+TWscqtkM220MxA0DNwKEzjJ6NZ1irt0uOiarb7RDwP4T+K8iwVDAYlpV1bRBBWv4uGSEaytiyRSMYpQjsSDccNo0r6o2HIMwpFnWsYi8iyRDAStFfV1zXGQFOT5JIe2+jkk7ZLAupStEy2V2hWS+ZTVmWOJOGdcYYk9LpuZUkIimYvEvXyjoWCRwywXzvBbQ1Ui6XFYuFAqY6VYMfK58Dtgsrx8bawwFoypWC4whFipKGAVgbl8h6aCql0gdogA/GgW8Yphtu26chC2lKFRwmYEyxHpvE/9m1uP+Y6mppyPlErM5mlETtBNiaJaWDAtVsUJmXcEWgwIYIAAuCLq1FcpCXCs+EYarMixQewMMcEXXocC13rIRrEV1p8MQl33dwhrD2FBGKAuuGCRsyukwxBXunrmFYdVdolIbVE+WIe61CI01hrgXoO3UYkCeFKytqp0MQx03KWCJP8FQMHH5XluCLIUkatcnwlAzsYgPnzYY4lpSHLyadBGqdM4uGAWTe4Y6ugFDN3KYIWLEssaQrFTRLMIw+xWIrtHkNgoklzTz1RLx+Lh/Q+Uu8CYMQ9SxZp6sY5D9X+sMicuv5FXTVMskcCUroWIdNxM1G7boGiTqqZl6s8mdIMkuJzSQVRZjkxXbdYaaGu32suk2LtBYeMAOggB/5EG8AUbmQdXlLn1ardO4bYEuOmBu0SMxDWOIK0w2K+a0aS0H15JZOoGrS2qN/t11uKu56dHGl6JViLNbI+w1Vfx3KRHdLDZ6vUbRjHddmoNcvdfLObQcoOr9Xq8ecpjkC2zvUrJAYZBuG+Zqf3F7rb6qZlpyjyx+4k4LU6RIkSJFihQpUqRIkSJFihQpUqRIkSLFCeD/byR9nN6tZWEAAAAASUVORK5CYII=",
  "comments": "tesing"
}

Responses

Name	Type	Description
document_id	number	Document ID retuned from the file server

ERP Connections

This API will enable our customers to sync both bank feed from our side and invoices / payments from their side, provided we have an integration with customer's erp system.

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/erp-connections \
  -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}/erp-connections',
  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}/erp-connections', params={

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/erp-connections

Get a list of account numbers in ERP system against currency wallets of the customer.

Example responses

200 Response

{
  "erp_connections": [
    {
      "currency": "GBP",
      "erp_id": [
        "6d23072a-ac3e-4146-9b83-7ad384d65707"
      ]
    }
  ]
}

Responses

Status Code 200

The response will contain array of account numbers in their ERP system against currency wallets of the customer.

Contacts

The Contacts resource allows you to create, update and delete your contact details and any other associated information. Each contact belongs to a customer.

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",
    "employment_status": "Full-time",
    "industry": "Technology and Software",
    "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
employment_status	body	string	false	Employment status of the contact
industry	body	string	false	Employment industry 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",
  "employment_status": "Full-time",
  "industry": "Technology and Software",
  "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
employment_status	body	string	false	Employment status of the contact
industry	body	string	false	Employment industry 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

Adds a recipient to the customer. We recommend using version 2 of this API. Version 2 complies with regulatory requirements of confirm the recipient, if it is a UK based recipient.

> Version 1

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.

> Version 2

Code samples

# You can also use wget
curl -X POST https://sandbox.currenciesdirect.com/v2/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/v2/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/v2/customers/{customerId}/recipients', params={

}, headers = headers)

print r.json()

POST /v2/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",
  "customer_own_account": "no",
  "payment_reference": "7567657657657",
  "address": {
    "address_line": "3 Stable Mews, Westminster",
    "city": "London",
    "state": "England",
    "post_code": "WC1"
  },
  "recipient_bank_details": {
    "currency": "USD",
    "iban": "GB29NWBK60161331926819"
  },
  "confirm_recipient": {
      "customer_action": "override",
      "request_identifier": "123456789",
      "event_id": "AG-435435454435"
  }
}

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).
customer_own_account	body	object	true	Enum: [yes,no]. Recipient to be added is customer own account or not.
payment_reference	body	object	false	Some accounts may require a payment reference. This reference should be used for future payments. It should not contain any special character
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
confirm_recipient	body	object	conditional	Container for confirmation of recipient details. It is required only if CoP check has failed in first iteration.
customer_action	body	object	true	Enum: override, update
request_identifier	body	object	true	Request identifier received in response of iteration 1
event_id	body	object	true	Event id received in response of iteration 1

Example responses

201 Response

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

Error response

{
  "code": "MBAM",
  "description": "Payee’s Bank has performed the matching and confirms it is a close match",
  "recipient_check": {
    "request_identifier": "123456789",
    "suggested_recipient_name": "John Doe",
    "event_id": "AG-435435454435"
  } 
}

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

We recommend using version 2 of this API. Version 2 has some extra fields in response as per regulatory requirements of confirm the recipient, if payment is to a UK based recipient.

> Version 1

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.

> Version 2

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v2/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/v2/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/v2/customers/{customerId}/recipients', params={

}, headers = headers)

print r.json()

GET /v2/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",
      "payment_reference": "443543543",
      "customer_own_account": "no",
      "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.
» payment_reference	string	It is an optional field. Some accounts may require a payment reference. This reference should be passed in future payments.
» customer_own_account	string	Enum: [yes,no]. Added recipient is customer own account or not.
» 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

We recommend using version 2 of this API. Version 2 has some extra fields in response as per regulatory requirements of confirm the recipient, if payment is to a UK based recipient.

> Version 1

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

> Version 2

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v2/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/v2/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/v2/customers/{customerId}/recipients/{recipientId}', params={

}, headers = headers)

print r.json()

GET /v2/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",
  "payment_reference": "5654654654",
  "customer_own_account": "no",
  "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.
payment_reference	string	It is an optional field. Some accounts may require a payment reference. This reference should be passed in future payments.
customer_own_account	string	Enum: [yes,no]. Added recipient is customer own account or not.
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

Updates an existing recipient. We recommend using version 2 of this API, which complies with regulatory requirements to confirm the recipient, if it is a UK based recipient.

> Version 1

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.

> Version 2

Code samples

# You can also use wget
curl -X PUT https://sandbox.currenciesdirect.com/v2/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/v2/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/v2/customers/{customerId}/recipients/{recipientId}', params={

}, headers = headers)

print r.json()

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

Update a Recipient's account

Body parameter

{
  "client_reference_id": "937564823645",
  "name": "Bob Nigh",
  "nick_name": "Bob",
  "type": "Individual",
  "email": "[email protected]",
  "phone_number": "(020)123456789",
  "mobile_number": "+44-987654321",
  "country_code": "GBR",
  "customer_own_account": "no",
  "payment_reference": "45435434543",
  "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"
  },
  "confirm_recipient": {
      "customer_action": "override",
      "request_identifier": "123456789",
      "event_id": "AG-435435454435"
  }
}

Parameters

Name	In	Type	Required	Description
client_reference_id	body	string	false	A Reference Id that you can assign to this Recipient, for your records.
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	true	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).
customer_own_account	body	object	true	Enum: [yes,no]. Recipient to be updated is customer own account or not.
payment_reference	body	object	false	Some accounts may require a payment reference. This reference should be used for future payments. It should not contain any special character
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.
confirm_recipient	body	object	conditional	Container for confirmation of recipient details. It is required only if CoP check has failed in first iteration.
customer_action	body	object	true	Enum: override, update
request_identifier	body	object	true	Request identifier received in response of iteration 1
event_id	body	object	true	Event id received in response of iteration 1

Example responses

200 Response

{
  "recipient_id": "743512"
}

Error response

{
  "code": "MBAM",
  "description": "Payee’s Bank has performed the matching and confirms it is a close match",
  "recipient_check": {
    "request_identifier": "123456789",
    "suggested_recipient_name": "John Doe",
    "event_id": "AG-435435454435"
  } 
}

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 for multiple currencies.

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

Use this resource to request customised currency quotation.

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 currency exchange based on the quote.

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(36)	false	Unique reference id that you want to assign to this conversions for your own purposes.
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",
      "client_reference_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375"
    }
  ],
  "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.
» client_reference_id	string	Unique reference id that you assigned to this conversions for your own purposes.
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",
  "client_reference_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375"
}

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.
client_reference_id	string	Unique reference id that you assigned to this conversions for your own purposes.

Balances

Obtain a list of wallet balances in each currency.

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 new and review existing payments made from your account. We recommend using version 2 of this API. Version 2 complies with regulatory requirements of confirm the recipient, if payment is to a UK based recipient.

Make a Payment

> Version 1

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(36)	false	Unique reference id that you want to assign to this payment for your own purposes.
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.

> Version 2

Code samples

# You can also use wget
curl -X POST https://sandbox.currenciesdirect.com/v2/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/v2/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/v2/customers/{customerId}/payments', params={

}, headers = headers)

print r.json()

POST /v2/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",
  "confirm_recipient": {
      "customer_action": "override",
      "request_identifier": "123456789",
      "event_id": "AG-435435454435"
  }  
}

Parameters

Name	In	Type	Required	Description
client_reference_id	body	string(36)	false	Unique reference id that you want to assign to this payment for your own purposes.
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 and should not contain any special character. If recipient is UK based and is a collection account, use payment_reference of recipient. It should not contain any special character.
customerId	path	string	true	Unique Customer Identifier
confirm_recipient	body	object	conditional	Container for confirmation of recipient details. It is required only if CoP check has failed in first iteration.
customer_action	body	object	true	Enum: override
request_identifier	body	object	true	Request identifier received in response of iteration 1
event_id	body	object	true	Event id received in response of iteration 1

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"
}

Error response

{
  "code": "ANNM",
  "description": "Payee’s Bank has performed the matching and confirms it is not a match",
  "recipient_check": {
    "request_identifier": "123456789",
    "event_id": "AG-435435454435"
  } 
}

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.
currency	query	string	false	Adding this optional parameter will retrieve only payments including this buy currency.
from	query	string	false	Adding this optional query parameter will retrieve only payments made after or on this date.
to	query	string	false	Adding this optional query parameter will retrieve only payments made before or on this date.
paymentstatus	query	string	false	Adding this optional query parameter will retrieve only payments having this status.

Example responses

200 Response

{
    "payments": [
        {
            "payment_id": "2932478",
            "instruction_number": "0202000005924291-000000164",
            "currency_code": "USD",
            "amount": 10,
            "recipient_details": {
                "recipient_name": "Joe Bloggs",
                "recipient_account_number": "457037479121",
                "country_code": "USA"
            },
            "status": "INPROCESS",
            "payment_reference": "987564823645",
            "created_datetime": "2019-05-20T16:42:12Z",
            "payment_date": "2019-05-20",
            "client_reference_id": "987564823645"
        },
        {
            "payment_id": "2932470",
            "instruction_number": "0202000005924291-000000162",
            "currency_code": "USD",
            "amount": 10,
            "recipient_details": {
                "recipient_name": "Joe Bloggs",
                "recipient_account_number": "457037479121",
                "country_code": "USA"
            },
            "status": "INPROCESS",
            "payment_reference": "987564823645",
            "created_datetime": "2019-05-20T14:07:12Z",
            "payment_date": "2019-05-20",
            "client_reference_id": "987564823646"
        },
        {
            "payment_id": "2932232",
            "instruction_number": "0202000005924291-000000161",
            "currency_code": "USD",
            "amount": 1.91,
            "recipient_details": {
                "recipient_name": "Joe Bloggs",
                "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",
            "client_reference_id": "987564823647"
        },
        {
            "payment_id": "2932072",
            "instruction_number": "0202000005924291-000000160",
            "currency_code": "USD",
            "amount": 1.91,
            "recipient_details": {
                "recipient_name": "Joe Bloggs",
                "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",
            "client_reference_id": "987564823648"
        },
        {
            "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",
            "client_reference_id": "987564823649"
        }
    ],
    "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.
» client_reference_id	string	Unique reference id that you assigned to this payment for your own purposes.
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",
  "client_reference_id": "987564823645"
}

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.
client_reference_id	string	Unique reference id that you assigned to this payment for your own purposes.

Statements

View currency level statements to monitor past transactions or view multiple accounts statements to know the credits and fees deducted for payments.

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.

Partner APIs

These are designed to support the world of Affiliate marketing enabling partners to connect different systems and support their custom campaigns.

The affiliate APIs are based on REST and use HTTP response codes to flag errors. Helpful API features such as token authentication HTTP verbs make these resources easy to use for a wider audience.

Get Monthly Referrals

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/referrals/month

Use the above resource to retrieve monthly affiliate referral details. These are the referrals made by partners for Currencies Direct. This is a protected resource which means you will need to provide authorisation token to access it.

Body parameter

{
  "affiliate_number": [
    "A060001"
  ],
  "statement_year": "2020",
  "statement_month": "9"
}

Parameters

Name	In	Type	Required	Description
affiliate_number	body	array	true	This is the affiliate number given to each referrals.
statement_year	body	string	true	Indicates the year for which the statement was issued.
statement_month	body	string	true	Indicates the month for which the statement was issued.

Example responses

200 Response

{
  "referrals": [
    {
      "uid": "3ftAsGKFbv",
      "type": "Personal",
      "datereferred": "2022-07-12",
      "estimatedtransactionalvalue": 2,000-5,000
    },
    {
      "uid": "null",
      "type": "Personal",
      "datereferred": "2022-07-20",
      "estimatedtransactionalvalue": Under 2,000
    },

  ],
}

Responses

Status Code 200

OK

Name	Type	Description
referrals	[object]	Array of referrals.
» uid	string	User identification number.
» type	string	Whether a Personal or Business.
» datereferred	string(date)	Referral date.
» estimatedtransactionalvalue	number(float)	Value of estimated transaction.

Get Monthly Registrations

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/registrations/month

Use the above resource to retrieve affiliate registration details. These are potential customers which have arrived from the third-party website to currencies direct and have registered to complete a currency exchange.

Body parameter

{
  "affiliate_number": [
    "A060001"
  ],
  "statement_year": "2020",
  "statement_month": "9"
}

Parameters

Name	In	Type	Required	Description
affiliate_number	body	array	true	This is the affiliate number given to each registrations.
statement_year	body	string	true	Indicates the year for which the statement was issued.
statement_month	body	string	true	Indicates the month for which the statement was issued.

Example responses

200 Response

{
  "registrations": [
    {
      "uid": "null",
      "clientid": "0201001006802081",
      "type": "Personal",
      "dateregistered": "2022-07-12",
      "estimatedtransactionalvalue": 2,000-5,000
      "trackingid": "null",
    },

  ],
}

Responses

Status Code 200

OK

Name	Type	Description
registrations	[object]	Array of registrations.
» uid	string	User identification number.
» clientid	string	Clients identification number.
» type	string	Whether a Personal or Business.
» dateregistered	string(date)	Registration date.
» estimatedtransactionalvalue	number(float)	Value of estimated transaction.
» trackingid	string	Tracking number.

Get Monthly Commissions

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/commission/month

Use the above resource to obtain the commission data for each the transactions. Each of these transactions is completed by the affiliate customer.

Body parameter

{
  "affiliate_number": [
    "A060001"
  ],
  "statement_year": "2020",
  "statement_month": "9"
}

Parameters

Name	In	Type	Required	Description
affiliate_number	body	array	true	This is the affiliate number given to each commissions.
statement_year	body	string	true	Indicates the year for which the statement was issued.
statement_month	body	string	true	Indicates the month for which the statement was issued.

Example responses

200 Response

{
  "commissions": [
    {
      "commissionamount": "23.31",
      "tier": "1",
      "commissionpaidamount": "26.20",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.123820
      "commissionamountcurrency": "GBP",
      "commissionpaiddate": "2023-02-02",
      "dealnumber": "0101000000163848-000000007",
    },

    {
      "commissionamount": "23.45",
      "tier": "1",
      "commissionpaidamount": "26.35",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.123820
      "commissionamountcurrency": "GBP",
      "commissionpaiddate": "2023-02-02",
      "dealnumber": "0101000000163848-000000008",
    },

    {
      "commissionamount": "106.51",
      "tier": "1",
      "commissionpaidamount": "119.70",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.123820
      "commissionamountcurrency": "GBP",
      "commissionpaiddate": "2023-02-02",
      "dealnumber": "0101000006061046-000000004",
    },

    {
      "commissionamount": "4.31",
      "tier": "1",
      "commissionpaidamount": "4.84",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.123820
      "commissionamountcurrency": "GBP",
      "commissionpaiddate": "2023-02-02",
      "dealnumber": "0101000006061046-000000001",
    },

  ],
}

Responses

Status Code 200

OK

Name	Type	Description
commissions	[object]	Array of commissions.
» commissionamount	string	Commission amount.
» tier	string	Tier number.
» commissionpaidamount	string	Commission paid amount.
» commissionpaymentcurrency	string	Commission payment currency.
» exchangerate	number(float)	Exchange rate.
» commissionamountcurrency	string	Commission amount in currency.
» commissionpaiddate	string(date)	Commission paid date.
» dealnumber	string	Deal unique number.

Get Monthly Trades

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/trades/month

Use the above resource to retrieve affiliate trade details. These are the details generated for each of the transaction completed monthly by the affiliate contact.

Body parameter

{
  "affiliate_number": [
    "A060001"
  ],
  "statement_year": "2020",
  "statement_month": "9"
}

Parameters

Name	In	Type	Required	Description
affiliate_number	body	array	true	This is the affiliate number given to each trade.
statement_year	body	string	true	Indicates the year for which the statement was issued.
statement_month	body	string	true	Indicates the month for which the statement was issued.

Example responses

200 Response

{
  "trades": [
    {
      "sold": "GBP",
      "profitcurrency": "GBP",
      "clientid": "0201001006802081",
      "closedate": "2022-07-13",
      "bought": "EUR",
      "type": "Personal",
      "uid": "null",
      "isfirsttrade": "true",
      "commission": "0.00",
      "turnover": "18000.00000000",
      "profit": "203.13000000"
      "trackingid": "null",
    },
    {
      "sold": "GBP",
      "profitcurrency": "GBP",
      "clientid": "0201001006802081",
      "closeddate": "2022-07-13",
      "bought": "EUR",
      "type": "Personal",
      "uid": "null",
      "isfirsttrade": "true",
      "commission": "0.00",
      "turnover": "18000.00000000",
      "profit": "203.13000000"
      "trackingid": "null",
    },

  ],
}

Responses

Status Code 200

OK

Name	Type	Description
trades	[object]	Array of trades.
» sold	string	Sold in currency.
» profitcurrency	string	Profit in currency.
» clientid	string	Clients identification number.
» closeddate	string(date)	Closing date.
» bought	string	Bought in currency.
» type	string	Whether a Personal or Business.
» uid	string	User identification number.
» isfirsttrade	string	First trade true or false.
» turnover	string	Turnover amount.
» profit	string	Profit amount.
» trackingid	string	Tracking number.

Get Manual Commission

Code samples

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

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

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/v1/affiliates/manual-commission/month',
  method: 'post',

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

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

r = requests.post('https://sandbox.currenciesdirect.com/v1/affiliates/manual-commission/month', params={

}, headers = headers)

print r.json()

POST /v1/affiliates/manual-commission/month

Use the above resource to retrieve commission data manually.

Body parameter

{
  "affiliate_number": [
    "A060001"
  ],
  "statement_year": "2020",
  "statement_month": "9"
}

Parameters

Name	In	Type	Required	Description
affiliate_number	body	array	true	This is the affiliate number given to each commission.
statement_year	body	string	true	Indicates the year for which the statement was issued.
statement_month	body	string	true	Indicates the month for which the statement was issued.

Example responses

200 Response

{
  "manual commissions": [
    {
      "commissionamount": "17.00",
      "commissionpaidamount": "14.45",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.000000
      "description": "fdgdrg",
      "commissionamountcurrency": "EUR",
      "commissionpaiddate": "2023-07-25",
    },

    {
      "commissionamount": "15.00",
      "commissionpaidamount": "12.75",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.000000
      "description": "vdxygdfgd",
      "commissionamountcurrency": "EUR",
      "commissionpaiddate": "2023-07-18",
    },

    {
      "commissionamount": "16.00",
      "commissionpaidamount": "13.60",
      "commissionpaymentcurrency": "EUR",
      "exchangerate": 1.000000
      "description": "dvdfgf",
      "commissionamountcurrency": "EUR",
      "commissionpaiddate": "2023-07-18",
    },


  ],
}

Responses

Status Code 200

OK

Name	Type	Description
manual commissions	[object]	Array of manual commissions.
» commissionamount	string	Commission amount.
» commissionpaidamount	string	Commission paid amount.
» commissionpaymentcurrency	string	Commission payment currency.
» exchangerate	number(float)	Exchange rate.
» description	string	Description.
» commissionamountcurrency	string	Commission amount in currency.
» commissionpaiddate	string(date)	Commission paid date.

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.

Employment Status

Code samples

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

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

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/references/employment-status',
  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/references/employment-status', params={

}, headers = headers)

print r.json()

GET /references/employment-status

Get a list of supported employment statuses. To be used in Register a Customer, Add Contact or Update Contact journey.

Example responses

200 Response

{
    "empoyment_statuses": [
        "Full-time",
        "Part-time",
        "Self-employed",
        "Unemployed",
        "Retired",
        "Student",
        "Full-time carer",
        "Full-time parent",
        "Not working due to illness/disability"
    ]
}

Responses

Status Code 200

The response will contain array of employment statuses.

Employment Industry

Code samples

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

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

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/references/employment-industry',
  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/references/employment-industry', params={

}, headers = headers)

print r.json()

GET /references/employment-industry

Get a list of supported employment industries. To be used in Register a Customer, Add Contact or Update Contact journey.

Example responses

200 Response

{
    "employment_industries": [
        "Accounting",
        "Administrative & Office Support",
        "Aerospace and Aviation",
        "Agriculture and Agribusiness",
        "Agriculture, Forestry, and Fishing",
        "Armed Forces and Defence",
        "Arts, Sports, and Creative",
        "Call Centre & Customer Services",
        "Charity and Non-profit",
        "Construction and Engineering",
        "Consulting and Professional Services",
        "Education",
        "Energy, Green Technology & Utility Services",
        "Entertainment and Media",
        "Environmental Services",
        "Finance and Insurance",
        "Government and Public Service",
        "Healthcare and Social Services",
        "Hospitality and Tourism",
        "Human Resources & Recruitment",
        "Information and Communication",
        "Legal and Regulatory Services",
        "Manufacturing and Production",
        "Marketing and Advertising",
        "Mining & Geology",
        "Motor Trade, Automotive and Manufacturing",
        "Non-Governmental Organisations (NGOs)",
        "Pharmaceuticals and Biotechnology",
        "Property and Real Estate",
        "Retail",
        "Scientific and Technical",
        "Technology and Software",
        "Telecommunications",
        "Trades & Services",
        "Transport and Logistics",
        "Wholesale and Distribution"
    ]
}

Responses

Status Code 200

The response will contain array of employment industries.

Virtual Accounts

Virtual Accounts are unique, bank routing instructions which are assigned to an individual customer (can be a personal customer or a business customer). Virtual Accounts will be available in a number of currencies. Please contact your Account Manager or Implementation Manager for more information. Virtual accounts can be requested for registered and active customers.

Request a virtual account

Code samples

# You can also use wget
curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts \
  -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}/virtual-accounts',
  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}/virtual-accounts', params={

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/virtual-accounts

This will initiate the process of creating a virtual account for the customer.

Body parameter

{
  "currency": "EUR",
  "vban_country": "USA"
}

Parameters

Name	In	Type	Required	Description
currency	body	string(3)	true	ISO Code of the virtual account currency.
vban_country	body	string(3)	false	Country code of the preferred country for virtual account. Mandatory field for EUR currency.

Example responses

201 Response

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

Responses

Status Code 201

Ok. A virtual account creation process has been initiated.

Name	Type	Description
unique_identifier	string	Unique identifier to identify this virtual account in future.

View a virtual account

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts/{vbanNumber} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'
Or
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts?currency={currency} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'
Or
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts?unique-ref={uniqueRefence} \
  -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}/virtual-accounts/{vbanNumber}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})
Or
var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts?currency={currency}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})
Or
var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts?unique-ref={uniqueRefence}',
  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}/virtual-accounts', params={

}, headers = headers)

print r.json()

GET v1/customers/{customerId}/virtual-accounts/{vbanNumber}

GET v1/customers/{customerId}/virtual-accounts?currency={currency}

GET v1/customers/{customerId}/virtual-accounts?unique-ref={uniqueRefence}

Get virtual account details.

Parameters

Name	In	Type	Required	Description
customerId	path	string	true	Unique Customer Identifier
vbanNumber	path	string	true	Virtual bank account number
currency	querystring	string	true	Code for the currency of the virtual bank account in ISO 4217 three letter format (e.g. GBP for UK pound).
uniqueRefence	querystring	string	true	unique reference retuned in response of create virtual account request.

Example responses

200 Response

{
  "customer_id": "0201000010520648",
  "customer_name": "Trevor",
  "virtual_account_details": {
    "virtual_account_number": "123456000000049",
    "virtual_account_type": "Checking",
    "financial_institution_name": "CFSB bank",
    "address": "CFSB US",
    "status": "ACTIVE",
    "currency": "USD",
    "country": "USA"
    "country_specific_code": "543212458",
    "country_specific_type": "ABA",
    "country_specific_method": "ACH",
    "country_specific_code2": "543212458",
    "country_specific_type2": "ABA",
    "country_specific_method2": "WIRE"
  }
}

Responses

Status Code 200

OK

Name	Type	Description
customer_id	string	Customer number.
customer_name	string	Name of the customer.
virtual_account_details	object	Contain details of virtual account.
» virtual_account_number	string	Account number of customer's virtual account.
» virtual_account_type	string	Type of customer's virtual account.
» financial_institution_name	string	Name of bank/financial institution.
» address	string	Address of bank/financial institution.
» status	string	Status of virtual account.
» currency	string	Currency of virtual account.
» country	string	Country of virtual account.
» country_specific_code	string	Code of bank/financial institution.
» country_specific_type	string	Type of bank/financial institution's code.
» country_specific_method	string	Method/network to be used for money transfer.
» country_specific_code2	string	Second code of bank/financial institution.
» country_specific_type2	string	Type of bank/financial institution's second code.
» country_specific_method2	string	Method/network to be used for money transfer using second code.

View virtual accounts

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts \
  -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}/virtual-accounts',
  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}/virtual-accounts', params={

}, headers = headers)

print r.json()

GET v1/customers/{customerId}/virtual-accounts

Get details of all virtual accounts alloted to the customer.

Parameters

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

Example responses

200 Response

{
  "customer_id": "0201000010520648",
  "customer_name": "Trevor",
  "virtual_account_details": [
    {
      "virtual_account_number": "123456000000049",
      "virtual_account_type": "Checking",
      "financial_institution_name": "CFSB bank",
      "address": "CFSB US",
      "status": "ACTIVE",
      "currency": "USD",
      "country": "USA",
      "country_specific_code": "543212458",
      "country_specific_type": "ABA",
      "country_specific_method": "ACH",
      "country_specific_code2": "543212458",
      "country_specific_type2": "ABA",
      "country_specific_method2": "WIRE"
    }
  ]
}

Responses

Status Code 200

OK

Name	Type	Description
customer_id	string	Customer number.
customer_name	string	Name of the customer.
virtual_account_details	object	Array of virtual accounts.
» virtual_account_number	string	Account number of customer's virtual account.
» virtual_account_type	string	Type of customer's virtual account.
» financial_institution_name	string	Name of bank/financial institution.
» address	string	Address of bank/financial institution.
» status	string	Status of virtual account.
» currency	string	Currency of virtual account.
» country	string	Country of virtual account.
» country_specific_code	string	Code of bank/financial institution.
» country_specific_type	string	Type of bank/financial institution's code.
» country_specific_method	string	Method/network to be used for money transfer.
» country_specific_code2	string	Second code of bank/financial institution.
» country_specific_type2	string	Type of bank/financial institution's second code.
» country_specific_method2	string	Method/network to be used for money transfer using second code.

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 Currencies Direct send out status updates via email. Webhooks allow you to subscribe to 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 their virtual accounts.

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. Permitted values: ["CUSTOMER STATUS", "VBAN STATUS"]
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.

Customer 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 Response 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, Currencies Direct 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	Type	Description
customer_type	string	Registering customer type.
status	string	Whether the customer is active or inactive.
unique_identifier	string	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	string	When the customer is inactive this will be the reason for it being 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 Currencies Direct.
contacts	object	Object containing an array of contacts.
» contact_id	string	Unique ID for this contact.
» 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.
» 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 Currencies Direct.

Virtual Account Status Updates

The status of virtual account can change to Active or Closed.

Callback Response Body

{
  "customer_id": "0201000010520648",
  "customer_name": "Trevor",
  "virtual_account_details": {
    "virtual_account_number": "123456000000049",
    "virtual_account_type": "Checking",
    "financial_institution_name": "CFSB bank",
    "address": "CFSB US",
    "status": "ACTIVE",
    "currency": "USD",
    "country": "US",
    "country_specific_code": "543212458",
    "country_specific_type": "ABA",
    "country_specific_method": "ACH",
    "country_specific_code2": "543212458",
    "country_specific_type2": "ABA",
    "country_specific_method2": "WIRE"
  }
}

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

Parameters

Name	Type	Description
customer_id	string	Customer number.
customer_name	string	Name of the customer.
virtual_account_details	object	Contain details of virtual account.
» virtual_account_number	string	Account number of customer's virtual account.
» virtual_account_type	string	Type of customer's virtual account.
» financial_institution_name	string	Name of bank/financial institution.
» address	string	Address of bank/financial institution.
» status	string	Status of virtual account.
» currency	string	Currency of virtual account.
» country	string	Country of virtual account.
» country_specific_code	string	Code of bank/financial institution.
» country_specific_type	string	Type of bank/financial institution's code.
» country_specific_method	string	Method/network to be used for money transfer.
» country_specific_code2	string	Second code of bank/financial institution.
» country_specific_type2	string	Type of bank/financial institution's second code.
» country_specific_method2	string	Method/network to be used for money transfer using second code.

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.currenciesdirect.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.currenciesdirect.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.currenciesdirect.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 Currencies Direct. 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 Currencies Direct 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.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.currenciesdirect.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 Currencies Direct, 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.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 - TSP

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.

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 Currencies Direct.
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 Currencies Direct 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

Payment Statuses

Description of payment statuses returned in Review Payments and View a Payment.

Payment Status	Description
InProcess	Payment is in proess
AwaitingBankApproval	Waiting for payment approval
Approved	Payment is approved and released to beneficiary's bank
Rejected	Payment rejected
Cancelled	Manually cancelled by operations
Returned	Fund returned by bank

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.

Migration Guides

UK Confirmation of Payee regulations

This guide will walk you through the changes required to comply with the new UK Confirmation of Payee regulations.

The new regulations affect the following flows:

· Creating and updating recipients

· Creating payments

To support these changes, we are releasing v2 of the relevant API endpoints, as documented below. Each section below explains when the new regulations apply.

You can begin developing these changes straightaway. Our new API endpoints will be ready for testing in our UAT environment on 24th September 2024, so you can ensure the changes won’t break anything.

Starting 31st October 2024, payments covered by the regulation submitted through the current v1 API endpoints will be rejected.

Create Recipient

With the new regulation, anytime you create a new recipient with UK bank account details, we will check the details with the recipient’s bank to ensure they are correct. You don’t need to know which recipients are affected by the new regulation – you will continue to create recipients equally regardless of country, however you must implement logic in your application to support Confirmation of Payee responses, when you do receive them.

The new endpoint is: POST /v2/customers/{customerId}/recipients

The new endpoint works exactly the same way for non UK recipients, so migration should be straightforward.

The new endpoint also introduces two new fields:

• customer_own_account, which must be set to either yes or no, depending on whether the recipient is the customer’s own bank account.

• payment_reference, which is optional and can be used to define the default reference for any payments to this recipient

For UK recipients, when the request is made, we will check the details provided with the recipient’s bank. If they match exactly, the recipient is simply created (no change vs current flow).

However, if there is a mismatch, an error will be returned with further details. See the Resolve a Confirmation of Payee Mismatch section to learn how to handle these errors.

Update Recipient

Just like when creating recipients, anytime a UK recipient is updated, a fresh Confirmation of Payee check is carried out.

The new endpoint is: PUT /v2/customers/{customerId}/recipients/{recipientId} .

Just like with Create Recipient, the new customer_own_account and payment_reference fields are introduced. Additionally, if there is a mismatch, an error will be returned with further details. See the Resolve a Confirmation of Payee Mismatch section to learn how to handle these errors.

Create Payment

With the new regulation, in addition to checking UK recipient details when a recipient is added to the system or updated, we are also required to repeat the Confirmation of Payee check when a payment is created in the following circumstances:

• If it’s been more than 6 months since the last check, or

• If the payment reference has changed, or is different from the one stored on the recipient record

The new endpoint is: POST /v2/customers/{customerId}/payments .

Just like with Create and Update Recipient, if a Confirmation of Payee check was required, carried out and there is a mismatch, an error will be returned with further details. See the Resolve a Confirmation of Payee Mismatch section to learn how to handle these errors.

Resolve a Confirmation of Payee Mismatch

Anytime we run a Confirmation of Payee check and a mismatch occurs, an error is returned. In most cases, you will be able to resolve the issue by asking the user for feedback - more details below.

Based on the type of error, will need to display the error to the user, ask them for the best course of action, and then repeat the initial request, now using the request_identifier and the event_id provided with the error payload, to complete the action.

Here is a sample error payload:

Details of each case are outlined below. Regardless of the case, once an action is selected by the user, the follow up request should look like the following:

New request body

The sections below outline the details of each type of mismatch and how to handle it.

Case 1: No match

Error code: ANNM

Sample response:

How to handle it:

You must display the error message to the user. The user has the option to continue anyway, or to update the details.

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

If the user updates the details, repeat the flow from the beginning

Case 2: Close match

Error code: MBAM

Sample response:

How to handle it:

You must display the suggestion to the user. The user has the option to accept the suggestion, or continue with the original details they provided:

If the user chooses to accept the suggestion, repeat the request as described above, with confirm_recipient.customer_action: "update"

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

Case 3: Recipient is a Business account

Error code: BANM

Sample response:

How to handle it:

You must inform the user that the name was matched, but the account is a Business account and not a Personal account. The user has the option to update the recipient type to Business, or continue with the original details they provided:

If the user chooses to update the recipient type, repeat the request as described above, with confirm_recipient.customer_action: "update"

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

Case 4: Recipient is a Personal account

Error code: PANM

Sample response:

How to handle it:

You must inform the user that the name was matched, but the account is a Personal account and not a Business account. The user has the option to update the recipient type to Personal, or continue with the original details they provided:

If the user chooses to update the recipient type, repeat the request as described above, with confirm_recipient.customer_action: "update"

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

Case 5: Recipient is a Business account, and account name is a close match

Error code: BAMM

Sample response:

How to handle it:

You must inform the user that the name was a close match, display the suggestion, and also that the account is a Business account and not a Personal account. The user has the option to update the recipient type to Business, and accept the name suggestion, or continue with the original details they provided:

If the user chooses to update the recipient name and type, repeat the request as described above, with confirm_recipient.customer_action: "update"

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

Case 6: Recipient is a Personal account, and account name is a close match

Error code: PAMM

Sample response:

How to handle it:

You must inform the user that the name was a close match, display the suggestion, and also that the account is a Personal account and not a Business account. The user has the option to update the recipient type to Personal, and accept the name suggestion, or continue with the original details they provided:

If the user chooses to update the recipient name and type, repeat the request as described above, with confirm_recipient.customer_action: "update"

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

Case 7: Incorrect account number

Error code: AC01

Sample response:

How to handle it:

You must inform the user that the account does not exist. The user has to update the details in order to proceed with payment.

Case 8: Invalid reference number

Error code: IVCR

Sample response:

How to handle it:

You must inform the user that the reference number is invalid. The user has the option to update the details, or continue with the original details they provided:

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

If the user updates the details, repeat the flow from the beginning

Case 9: Opted out of Confirmation of Payee

Error code: OPTO

Sample response:

How to handle it:

You must inform the user that the recipient has chosen not to use Confirmation of Payee checks. The user has the option to update the details, or continue with the original details they provided:

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

If the user updates the details, repeat the flow from the beginning

Case 10: Account has been switched

Error code: CASS

Sample response:

How to handle it:

You must inform the user that the recipient has switched accounts and these details are no longer valid. The user has to update the details in order to proceed with payment.

Case 11: Sort code not supported

Error code: SCNS

Sample response:

How to handle it:

The user should be informed that Confirmation of Payee could not be carried out because the recipient’s sort code doesn’t support this check.

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

If the user updates the details, repeat the flow from the beginning

Case 12: Account type not supported

Error code: ACNS

Sample response:

How to handle it:

The user should be informed that Confirmation of Payee isn’t supported by the recipient’s financial institution.

If the user chooses to continue anyway, repeat the request as described above, with confirm_recipient.customer_action: "override"

If the user updates the details, repeat the flow from the beginning.