Perform a transfer between ledger accounts

Transfer funds smoothly between any two of your subaccounts

General considerations

• This endpoint could be only used for accounts with type subaccount.
• Both payer and receiving accounts should be active.
• The associated account holders should also be active.

Considerations for same currency transfers

• You can specify either source_amount or target_amount, the other field should be set to null. It will be set equal to the given amount.
• The currency code of the amount should be equal to the payer and receiving accounts' currency code.

Considerations for transfers with different currencies

• You can specify either source_amount or target_amount, the other field should be set to null. It will be calculated according to the given amount, fx_rate, and configured fees.
• The currency code of the source_amount should be equal to the payer account currency code.
• The currency code of the target_amount should be equal to the receiving account currency code.
• The fx_rate is the conversion rate from target currency to source currency For example, with source currency COP and target currency USD, the rate would be like 4000. For source currency USD and target currency COP, the rate would be like 0.00025. The rate includes any FX markup configured (or overridden in the request).

How the amounts are calculated

If given target amount

source_amount = target_amount * fx_rate + fixed_fee (rounded to the appropriate number of decimal places)

If given source amount

target_amount = (source_amount - fixed_fee) / fx_rate (rounded to the appropriate number of decimal places)

How the fx_rate field works

If the fx_rate field is not given, it's calculated by using the current marked rate (as returned by the FX rates endpoint) and adding the spread (FX markup). For example, for a market rate of 4000 and a spread of 1%. fx_rate will be 4000 * (1 + 0.01) = 4040.

If fx_rate is given, it's assumed to include the spread already, so the given rate won't be modified in any way.

How the override_fees field works

There are two fees that apply to this operation:

• A fixed amount fee named account_to_account_fx, in the currency of the source amount
• A percentage fee named account_to_acount_fx_spread, included in the conversion rate

These fees are configured in the system but can be overridden for individual requests by passing them in override_fees.

For account_to_account_fx, the fixed and tx_description fields can be provided to override the defaults. For account_to_account_fx_spread, percentage can be overridden.

What is returned in calculated_fees

For each supported fee (account_to_account_fx and account_to_account_fx_spread), a fee object is returned in calculated_fees that contains the final amount of the fee. This amount is always in the currency of the source amount and represents how much was charged for the operation. The spread fee is calculated from the difference in rates between the actual conversion rate (fx_rate) and the market rate.