Authentication
Send your API key on every request:
Authorization: Bearer {{API_KEY}}
Content-Type: application/jsonCall Link App from your server only. Do not put the API key in a mobile app or website.
Getting an API key
Request a test key and a live key from Chapa when you onboard. Each key is tied to your merchant account.
Test vs live
Both use the same base URL:
https://api.chapa.link| Key | Use for |
|---|---|
| Test key | Building and testing your integration |
| Live key | Real customers and real money |
Data from test does not appear when you switch to live.
List endpoints (GET /card/payments, GET /card/payouts) include mode on each item (live or test) so records always reflect the key you used.
What your key can access
- Gift cards — create, list, update, cancel
- Payments — top up, list history, check status
- Payouts — initiate, list history, check status
Common errors
| Status | Message | What it usually means |
|---|---|---|
401 | Unauthorized | Missing or wrong API key |
401 | Token expired | Key has expired — request a new one from Chapa |
403 | Forbidden | Key is inactive or not set up for the gift card API |
403 | API key must be linked to a business_id | Token is missing a business_id — contact Chapa |
{
"status": "error",
"message": "Unauthorized",
"error": "Unauthorized"
}{
"status": "error",
"message": "Forbidden",
"error": "API token cannot create gift cards"
}{
"status": "error",
"message": "API key must be linked to a business_id. Set user_api_tokens.business_id for this token",
"error": "Set user_api_tokens.business_id for this token"
}These errors apply to every Link App endpoint before your request is processed.