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
ortarget_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
ortarget_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 currencyCOP
and target currencyUSD
, the rate would be like4000
.
For source currencyUSD
and target currencyCOP
, the rate would be like0.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
fx_rate
field worksIf 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
override_fees
field worksThere 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
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.
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
ortarget_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
ortarget_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 currencyCOP
and target currencyUSD
, the rate would be like4000
.
For source currencyUSD
and target currencyCOP
, the rate would be like0.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
fx_rate
field worksIf 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
override_fees
field worksThere 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
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.