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 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 join us on slack channel by clicking here.

For terms of service see Terms of service.

APIs

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

Authenticate

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

Get an OAuth Access Token

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /auth/oauth/v2/token

To access any of the other API resources you will first need to obtain a token. Make a POST request to this Resource. 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 integrate all the available customer resources from Currencies Direct. These resources are designed for you to create, update, and delete customer’s data.

Register a Customer

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers

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

Body parameter

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

Parameters

Name In Type Required Description
customer_type body string true Registering customer type
company body object false Only required for Business Customer. These are the details of your Company.
» name body string true Name of the company
» type body string true Company type
» vat_number body string false Company's VAT number
» registration_number body string true Company's registration number
» country_of_incorporation body string true Country where the company is registered
» address body object true Container for address details.
»» unit_number body string false Unit number
»» street_number body string false Street number
»» street body string false Street name
»» street_type body string false Type of street.
»» post_code body string true Postcode or zip code
»» city body string true City name
»» civic_number body string false Civic number
»» state body string false State
»» country body string true Contact country code
contacts body [object] true This is an array with a minimum of one Contact object and maximum of two.
» first_name body string true First name of this contact person.
» middle_name body string false Middle name of this contact person.
» last_name body string true Last name of this contact person.
» date_of_birth body string true DOB of contact person
» employment_status body string false Employment status of the contact
» industry body string false Employment industry of the contact
» nationality body string false Nationality of the contact
» email body string true Email address of the contact person
» phone_number body string false Contact phone number
» mobile_number body string true mobile number of the contact
» primary_contact body boolean true Primary contact for the customer account
» authorize_to_trade body boolean true Whether the customer is authorised to trade with us.
» address body object true Container for address details.
»» unit_number body string false Unit number
»» street_number body string false Street number
»» street body string false Street name
»» street_type body string false Street type
»» post_code body string true Postcode or zip code
»» city body string true City name
»» civic_number body string false Civic number
»» state body string false State
»» country body string true Contact country code
» proof_of_identity body object false Proof of identity
»» oneOf
»»» passport body object false Container for passport details.
»»»» number body string true Passport number
»»»» name_at_citizenship body string false Name as per citizenship
»»»» family_name_at_birth body string false Family name at the time of birth
»»»» place_of_birth body string true Place of birth
»»»» expiry_date body string true Expiry date
»»»» issuing_country body string true Passport issuing country
»» xor
»»» medicare body object false Container for Medicare details.
»»»» card_number body string true Medicare card number
»»»» reference_number body string true Medicare reference number
»» xor
»»» 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.
» etv body [string] true Estimated transaction value
» Possible values:
» Under 2,000
» 2,000 - 5,000
» 2,000 - 10,000
» 5,000 - 10,000
» 10,000 - 25,000
» 25,000 - 50,000
» 50,000 - 100,000
» 100,000 - 250,000
» over 250,000
» ccy_pair body [string] true default currency pair, selling currency code followed by buying currency code

Example responses

200 Response

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

Responses

Status Code 200

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

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

Get Customer's ID

Code samples

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

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

};

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

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

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

print r.json()

GET /v1/customers

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

Parameters

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

Example responses

200 Response

{
    "customer_id": "0045698757"
}

Responses

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

Get Customer

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/details

Review a Customer's details.

Parameters

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

Example responses

200 Response

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

Responses

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

Upload documents

Code samples

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

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

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}/documents/{accountSFID}-{contactSFID}',
  method: 'get',

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

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

r = requests.get('https://sandbox.currenciesdirect.com/v1/customers/{customerId}/contacts/{contactId}/documents/{accountSFID}-{contactSFID}', params={

}, headers = headers)

print r.json()

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

Upload Customer's POI/POA documents.

Parameters

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

Example responses

200 Response

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

Responses

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

Contacts

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

Add a Contact

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/contacts

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

Body parameter

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

Parameters

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

Example responses

200 Response

{
  "customer_id": "0201563989"
}

Responses

Status Code 200

Ok.

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

Update a Contact

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok.

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

Remove a Contact

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Remove a Contact from this Customer.

Parameters

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

Recipients

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

Create Recipient

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": "[email protected]",
  "phone_number": "(020)123456789",
  "mobile_number": "+44-987654321",
  "client_reference_id": "937564823645",
  "country_code": "GBR",
  "address": {
    "address_line": "3 Stable Mews, Westminster",
    "city": "London",
    "state": "England",
    "post_code": "WC1"
  },
  "recipient_bank_details": {
    "currency": "USD",
    "iban": "GB29NWBK60161331926819"
  }
}

