Transfers between subaccounts

A transfer between subaccounts moves money from one of your users' balances to another — a peer-to-peer payment inside your wallet, a movement between a user's COP and USD accounts, a correction between two balances. Same-currency transfers are a plain ledger movement. When the two subaccounts hold different currencies, Core converts the amount at an exchange rate and the transfer becomes an FX transfer, with two fees you can price: a fixed conversion charge and your margin on the rate.

This flow is part of Core's ledger service. FX transfers must be enabled for the program of the accounts; Mono enables it when you set the program up.

Before you start

You will need:

• A Core API key with the ledger scope.
• Two active subaccounts, of active account holders, belonging to you.
• For FX transfers: the feature enabled for the subaccounts' program, and — if you want to price the conversion — your fee policies for account_to_account_fx and account_to_account_fx_spread. Mono creates the base ones; see Fee policies.
• An idempotency key per transfer.

Same-currency transfers

Send the source subaccount, the destination subaccount and one amount — source_amount or target_amount, the other one null. Both are equal, and the currency must be the one of both subaccounts. Core posts a balanced ledger transaction: a debit on the source and a credit on the destination, instantly. No fees apply.

FX transfers

When the subaccounts hold different currencies, the same request performs a conversion:

1. Send either source_amount (in the source currency) or target_amount (in the destination currency); Core calculates the other one.
2. Optionally send fx_rate. If you leave it out, Core takes the current market rate — the one the FX rates endpoint publishes — and adds your spread on top. If you send it, Core uses it as-is and assumes it already includes your spread.
3. Core prices the two fees below, posts the transaction and returns the amounts, the rate applied and calculated_fees.

The two fees

Both are priced by your fee policies of those types — by program, account holder or account, like any other fee — and both can be replaced for a single transfer through override_fees: fixed and tx_description for the fixed fee, percentage for the spread.

How the amounts are calculated

fx_rate is the rate from the destination currency to the source one — for COP to USD it looks like 4000; for USD to COP, like 0.00025. With the fixed fee in the source currency:

• Given the target amount: source_amount = target_amount × fx_rate + fixed_fee.
• Given the source amount: target_amount = (source_amount − fixed_fee) ÷ fx_rate.

Results are rounded to the decimals of each currency. Without an explicit fx_rate, and a spread of 1% on a market rate of 4000, the rate applied is 4000 × 1.01 = 4040.

What comes back

The response includes calculated_fees, with one entry per fee type and the final amount of each in the source currency. The spread fee is the difference between converting at the applied rate and converting at the market rate — what your user paid for the conversion beyond the market price. These are the amounts to reconcile against; they also appear, with their state and the rule that priced them, in the fees listing.

Steps

1. Look up the two subaccounts and confirm both, and their holders, are active.
2. Decide which amount you fix — what the sender pays or what the receiver gets — and whether you pass your own fx_rate.
3. Call Perform a transfer between ledger accounts with an idempotency key. A 201 returns the transfer; repeating the same key returns the same transfer with a 200.
4. Read calculated_fees and the amounts from the response and show your user what was charged.
5. To find a transfer again by your own reference, use Find a successful subaccount operation.

Next steps

• Fee policies — set the conversion charge and the spread per program, holder or account.
• FX rates — where the market rate comes from.
• Ledger accounting — the bookkeeping every transfer produces.