Migration guide: moving from the Settlement model to the Balances model

To make sure you’re always receiving the best possible service, Currencycloud is making some important changes to our platform and the way we handle your funds.

Simply put, we are migrating all our clients from a Settlement model (non-cash manager) onto a new and improved Balance model (Cash manager). This guide is aimed at providing you with all the information you’ll need to have a smooth and successful migration including;

  • How the Balances model works
  • How it will benefit our clients
  • What API integrations will be affected
  • Which APIs are being deprecated
  • What new APIs you’ll need to use
  • What needs to happen before the migration deadline
What is changing?

We are moving all clients away from the legacy Settlement model (non-cash manager)  onto a new Balances model (Cash manager). This means you will no longer be required to directly settle individual conversions (or groups of conversions) and instead move into a more flexible, multi-currency balance driven environment.

How does the Balances Model work?

Conversions and payments will be executed on the defined dates as soon as there are sufficient funds on the relevant account balances. When funding a balance there is no need to reference a different conversion or settlement every time, the only reference required is the account reference, then the funds will be deposit on the right currency balance.

How does this benefit me?
  • Ability to pre-fund your Currencycloud Accounts and hold funds on balance for future use meaning that conversions and payments no longer have to be linked
  • Faster conversions and payments; conversions and payments will be executed on your defined dates as soon as sufficient funds are available. This will happen automatically throughout the day when the balance is funded
  • Better user experience as we improve efficiencies and processes such as what happens when a payment fails.
  • No need to place same-currency trades
  • If you are using our Global Collections functionality, the process of receiving funds in becomes even more efficient and fluid.
When are the changes happening?

We will be deprecating our Settlement (non-Cash Manager) APIs on 31st July 2019.

What APIs are being deprecated?:

As part of this migration, Currencycloud will be deprecating the following Settlement API calls; :

What are the New APIs you’ll need to integrate?:


The balances APIs provide information on the amount held within a single currency balance (/v2/balances/{currency}) or across all the balances of an account (/v2/balances/find).


Any action  performed on the platform that affects or changes a currency account balance (i.e making a conversion or payment) is associated with one or more transactions. A transaction is essentially when either a debit or a credit action is applied on a currency balance.

Example: When a conversion is executed, a debit transaction is applied on the sell currency balance and a credit transaction is applied on the buy currency balance. Both these transactions are then linked to the relevant conversion.


What changes in practical terms:

Using Settlements APIs required you to:

  • From API perspective:
    • Create conversion
    • Create Beneficiary
    • Create Payment linked to Conversion using optional conversion_id param
    • Create Settlement
    • A Conversion to Settlement
    • Release Settlement
  • From an Operational perspective:
    • You send Currencycloud the exact amount of sold currency using unique (different) Settlement ID each time
    • Currencycloud process all Conversions attached to the Settlement
    • Currencycloud processes all Payments attached to the Conversions
    • If Payments fail, bought funds are returned to the Conversion and a new payment has to be created and linked to the existing conversion

Using Balances APIs allows you to:

  • From an API perspective
    • Create standalone Conversions
    • Create standalone Payments to Beneficiaries
  • From an Operational perspective
    • You (or your end customers) send funds to Currencycloud to top balances held on your (or their) behalf by referencing your (or their) existing Account ID
    • Conversions and Payments are processed automatically from an available balance