Testing Mobile

Testing Mobile allows you to validate mobile money payment flows (such as Telebirr, CBE Birr, M-Pesa, etc.) in Test Mode, without charging real wallets.

This helps you test:

• Direct Charge mobile flows
• USSD / PIN / OTP–based authentication
• Webhook delivery for mobile payments
• Verification and error handling

Supported Mobile Payment Methods (Test Mode)

Common mobile methods you can test include:

• telebirr
• cbebirr
• mpesa
• awashbirr
• ebirr

Availability may vary depending on:

• Currency
• Country
• Merchant configuration

Test Mode Requirements

To test mobile payments:

• Use test API keys (CHAPA_TEST_...)
• Ensure the environment is set to test
• Use test phone numbers (no real wallet interaction)

Test Phone Numbers

Success Scenario

Expected Result: Payment succeeds

Insufficient Funds

Expected Result: Payment fails with INSUFFICIENT_FUNDS

User Cancellation

Expected Result: Payment cancelled by user

Timeout / No Response

Expected Result: Payment becomes incomplete

Example Test Flow (Direct Charge)

POST /v2/payments/initialize/direct
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 5000,
  "currency": "ETB",
  "payment_method": "telebirr",
  "customer": {
    "phone_number": "251900000000"
  }
}

Expected Webhook Events

Depending on the test phone number used, you'll receive:

Each webhook includes:

{
  "mode": "test"
}

Use this field to separate test and live processing.

Verification

Always confirm the final result using:

GET /v2/payments/{reference}/verify

Verification results should match the webhook status.

Best Practices

• Test all mobile scenarios before going live
• Handle auth_needed even in test mode
• Build timeout and retry logic
• Keep test data separate from live data

Common Errors

Next Steps

• Testing Cards - Test card payments
• Direct Charge - Initiate mobile payments
• Webhooks - Handle payment events