Skip to main content

​
Overview

Currency Exchange lets you convert a balance from one of your fiat currency wallets to another. The source wallet is debited, the destination wallet is credited at the calculated exchange rate, and both an Exchange From and an Exchange To transaction record are created.
Only fiat currency wallets are supported for currency exchange. Crypto wallets use a separate crypto exchange flow.

​
How exchange rates are determined

The system supports two rate sources, configured per destination currency:
SourceBehaviour
apiLive rate fetched from the configured exchange rate API for the currency pair
localRate calculated from the currency rate values stored in the database
If the API is enabled and the source currency is api, the live rate is used. If the API call fails, the system falls back to the local rate automatically. The exchange rate is locked at the time you reach the confirmation screen and stored as destination_exchange_rate in the session.

​
How to perform an exchange

1

Go to Exchange

Navigate to Exchange from the main menu. The form shows all your fiat wallets that have an active Exchange From fees configuration.
2

Select the source wallet

Choose the currency wallet you want to exchange from. Your current balance is displayed.
3

Select the destination currency

Select the currency you want to exchange to. The list shows all active fiat currencies with an active exchange configuration, excluding the source currency.The live exchange rate and the equivalent amount in the destination currency are shown immediately.
4

Enter the amount

Enter the amount to exchange from the source currency. The system shows:
  • Exchange rate
  • Equivalent amount in the destination currency
  • Fees (percentage + fixed)
  • Total deducted from the source wallet (amount + fees)
5

Review on the confirmation screen

The confirmation screen displays the full breakdown. Review the amounts and rate before proceeding.
6

Enter OTP

An OTP is sent to your registered phone number. Enter the code to authorize the exchange.
7

Exchange complete

The source wallet is debited (amount + fees) and the destination wallet is credited (amount × exchange_rate).If a destination wallet does not exist yet for the target currency, one is created automatically.

​
Fee structure

Fees are applied to the source currency amount based on the Exchange From fees configuration: 
percentage_fee = amount × (charge_percentage ÷ 100)
total_fees     = percentage_fee + charge_fixed
total_deducted = amount + total_fees
The destination wallet receives amount × exchange_rate. Fees do not reduce the destination amount.

​
Transaction records

A successful exchange creates two transaction entries:
RecordTypeUserAmount
Exchange FromExchange_FromYour account-(amount + fees)
Exchange ToExchange_ToYour account+(amount × rate)
Both records reference the same CurrencyExchange entry via transaction_reference_id.

​
Transaction limits

Minimum and maximum exchange amounts are set per source currency by the administrator. If the amount is outside the configured range, the exchange is blocked before you reach the confirmation screen.
The balance check compares amount + fees against your source wallet balance. If total deducted exceeds your balance, the exchange is blocked with an insufficient funds error.

Digital Wallet

View balances across all your currency wallets.

Deposits

Fund a wallet before exchanging.

Send Money

Transfer the exchanged funds to another user.

Withdrawals

Withdraw the exchanged balance to an external account.

Build docs developers (and LLMs) love

Get started for freeTalk to us