Accept Payment

This document covers payment transaction and its establishment with the help of our API, Javascript library, Popup Js or our SDKs.

When accepting a payment, a transaction is established and following every transaction carries out a complete payment method.

Collecting Customer Information

Before carrying out the transaction, a user must provide required information such as full name, email address, the amount to transfer, etc. Below you will find a list of parameter needed:

Parameter Required Description
key yes This will be your private key from Chapa. When on test mode use the test key, and when on live mode use the live key.
email no A customer’s email. address
amount yes The amount you will be charging your customer.
first_name no A customer’s first name.
last_name no A customer’s last name.
phone_number no The customer’s phone number.
tx_ref yes A unique reference given to each transaction.
currency yes The currency in which all the charges are made. Currency allowed is ETB and USD.
callback_url no Function that runs when payment is successful. This should ideally be a script that uses the verify endpoint on the Chapa API to check the status of the transaction.
return_url no Web address to redirect the user after payment is successful.
customization[title] no The customizations field (optional) allows you to customize the look and feel of the payment modal. You can set a logo, the store name to be displayed (title), and a description for the payment.

Phone number is a recent addition to the parameter that was added upon the dev community’s request. It is not required, but if you pass phone_number, it must be 10 digits, so it should be in 09xxxxxxxx or 07xxxxxxxx format.

Once all the information needed to proceed with the transaction is retrieved, the action taken further would be to associate the following information into the javascript function(chosen language) which will innately display the checkout.

Method POST


  • Authorization * : Pass your secret key as a bearer token in the request header to authorize this call.

Refer to our Error Codes page for all responses for this request.

Now all you need to do is redirect your customer to the link returned in data.checkout_url, and we’ll display our checkout modal for them to complete the payment.

Alt for image

After the payment

Four things will happen when payment is done (successful):

  1. We’ll redirect to your set return__url. The callback_url will return status, and tx_ref after payment is complete.
  2. We’ll send you a webhook if you have that enabled. You can find more information on Webhooks here.
  3. We’ll send you an email notification (unless you’ve disabled that).

N.B: On your server, you should handle the redirect and always verify the final state of the transaction.

Verify Transaction

It is important to verify the transaction and confirm its status. Here is how you can Verify a Transaction.


Chapa has event listeners that will send a message whenever a payment is successful. You can find more information on Webhooks here.


The Initialization transaction API is used for redirection. When users go for check out, it generates a link that redirects them to the payment page. Once the payment has been made the users are redirected back to the website.

Test Mode Vs Live Mode
Verify Payments
Next →