Reference

Quick answers for things you'll see across all endpoints.

Response format

Success:

{
  "status": "success",
  "message": "Gift card created successfully",
  "data": { }
}

Error:

{
  "status": "error",
  "message": "Gift card not found. No gift card for this card number and business",
  "error": "No gift card for this card number and business"
}

The error field may be a string (as above) or an object for validation failures:

{
  "status": "error",
  "message": "Validation error",
  "error": {
    "amount": "Amount must be greater than or equal to 1"
  }
}

Some errors also include a request_id you can share with Chapa support when debugging.

Base URL

https://api.chapa.link

Amounts

• Send amounts in cent — 100 means 1 ETB in cents.
• Minimum amount is 100 which is 1 ETB.

Currencies

You can create gift cards in: ETB, USD, DJF, UGX.

Payments and payouts use the card's currency automatically.

Gift card status

Payment / payout status

When you check status or list history, status is one of:

• pending — still processing
• success — done
• failed — did not complete

Live and test mode

Your API key determines the environment. Test keys read and write test data; live keys use production data. The same base URL is used for both.

List endpoints include mode on each item (live or test) so you can tell which environment a record belongs to when building dashboards or exports.

Pagination

GET /card/payments and GET /card/payouts return paginated history for your business.

Use page and limit for most integrations. If you send offset in the query string, it is used instead of page.

Response shape:

{
  "items": [ ],
  "total": 42,
  "page": 1,
  "limit": 15,
  "pages": 3
}

Results are ordered newest first.

Service fee

service_fee appears on payment and payout list items and on payment/payout status checks. It is calculated from the transaction amount. Today this is typically 0 unless Chapa configures a fee for your account.

On B2B, bank, and card-to-card payouts you can choose who pays the fee with charge_payer:

When business (B2B/bank) or receiver (card-to-card) pays, the source is debited amount and the destination receives amount - service_fee. When customer (B2B/bank) or sender (card-to-card) pays, the source is debited amount + service_fee and the destination receives the full amount.

References worth saving

List response fields

Payments (GET /card/payments)

Payouts (GET /card/payouts)

Common errors