​
Overview

HOST Pay uses a configurable base currency (e.g., USD or SLE) for all wallet balances and internal transactions. For applications using USD as their base currency, the system automatically handles conversion for Sierra Leone’s mobile money transactions.

​
How It Works

​
Configurable Base Currency

Each application in HOST Pay defines its own base currency (defaulting to USD) which is used for all internal accounting. This means:
  • ✅ Wallet balances are stored in the base currency
  • ✅ Peer-to-peer transfers are processed in the base currency
  • ✅ Transaction history shows amounts in the base currency
  • ✅ API responses return balances in the base currency

​
Mobile Money Transactions: SLE Input

When users make mobile money deposits or withdrawals through Monime (Orange Money, Africell Money), they enter amounts in Sierra Leone Leones (SLE). If your application’s base currency is different (e.g., USD), HOST Pay performs an automatic conversion.

Deposits

User enters SLE amount → System converts to Base Currency → Wallet credited

Withdrawals

User requests SLE amount → System converts from Base Currency → Withdrawn in SLE

​
Conversion Process

1

User Initiates Transaction

User enters the amount in Sierra Leone Leones (SLE) for their mobile money transaction
2

Real-time Exchange Rate

HOST Pay fetches the current exchange rate between the transaction currency and your application’s base currency from a reliable source
3

Automatic Conversion

The system converts the SLE amount to the application’s base currency using the current exchange rate
4

Transaction Processing

The converted amount is used for the wallet transaction
5

Balance Update

The wallet balance is updated in the base currency and displayed to the user

​
Exchange Rate Updates

Exchange rates are fetched in real-time for each transaction to ensure accuracy and fairness for both deposits and withdrawals.
HOST Pay uses reliable financial data providers to fetch current exchange rates. The exact rate used is included in each transaction response.
Every mobile money transaction response includes the exchange rate used, so users can verify the conversion calculation.
In Test Mode, a fixed exchange rate may be used for consistent testing. Check your test environment configuration for the current test rate.

​
Card Payments (Stripe)

Card payments through Stripe are typically processed in USD. If your application’s base currency is different, the amount will be converted and credited to the wallet in the base currency: 
{
  "wallet_id": "wallet_abc123",
  "amount": 10.0, // USD amount
  "currency": "USD",
  "payment_method": "card"
}
Users see USD amounts when paying with credit/debit cards via Stripe.

​
Peer-to-Peer Transfers

All wallet-to-wallet transfers happen in the application’s base currency: 
{
  "sender_wallet_id": "wallet_abc123",
  "recipient_username": "john_doe",
  "amount": 5.0, // USD
  "currency": "USD"
}
There is no currency conversion for P2P transfers since both wallets use the same base currency within a single application.

​
API Implementation

​
Specifying Currency in Requests

When making API calls for mobile money transactions: 
// Mobile money deposit (user enters SLE)
const depositResponse = await fetch(
  "/api/v1/transactions/wallet/mobile-money-deposit",
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
      "secret-key": "YOUR_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      wallet_id: "wallet_abc123",
      amount: 100000, // Amount in SLE
      currency: "SLE", // Specify currency
    }),
  }
);

​
Best Practices

When showing transaction details, display both the original SLE amount and the converted base-currency amount for transparency.
Save the exchange rate used for each transaction in your database for record-keeping and reconciliation.
Inform users that exchange rates fluctuate and the final base-currency amount may vary slightly from estimates.
Use Test Mode to verify your currency conversion logic before going live with real money.

​
Common Questions

Yes, the base currency is configurable per application. You can set it to USD, SLE, or other supported currencies during application setup. Internal accounting will be performed in your chosen currency.
The exchange rate is locked at the moment the transaction is initiated. The rate will not change even if the transaction takes time to complete.
Currency conversion is included in the transaction. Check your application’s fee configuration for any transaction fees that may apply.
Yes, your application should fetch and display the current exchange rate and converted amount before the user confirms the transaction.

Mobile Money Deposits

Learn how to test mobile money deposits

Webhooks

Handle transaction events with webhooks

Test Mode

Understand test and live environments

API Reference

Complete API documentation