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. |
| 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.
Initialize the Transaction and Get a payment link
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.
Endpoint https://api.chapa.co/v1/transaction/initialize
Method POST
Headers
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.
Redirect the user to the payment link
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.
After the payment
Four things will happen when payment is done (successful):
- We’ll redirect to your set
return__url. Thecallback_urlwill returnstatus, andtx_refafter payment is complete. - We’ll send you a webhook if you have that enabled. You can find more information on Webhooks here.
- 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.
Webhook
Chapa has event listeners that will send a message whenever a payment is successful. You can find more information on Webhooks here.
Redirection
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.
