Chapa Developer Documentation

This documentation explains how to use our Swap API for converting USD to ETB (Ethiopian Birr).

Initiating a Swap

Endpoint: https://api.chapa.co/v1/swap
Method: POST
Authorization: Pass your secret key as a bearer token in the request header to authorize this call.

Body Parameters

Parameter	Required	Type	Description
`amount`	Yes	number	The amount to convert (minimum 1 USD)
`from`	Yes	string	Source currency code (USD)
`to`	Yes	string	Target currency code (ETB)

Important Notes:

The minimum amount for conversion is 1 USD
The maximum allowed amount for swap is $10,000
Current exchange rate is applied at the time of the swap
Swaps are processed immediately and cannot be reversed
The exchanged amount will be added to the business ETB balance

cURL

JavaScript

PHP

Python

Successful Response

{
  "message": "Swap has been made successfully.",
  "status": "success",
  "data": {
    "status": "Success",
    "ref_id": "SWPfSqc5BiwcC",
    "from_currency": "USD",
    "to_currency": "ETB",
    "amount": 1,
    "exchanged_amount": 127,
    "charge": 0,
    "rate": 127,
    "created_at": "2025-04-23T08:50:46.000000Z",
    "updated_at": "2025-04-23T08:50:46.000000Z"
  }
}

Response Parameters

Parameter	Type	Description
`message`	string	Response message
`status`	string	Status of the request (success/failed)
`data.status`	string	Swap status (Success)
`data.ref_id`	string	Unique reference ID for the swap
`data.from_currency`	string	Source currency (USD)
`data.to_currency`	string	Target currency (ETB)
`data.amount`	number	Original amount in source currency
`data.exchanged_amount`	number	Amount received in target currency
`data.charge`	number	Transaction fee (if any)
`data.rate`	number	Exchange rate applied
`data.created_at`	string	Timestamp when swap was created
`data.updated_at`	string	Timestamp when swap was last updated

Failed Response

{
  "message": "Amount must be at least 1",
  "status": "failed",
  "data": null
}

Refer to our Error Codes page for all responses for this request.

Use Cases

Currency Conversion: Convert USD balance to ETB for local transactions
Balance Management: Manage multi-currency balances efficiently
Payment Processing: Convert funds before processing ETB payments

Best Practices

Check Exchange Rates: Exchange rates fluctuate, so check current rates before initiating swaps
Minimum Amount: Ensure the amount meets the minimum requirement of 1 USD
Maximum Limit: Be aware of the $10,000 maximum limit per swap
Irreversible: Remember that swaps cannot be reversed once processed
Balance Verification: Verify your USD balance before initiating a swap

Next Steps

Get Balance - Check your USD and ETB balances
Transfer - Make transfers using your ETB balance
All Transfers - View all your transfers
Error Codes - Handle errors gracefully

Swap

On this page