Swap
Convert funds from one currency to another within your Chapa account.
Swap refers to converting funds from one currency to another within your Chapa account before using them for payments, payouts, or settlements.
This feature is typically used when:
- You collect payments in one currency (e.g. USD)
- You need to pay out or settle in another currency (e.g. ETB)
- You manage multi-currency balances across regions
Availability of Swap depends on your business configuration and enabled currencies. Not all accounts or currency pairs may support swapping.
How Swap Fits into the Flow
A typical swap workflow looks like this:
- Funds are available in your Chapa balance (e.g. USD)
- You initiate a swap to convert funds to another currency
- The converted balance becomes available
- You use the new balance for:
- Payouts
- Settlements
- Internal transfers
Swap happens before money movement (payments or payouts).
Key Concepts
Source Currency
The currency you currently hold (e.g. USD).
Target Currency
The currency you want to convert into (e.g. ETB).
Exchange Rate
The rate applied at the time of the swap.
Rates may:
- Be dynamic
- Include fees or spreads
- Vary based on market conditions
Expected Swap Properties
While swap APIs may vary by setup, a swap operation generally includes the following properties:
| Field | Description |
|---|---|
from_currency | Currency being converted |
to_currency | Currency being received |
amount | Amount to swap |
rate | Applied exchange rate |
converted_amount | Final received amount |
status | pending, processing, completed, failed |
created_at | Swap initiation time |
completed_at | Swap completion time (if completed) |
Status Lifecycle
| Status | Meaning |
|---|---|
pending | Swap initiated |
processing | Conversion in progress |
completed | Swap completed successfully |
failed | Swap failed |
Status updates are usually delivered via:
- Dashboard
- API polling (if supported)
- Webhook events (if enabled)
Best Practices
- Always confirm supported currency pairs before swapping
- Validate available balance before initiating a swap
- Treat swap as asynchronous unless explicitly stated otherwise
- Store swap references for reconciliation and reporting
- Handle rate differences and rounding carefully
Error Handling
Common swap-related errors may include:
| Error Type | Meaning |
|---|---|
INVALID_VALUE | Unsupported currency pair |
INSUFFICIENT_BALANCE | Not enough funds to swap |
OPERATION_NOT_SUPPORTED | Swap not enabled for business |
PROCESSING_FAILED | Swap engine error |
Important Notes
- Swap is not a payment or payout — it's an internal balance operation
- Fees (if any) are applied during conversion
- Swap availability and rates may differ between Test and Live mode
- Final converted amount may vary slightly due to rounding
Next Steps
- Payout - Send funds after swapping
- Bulk Payout - Send multiple payouts
- Bank List - Get supported banks