API Overview
Choose a payment flow, send payouts, and manage Chapa API v2 resources.
Chapa API v2 provides hosted checkout, direct and inline wallet charges, payouts, split payments, refunds, and balances.
New integration? Follow the Quick Start. Migrating an existing integration? Read the Migration Guide.
Choose a payment flow
| Flow | Use it when | Authentication |
|---|---|---|
| Hosted Checkout | Customers should pay on Chapa's checkout page | Private key on your server |
| Direct Charge | Your backend charges a specific wallet method | Private key on your server |
| Inline Charge | Your browser checkout initiates a wallet charge | Public key |
All flows require server-side payment verification before fulfillment. API operation success and payment completion are separate: check data.status === "SUCCESS", the amount, currency, and merchant reference.
API conventions
- Base URL:
https://api.chapa.global. - Amounts and fees are integer cents. Creation requires a minimum amount of
100where applicable. - Merchant references are at most 20 characters.
- Payment, payout, and refund creation requires
Idempotency-Key. Reuse the key for retries. - List endpoints return cursor pagination. The collection includes
limit(default10), but does not enumerate cursor request parameters. - Banks and payment methods return arrays in
data.
See API Keys and Environments before sending requests.
Follow a resource from creation to verification
- Split payments: Create a recipient, then set payment split rules.
- Payouts: Create a payout, send a batch, or transfer to another merchant. Use Payout Banks for destination slugs.
- Refunds: Create a full or partial refund, then verify it.
- Reconciliation: List Payments, List Payouts, List Refunds, and Balances.
Build the surrounding integration
Use Webhooks for notifications, Error Codes for failures, and Security Guide for server-side handling. Dashboard setup and access management are grouped under Dashboard. Reporting, Security, and Disputes have dedicated sections; testing and SDK pages are grouped under Reference.