Getting Started

A typical integration looks like this:

1. Create a gift card for your customer
2. Top up the card (hosted checkout or direct charge)
3. Confirm the payment (webhook or status check)
4. Pay out when you need to move money out (optional)

You'll need an API key from Chapa — see Authentication.

Step 1 — Create a gift card

POST https://api.chapa.link/card
Authorization: Bearer {{API_KEY}}

{
  "phone_number": "+251960724272",
  "currency": "ETB",
  "first_name": "Abebe",
  "last_name": "Bikila"
}

Save the card_number from the response. You'll use it for every payment and payout.

→ Gift Cards

Step 2 — Top up the card

Hosted — send the customer to a checkout page:

{
  "type": "hosted",
  "amount": 500,
  "card_number": "7915786161"
}

Use the checkout_url from the response to redirect the customer.

Direct charge — charge a wallet directly:

{
  "type": "direct-charge",
  "amount": 500,
  "card_number": "7915786161",
  "phone_number": "+251960724272",
  "payment_method": "telebirr"
}

Save link_reference from the response.

See Payments to get a detailed information.

Step 3 — Know when payment is done

Production: set up a webhook URL with Chapa. You'll get a payment.success event when the card is credited.

Testing: poll the status endpoint:

GET https://api.chapa.link/card/payment/{link_reference}/status

To review past activity, list payments or payouts:

GET https://api.chapa.link/card/payments?page=1&limit=15
GET https://api.chapa.link/card/payouts?page=1&limit=15

Step 4 — Payout

Send money to a business, another card, or a bank account. Pick one destination per request:

{
  "card_number": "7915786161",
  "amount": 200,
  "destination_card_number": "8787064900"
}

→ Payouts

Checklist

• Get test and live API keys from Chapa
• Save card_number after creating a card
• Keep the API key on your server
• Set up webhooks before going live
• Test with the test key first