API Reference

Our comprehensive API documentation and guides help you explore our products and features, helping to get you integrated with us as soon as possible.

The integration guides provide step-by-step instructions for our most common use cases and once you’ve registered for a developer account and received your API key, you can login to make live API requests in our demo environment.

collect

Find Funding Accounts

Gets details of the Standard Settlement Instructions (SSIs) that can be used to settle and collect funds in each available currency.

Get Sender Details

Returns a JSON structure with details of the sender of funds.

Emulate inbound funds

Triggers a production-like flow for processing funds, topping up CM balance or rejecting the transaction without topping up CM balance. This resource is only available in the Currencycloud Demo environment; it is not implemented in the Production environment.

convert

Create Conversion

Creates a new conversion. Returns the details of the created conversion on success.

Get Conversion

Gets a conversion record for the provided unique ID.

Find Conversions

Finds conversions based on search parameters. If no search parameters are provided, all conversions under the house account are returned.

Quote Conversion Cancellation

Gets a quote of the projected cost to cancel a conversion identified by a provided unique ID {id}.

Cancel a Conversion

Cancels the conversion identified by the provided unique ID {id}.

Quote Conversion Date Change

Gets a quote of the projected cost to change the date of a conversion identified by a provided unique ID {id}.

Conversion Date Change

Changes the date of the conversion identified by the provided unique ID {id}.

Retrieve Profit / Loss

Returns the information of any actions related to a conversion that have generated profit or loss, including the profit or loss amount.

Split Preview

Gets a preview of the details of each part of a split conversion specified by the provided unique conversion ID {id}.

Conversion Split

Splits the conversion specified by the unique ID {id}. Upon success, it returns the details of the parent and new child conversions.

Conversion Split History

Returns the history of executed conversion splits, specified by a unique conversion ID {id}.

Get Basic Rates

Gets indicative foreign exchange rate information for one or more currency pairs in a single request.

This endpoint is intended to provide an indication of the rate available in the market and can support requests for multiple currency pairs, so is good for polling requirements such as live FX ticker widgets. This endpoint should be used where speed, availability and the ability to request multiple currency pairs is important.

Get Detailed Rates

Gets a detailed, tradeable rate quote to convert money from one currency to another. The quotation provided will be based on the spread table of the authenticated user. There is also the option to provide a specific date for the conversion to occur.

This endpoint provides a current tradeable rate for a single currency pair. It should be used as the start of the flow before a conversion is booked. This endpoint should be used where accuracy is the most important aspect, such as when a trade is about to be booked.

manage

Login

Authenticates and authorizes a user to the Currencycloud API.

Submit a login ID and API key for a Currencycloud account, you can register for and API key here. A temporary authentication token is returned following a succesful login.

The authentication token is required to make requests to all other endpoints in the Currencycloud API. Tokens expire after 30 minutes of inactivity.

Token requests are limited to 60 calls per minute.

For security, Currencycloud accounts are disabled when four unsuccessful login attempts are made within a short period. In these circumstances, account holders must contact support to reactivate their account.

Logout

Authentication tokens expire automatically after 30 minutes of inactivity. If a session is no longer required, it is good security practice to retire its authentication token early rather than leave it to time out.

Create Account

Creates a new sub-account. Returns the new account entity on success.

Get Account

Gets an account or sub-account owned by the authenticated user.

Update Account

Updates a sub-account owned by the authenticated user. The updated account entity is returned on success.

Get Authenticating Account

Gets the authenticated user's main account.

Find Accounts

Returns account and any sub-accounts owned by the authenticated user. Optionally filter by account status and other criteria.

Get the Payment Charges Settings for a given account

Retrieves the Payment Charges Settings for the given account.

Manage Account Payment Charges Settings

Manage a given account's Payment Charge Settings (enable, disable, set as default).

Get Balance

Gets the balance for a currency from the account of the authenticated user.

Find Balances

Searches for currency balances in the main account or a sub-account owned by the authenticated user.

Top Up Margin Balance

Tops up the margin balance.

Get Authenticating Contact

Gets the contact record for the authenticated user.

Find Contacts

Returns contacts that match the parameters.

Get Contact

Gets the contact for the given ID.

Update Contact

Updates an existing contact. Returns the updated contact entity on success.

Create Contact

Creates a new contact and attaches it to a sub-account. Returns the new contact entity on success.

Generate HMAC Key for Contact

Generates a new HMAC key for the current contact.

