Chapa Developer Documentation

Initiate a payment using a specific payment method without showing multiple options.

Direct Charge allows you to initiate a payment using one specific payment method only, without showing multiple options or allowing fallback methods.

This is useful when:

You already know the customer's payment channel (e.g. Telebirr)
You want a fast, focused checkout flow
You're building USSD, mobile-money, or tightly controlled payment experiences

Unlike hosted checkout, Direct Charge does not present a payment method selector.

When to Use Direct Charge

Use Direct Charge if:

You want to force Telebirr-only, CBE Birr-only, etc.
You're building a mobile or USSD-driven flow
You want tighter control over authentication steps (PIN, OTP, USSD)

Do NOT use Direct Charge if:

You want users to choose between multiple payment methods
You want a fully hosted checkout experience

Endpoint

POST /v2/payments/initialize/direct
Host: api.chapa.co

Authentication

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <PRIVATE_API_KEY>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Prevent duplicate charges on retry

Request Body

Required Fields

Field	Type	Description
`amount`	number	Total amount to charge
`currency`	string	ISO currency code (`ETB`, `USD`, `UGX`, `DJF` — availability depends on method)
`payment_method`	string	Single payment method
`customer.phone_number`	string	Customer phone number (required)

Optional Fields

Field	Type	Description
`customer.first_name`	string	Customer first name
`customer.last_name`	string	Customer last name
`customer.email`	string	Customer email
`meta`	object	Custom metadata

Supported Payment Methods (Examples)

telebirr
mpesa
cbebirr
awashbirr
ebirr
enat_bank

Supported methods vary by country, currency, and business configuration.

Example Request

POST https://api.chapa.co/v2/payments/initialize/direct
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 25000,
  "currency": "ETB",
  "payment_method": "telebirr",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "251722927727"
  },
  "meta": {
    "order_id": "ORD-99887",
    "notes": "Direct charge for premium subscription"
  }
}

Example Response

{
  "status": "success",
  "message": "Payment successfully initiated with telebirr",
  "data": {
    "auth_type": "ussd",
    "request_id": "IZgAoomVWDl1hLlL9luAhI7YOAuw6wqDI0b0gRqL2U9n8AcPpWtsdYdmuUetQXlLYMjSXp5Slo2y75ZrmRFowmHbO9UP1sBOS",
    "chapa_reference": "CHvJ9DZ8r6zKW",
    "payment_status": "PENDING",
    "created_at": "2025-11-07T12:00:00Z",
    "expires_at": "2025-11-07T12:01:00Z"
  }
}

Understanding the Response

Field	Description
`auth_type`	Required authentication method (`ussd`, `pin`, `otp`, `redirect`)
`request_id`	Provider-side transaction identifier
`chapa_reference`	Chapa payment reference
`payment_status`	Initial status (`PENDING`)
`expires_at`	Time limit for completing authentication

What Happens Next?

Depending on auth_type:

Auth Type	Customer Action
`ussd`	Customer dials a USSD code
`pin`	Customer enters PIN
`otp`	Customer receives OTP
`redirect`	Redirect user to provider page

Final status updates are delivered via:

Webhooks (recommended)
Verification endpoint

Verification (Required)

After initiation, always verify the payment before fulfillment:

GET /v2/payments/{reference}/verify

Only treat the payment as successful if verification confirms status == success.

Best Practices

Always verify payment after initiation
Store chapa_reference and request_id
Handle authentication timeouts gracefully
Use webhooks for final payment state
Use Idempotency-Key for safe retries
Do not retry blindly without idempotency

Common Errors

HTTP	Error Code	Description
400	`INVALID_VALUE`	Invalid payment method or currency
400	`INVALID_FORMAT`	Invalid phone number
409	`INVALID_STATE`	Duplicate transaction reference
500	`PROCESSING_FAILED`	Direct charge system failure

Next Steps

Authorize Payment - Complete authentication
Verify Payments - Confirm payment status
Webhooks - Handle payment events

Initiate Payment