Currencies Direct APIs Currencies Direct APIs NAV Navbar
Shell JavaScript Python

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 current version of the API is v 1.0.

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

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:

making a foreign exchange payment

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

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

More details can be found in the following sections:

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

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

Authentication

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

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

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

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

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

  # The resulting request will look similar to this:
  curl -X POST https://api.currenciesdirect.com/v1/customers -H 'Content-Type: application/json' -H 'Authorization: Bearer dadadb2c-1ae2-48a2-a5dc-506e0432067b'
  1. Send an email to API Support requesting credentials to access to our API. Please specify the resources you require access to, the purpose of the access and the planned frequency of the requests you intend to make. When you are approved as a user, you will receive credentials in the form of a client_id and client_secret. Treat these with care as they are like your username and password for the API. They protect your data against requests from malicious users.
  2. Make a HTTPS request to the Authenticate Resource including the credentials in the request body. See Get an Access Token for a full description of the parameters in the request body and header.
  3. If the details are correct the server will respond with an access_token in the response body. The access_token is in GUID format.
  4. Make a request to a 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:

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:

If you have a question about the API, please email: it-support@currenciesdirect.com.

For terms of service see Terms of service.

APIs

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

Authenticate

Request an Access Token to Authenticate.

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. OAuth2 Request Sequence Diagram 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 create, update and delete all your customers' data.

Register a Customer

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Get Customer's ID

Code samples

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

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

};

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

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

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

print r.json()

GET /v1/customers

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

Parameters

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

Example responses

200 Response

{
    "customer_id": "0045698757"
}

Responses

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

Get Customer

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}

Review a Customer's details.

Parameters

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

Example responses

200 Response

{
  "customer_type": "Business",
  "status": "Active",
  "company": {
    "name": "Robin Hood Ltd",
    "type": "Pvt Ltd",
    "vat_number": "7979797979",
    "registration_number": "13123121",
    "country_of_incorporation": "GBR",
    "address": {
      "unit_number": "12",
      "street": "London Road",
      "street_type": "Canary Wharf",
      "post_code": "E14 5AB",
      "city": "LONDON",
      "country": "GBR"
    }
  },
  "contacts": [
    {
      "first_name": "Robin",
      "middle_name": "Junior",
      "last_name": "Hood",
      "date_of_birth": "2072-04-30",
      "occupation": "Analyst",
      "nationality": "British",
      "email": "robin.hood@currenciesdirect.com",
      "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
» 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

Contacts

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

Add a Contact

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/contacts

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

Body parameter

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

Parameters

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

Example responses

200 Response

{
  "customer_id": "0201563989"
}

Responses

Status Code 200

Ok.

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

Update a Contact

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok.

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

Remove a Contact

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Remove a Contact from this Customer.

Parameters

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

Recipients

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

Create Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/recipients

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

General Information

Recipient 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:

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

Body parameter

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

Parameters

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

Example responses

201 Response

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

Responses

Status Code 201

Successfully created a Recipient's account.

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

Get Recipients

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/recipients

Get the details of all active Recipients for this Customer.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Get a Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Update Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Update a Recipient's account

Body parameter

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

Parameters

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

Example responses

200 Response

{
  "recipient_id": "743512"
}

Responses

Status Code 200

Successfully updated a Recipient's account.

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

Delete Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

This will set the status of the Recipient to inactive.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Successfully deleted a Recipient's account.

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

Rates

Get current foreign exchange rates.

Get Exchange Rates

Code samples

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

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

};

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

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

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

print r.json()

GET /v1/rates

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

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

Quotes

Get fixed price quotations.

Get Quotation

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/quotes

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Conversions

Execute a Forex Exchange, swapping one currency for another.

Request Conversion

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/conversions

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

View Conversions

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/conversions

Retrieve details of all your previous conversions.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

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

Get a Conversion

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Retrieve details of a previously requested currency conversion.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

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

Balances

Get your Wallet Balances.

Get Balances

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/balances

Get wallet balances for all of your activated currencies.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Get a Balance

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Get wallet balances for a single currency.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Payments

Initiate Payments and Review their details.

Make a Payment

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/payments

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok. A payment was initiated.

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

Review Payments

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/payments

Review all your Payments.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

View a Payment

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

View a Single Payment.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Statements

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

View Statements

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

OK

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

Collection Account Statements

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

OK

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

References

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

Currencies

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/references/currencies

Get a list of supported currencies for your organisation.

Example responses

200 Response

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

Responses

Status Code 200

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

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

Transaction Purposes

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/references/transaction-purpose

Get a list of transaction purposes.

Example responses

200 Response

[
  {
    "country_code": "All",
    "transaction_purposes": [
      "Pension",
      "Art / Antiques",
      "Study fees",
      "Car",
      "Emigration",
      "Land",
      "Mortgage",
      "Bill payments",
      "Building / repairs",
      "Property",
      "Property sale",
      "Yacht",
      "Living funds",
      "Other"
    ]
  }
]

Responses

Status Code 200

The response will contain an array of purposes.

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

Webhooks

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

Subscribe for Updates

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/webhooks

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

Body parameter

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

Parameters

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

Example responses

200 Response

{
  "id": 1234567
}

Responses

Status Code 200

Ok. You successfully subscribed to a feed.

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

Status Updates

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

Callback Request Body

Body parameter - Active Account

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

Body parameter - In-Active Account

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

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

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.

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.