Find Bank Details

Returns the related bank details for the given account reference.

Get Beneficiary Requirements

Returns the information that is required to make payments to beneficiaries in specified currencies and countries.

Get Conversion Dates

Provides a list of upcoming non-trading dates, such as weekends or public holidays, for a specified currency pair. Common use cases include situations where this information needs to be provided, or for planning upcoming conversion bookings.

Many currencies are triangulated; this means that holidays affecting the intermediary currency, as well as the sale and purchase currencies, will impact transactions. Find out more at our support article.

Get Available Currencies

Gets a list of all currencies that can be traded on the Currencycloud platform.

Get Payer Requirements

Returns the payer information you need to provide to create a payment. Requirements vary depending on the location of the payer, the type of payment to be made (priority or regular), and other factors.

Get Payment Dates

Gets a list of invalid payment dates for a given currency covering a two months period from the start_date specified. A payment date is when a payment will be executed by Currencycloud. Payments cannot be made on some days, for example when banks are closed.

Get Payment Fee Rules

Gets the payment fee information set up for the account / payment type provided.

Get Payment Purpose Codes

Gets a list of payment purpose codes for a given currency and entity type. When initiating cross-border payments, the central bank of the country may require a purpose to be included with your transaction in order for your payment to be accepted and processed. If a payment purpose code is required but not provided, your payment may be delayed or rejected by the beneficiary bank.

Get Settlement Accounts

Gets settlement account information - a list of accounts that require funding in order to allow for outstanding transactions to be processed.

Generate Conversion Report

Returns a JSON structure with details of the conversion report requested.

Generate Payment Report

Returns a JSON structure with details of the payments report requested.

Find Report Requests

Searches for report requests made. Returns a JSON structure with details of matching report requests.

Retrieves a Report Request with the given ID

Searches for a report by ID. Returns a JSON structure with details of the specified report request.

Find Transactions

Search for transactions.

Get Transaction

Gets a transaction record.

Find Withdrawal Account

Lists all withdrawal accounts assigned to an account.

Pull Funds From Withdrawal Account

Submits an ACH pull request from a specific withdrawal account. The funds will be pulled into the account the specified withdrawal account is related to.

pay

Find Beneficiaries

Returns beneficiaries attached to the account or any sub-account owned by the authenticated user.

Get Beneficiary

Gets a beneficiary with the given ID.

Update Beneficiary

Updates an existing beneficiary. Returns the updated beneficiary entity on success.
Please note that it's not possible to change a beneficiary's entity type (company or individual) by an update. To achieve this, you should create a new beneficiary.

Create Beneficiary

Creates a new beneficiary. Returns the new beneficiary entity on success.

Delete Beneficiary

Delete a beneficiary associated with a sub-account. If the deletion is successful, the beneficiary's final state is returned.

Validate Beneficiary

Validates a new beneficiary's bank details, without actually creating a record of the beneficiary. On success, returns an object that represents the entity that would be created if the beneficiary was saved.

Create Payment

Submits a payment. On success, returns the new payment record. Use the Get Payer Requirements endpoint to find out what payer information needs to be provided.

Find Payments

Searches for payment records.

Get Payment

Gets a payment record.

Update Payment

Updates a payment. On success, returns the updated payment entity.

Get Payment Confirmation

Gets confirmation for a given payment.

Get Payment Submission

Gets the MT103 information for a SWIFT payment.

Authorise Payment

Authorises a payment pending authorisation.

Delete Payment

Delete a payment. On success, returns the final payment record state.

Get Payment Tracking Information

Gets the tracking information for a payment.

Assign Payment Fee

Assigns a payment fee table to a specific sub-account.

Get Payment Delivery Date

Gets payment delivery date.

Get Payment Fees

Gets the payment fee tables for the current authenticated account.

Get Quote Payment Fee

Gets the calculated quote for the fee that will be applied against a payment.

Unassign Payment Fee

Unassigns the payment fee tables for a specific sub-account.

Validate Payment

Validates the details of a new payment without creating a record of the payment. On success, returns an object containing a string validation_result with value "success".

Get Payer

Get a payer record.

Create Transfer

Transfers funds from one account to another. No currency conversion is performed, so the sending and receiving accounts must hold money in the same currency.

Get Transfer

Returns the money transfer record with the given ID.

Find Transfers

Searches for transfer records that meet the given criteria.

Cancel Transfer

Requests that a transfer be cancelled.