Parameters

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

Example responses

201 Response

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

Responses

Status Code 201

Successfully created a Recipient's account.

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

Get Recipients

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/recipients

Get the details of all active Recipients for this Customer.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Get a Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Update Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Update a Recipient's account

Body parameter

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

Parameters

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

Example responses

200 Response

{
  "recipient_id": "743512"
}

Responses

Status Code 200

Successfully updated a Recipient's account.

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

Delete Recipient

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

This will set the status of the Recipient to inactive.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Successfully deleted a Recipient's account.

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

Rates

Get current foreign exchange rates for multiple currencies.

Get Exchange Rates

Code samples

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

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

};

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

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

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

print r.json()

GET /v1/rates

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

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

Quotes

Use this resource to request customised currency quotation.

Get Quotation

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/quotes

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Conversions

Execute a currency exchange based on the quote.

Request Conversion

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/customers/{customerId}/conversions

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

View Conversions

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/conversions

Retrieve details of all your previous conversions.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

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

Get a Conversion

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Retrieve details of a previously requested currency conversion.

Parameters

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

Example responses

200 Response

{
  "conversion_id": 2907898,
  "instruction_number": "0202000005923566-000000011",
  "selling_currency": "GBP",
  "buying_currency": "EUR",
  "selling_amount": 2.3,
  "buying_amount": 2.57,
  "agreed_rate": 1.1181,
  "booking_datetime": "2018-10-19T10:51:13Z",
  "status": "OPEN",
  "value_date": "2018-10-19",
  "client_reference_id": "42a8a4e6-05e0-4188-bd87-70a2febb5375"
}

Responses

Status Code 200

Ok. Successfully requested details of a Conversion.

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

Balances

Obtain a list of wallet balances in each currency.

Get Balances

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/balances

Get wallet balances for all of your activated currencies.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Get a Balance

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Get wallet balances for a single currency.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Payments

Initiate new and review existing payments made from your account.

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(16) false Unique reference id that you want to assign to this payment for your own purposes.
recipient_id body string true The Payee ID used to identify this Recipient.
purpose_of_transaction body string true Purpose of the transaction. A list of possible values can be obtained with a GET request to the transaction-purpose resource
amount body number(float) true Amount of the payment.
payment_reference body string true Description to appear on the Recipient's bank statement.
customerId path string true Unique Customer Identifier

Example responses

200 Response

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

Responses

Status Code 200

Ok. A payment was initiated.

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

Review Payments

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/customers/{customerId}/payments

Review all your Payments.

Parameters

Name In Type Required Description
customerId path string true Unique Customer Identifier
page query number(int32) false For queries that return arrays of data. Including this optional query parameter causes the set of results to be paginated by this number of pages.
limit query number(int32) false For queries that return arrays of data. Adding this optional query parameter causes the set of results to be split into pages of this size. Default is 50.
currency query string false Adding this optional parameter will retrieve only payments including this buy currency.
from query string false Adding this optional query parameter will retrieve only payments made after or on this date.
to query string false Adding this optional query parameter will retrieve only payments made before or on this date.
paymentstatus query string false Adding this optional query parameter will retrieve only payments having this status.

Example responses

200 Response

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

Responses

Status Code 200

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

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

View a Payment

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

View a Single Payment.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Statements

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

View Statements

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

OK

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

Partner APIs

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

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

Get Monthly Referrals

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/referrals/month

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

  ],
}

Responses

Status Code 200

OK

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

Get Monthly Registrations

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/registrations/month

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

  ],
}

Responses

Status Code 200

OK

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

Get Monthly Commissions

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/commission/month

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

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

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

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

  ],
}

Responses

Status Code 200

OK

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

Get Monthly Trades

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/trades/month

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

Body parameter

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

Parameters

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

Example responses

200 Response

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

  ],
}

Responses

Status Code 200

OK

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

Get Manual Commission

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/affiliates/manual-commission/month

Use the above resource to retrieve commission data manually.

Body parameter

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

Parameters

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

Example responses

200 Response

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

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

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


  ],
}

Responses

Status Code 200

OK

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

References

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

Currencies

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/references/currencies

Get a list of supported currencies for your organisation.

Example responses

