Chapa
Connect Chapa to PayLexer to accept cards, telebirr, M-PESA, CBE Birr and bank transfers from Ethiopian customers in ETB and USD.
Chapa is an Ethiopian payment gateway, founded in 2021 and built for online businesses selling into Ethiopia. Through a single integration, Chapa lets merchants accept local and international cards alongside the mobile money wallets Ethiopian customers actually use, including telebirr, M-PESA, CBE Birr and Coopay-Ebirr, plus direct bank transfers.
Customers complete payment on Chapa's own hosted page, so card details never touch your website.
- Supported Regions (Merchant Accounts): Ethiopia
- Supported Currencies: ETB, USD
This gateway appears in checkout only when the selected currency is ETB or USD.
Supported Features
- Hosted checkout that redirects shoppers to Chapa's secure payment page
- Local and international card payments
- Mobile money through telebirr, M-PESA, CBE Birr and Coopay-Ebirr
- Bank transfers from Ethiopian banks
- Full refunds and partial refunds
- Real-time webhook notifications for payments and refunds, secured with HMAC-SHA256 signatures
- Automatic recording of refunds issued directly inside the Chapa dashboard
- Separate test and live credentials for safe testing
Chapa does not support subscriptions or recurring billing in PayLexer. Chapa has no API for saving a payment method or scheduling future charges, so only one-time payments are available.
Before You Start
Make sure you have:
- Chapa Account – Don't have one? Sign up for Chapa →
- PayLexer Account – Required to configure the integration. Create your account →
- A website where you want to integrate
Looking for a different payment processor? View all supported gateways →
Configuring Chapa
You need a Public Key and Secret Key from Chapa for this integration.
Getting API Credentials
Log in to Chapa
Sign in to your Chapa dashboard.
Choose your environment
Use the Test Mode toggle to switch between environments. Chapa issues a different pair of keys for each, so collect them one environment at a time.
Test keys are prefixed CHAPUBK_TEST- and CHASECK_TEST-. Live keys are prefixed CHAPUBK- and CHASECK-.
Open the API tab
Click your profile icon in the top right, go to Settings, then open the API tab. You will see your Public Key and Secret Key.
Copy both keys
Copy the Public Key and the Secret Key using the copy icon beside each value. Keep the Secret Key private, as it authorizes payments and refunds on your account.
The Encryption Key shown on the same screen is not required. It is only used for direct charge integrations, and PayLexer uses Chapa's hosted checkout, so card details are entered on Chapa's own page and never reach PayLexer.
Adding Credentials to PayLexer
Open PayLexer Dashboard
Log in to your PayLexer dashboard and navigate to Payment Gateways → Chapa.
Enter your credentials
Paste the Public Key and Secret Key you copied from Chapa into the corresponding fields. They are listed in the same order as Chapa's own API tab, so you can copy straight down the page.
Understanding Live/Production and Sandbox Settings:
| Environment | Purpose |
|---|---|
| Live / Production (Mandatory) | Used for real transactions. Cannot be empty, even when testing. |
| Test / Sandbox (Optional) | Used for testing only. No real money is processed. |
How PayLexer selects credentials:
- Debug/Test mode ON → Test credentials are used
- Debug/Test mode OFF → Live credentials are used
Test and save
Click Save to save your configuration and verify your credentials. Click Verify Connection to test the connection.
Chapa rejects a live key used in test mode and a test key used in live mode, so a key saved in the wrong environment will fail verification. Check the key prefix if the connection is refused.
Configuring Webhooks (Mandatory)
Webhooks enable real-time payment updates and significantly improve reliability.
Benefits of Webhooks:
- Instant payment status updates
- Automatic refund processing
Copy your PayLexer webhook URL
On the Payment Gateways → Chapa page in PayLexer, copy the Webhook URL. It is generated for your account and shown as a read-only field.
Open the Webhooks tab in Chapa
In your Chapa dashboard, click your profile icon, go to Settings, and open the Webhooks tab.
Add the URL and a secret hash
Paste the PayLexer webhook URL into the webhook URL field. In the Secret Hash field, enter a random value of your own choosing, then save.
Chapa uses a single webhook URL for your whole account rather than one per payment, and payment confirmations are delivered to it. If this is left blank, orders may stay pending even after a customer has paid.
Add the same secret hash to PayLexer
Back in PayLexer, paste the value you chose into the Webhook Secret Hash field and save. It must match the one saved in Chapa exactly, or notifications will be rejected.
Integrate Chapa to Your Website
If you have already added and configured your site, you can enable Chapa in your existing setup.
Go to Websites
Navigate to Websites in your PayLexer dashboard.
Edit your website
Click the Edit Icon of your added website.
Enable Chapa
Click the checkbox to enable Chapa for the website.
If you haven't added a website yet, Continue to Add Your Website →
Troubleshooting
Best Practices
- Test in sandbox before enabling production, using your Chapa test keys with Debug/Test mode ON
- Save your PayLexer webhook URL and secret hash in Chapa before taking live payments
- Use Chapa's published test cards and test phone numbers, since any other value fails in test mode
- Use real customer email addresses, as Chapa rejects reserved domains such as
.local - Keep your Secret Key private and rotate it in Chapa if you suspect it has been exposed
- Complete Chapa's compliance form early, as live keys are only issued after your business is verified
- Reconcile your PayLexer orders against your Chapa dashboard periodically
FAQs
Still Have Questions?
- Chapa Support: Chapa Support
- PayLexer Support: Contact Support