200 Response

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

Responses

Status Code 200

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

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

Transaction Purposes

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

GET /v1/references/transaction-purpose

Get a list of transaction purposes.

Example responses

200 Response

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

Responses

Status Code 200

The response will contain an array of purposes.

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

Employment Status

Code samples

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

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

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/references/employment-status',
  method: 'get',

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

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

r = requests.get('https://sandbox.currenciesdirect.com/references/employment-status', params={

}, headers = headers)

print r.json()

GET /references/employment-status

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

Example responses

200 Response

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

Responses

Status Code 200

The response will contain array of employment statuses.

Employment Industry

Code samples

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

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

};

$.ajax({
  url: 'https://sandbox.currenciesdirect.com/references/employment-industry',
  method: 'get',

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

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

r = requests.get('https://sandbox.currenciesdirect.com/references/employment-industry', params={

}, headers = headers)

print r.json()

GET /references/employment-industry

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

Example responses

200 Response

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

Responses

Status Code 200

The response will contain array of employment industries.

Virtual Accounts

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

View a virtual account

Code samples

# You can also use wget
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts/{vbanNumber} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'
Or
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts?currency={currency} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'
Or
curl -X GET https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts?unique-ref={uniqueRefence} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'  
var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

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

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

};

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

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

Get virtual account details.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

OK

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

View virtual accounts

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

Get details of all virtual accounts alloted to the customer.

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

OK

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

Webhooks

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

Subscribe for Updates

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/webhooks

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

Body parameter

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

Parameters

Name In Type Required Description
event_type body string true Event type of webhook subscription. Permitted values: ["CUSTOMER STATUS", "VBAN STATUS"]
endpoint body string true This is the URI of your webservice, which we will call with the updates.

Example responses

200 Response

{
  "id": 1234567
}

Responses

Status Code 200

Ok. You successfully subscribed to a feed.

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

Customer Status Updates

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

Callback Response Body

Body parameter - Active Account

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

Body parameter - In-Active Account

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

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

Parameters

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

Virtual Account Status Updates

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

Callback Response Body

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

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

Parameters

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

Schemas

generalError

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

Properties

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

Third-Party Service Provider

Abstract

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

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

Introduction

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

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

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

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

Terminology

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

Example

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

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

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

The complete process involves the following steps:

Sequence Diagram

  1. Jane logs in to her accountancy.example.com account and asks to collate her tax return. She specifies that she wants to include data from Currencies Direct. The client responds with a request to link to our service.
  2. Before accountancy.example.com can ask Jane to grant it access to her Currencies Direct account, it must first request a one time token to identify the delegation request. To do so, the client sends the following HTTPS request to the server:

    POST /token HTTP/1.1

    Host: www.currenciesdirect.com

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

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

    HTTP/1.1 200 OK

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

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

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

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

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

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

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

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

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

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

  10. Jane approves the request

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

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

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

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

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

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

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

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

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

    The Authorisation returns the access_token.

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

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

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

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

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

Authenticate a TSP

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

Get an OAuth Access Token - TSP

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /auth/oauth/v2/token

To access any of the other API resources you will first need to obtain a token. Make a POST request to this Resource.

If you provided all the Request Body parameters, you should receive an Access Token in the response body.

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Code 200

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

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

Scope of TSP Access Tokens

There are two types of Third-Party Service Provider.

APIs

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

POST /v1/tsp/invitation

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

Body parameter

{
 "redirect_uri":"/v1/tsp/invitation"
}
Name In Type Required Description
redirect_uri body string true Resource owner's consent will be passed to this endpoint.

Example responses

200 Response

{
    "invitation_id": "2fed3391-f03d-433f-be29-41441096a0d8",
    "redirect_url": "http://uat.currenciesdirect.com/CustomerPortal/landingPage.htm?invitationId=2fed3391-f03d-433f-be29-41441096a0d8"
}
Name Type Description
invitation_id string Unique id to identify consent invitation.
redirect_url string Login page url which will be presented to resource owner to login.

Initiate Payment Instructions

Code samples

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

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

};

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

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

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

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

}, headers = headers)

print r.json()

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

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

General Information

Recipient 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

POST /v1/tsp/payments

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

Body parameter

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


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

Parameters

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

Example responses

200 Response

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

Responses

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

Payment Statuses

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

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

Error Codes

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

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

All errors follow the GeneralError schema.

Glossary

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