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 yes A customer’s email. address
amount yes The amount you will be charging your customer.
first_name yes A customer’s first name.
last_name yes A customer’s last name.
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[tiitle] 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.

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 which will innately display the checkout.

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.chapa.co/v1/transaction/initialize',
  'headers': {
    'Authorization': 'Bearer CHASECK-AAAAAAAAAAAAAAAAAAA'
  },
  formData: {
    'amount': '100',
    'currency': 'ETB',
    'email': 'abebe@bikila.com',
    'first_name': 'Abebe',
    'last_name': 'Bikila',
    'tx_ref': 'tx-myecommerce12345',
    'callback_url': 'https://chapa.co',
    'customization[title]': 'I love e-commerce',
    'customization[description]': 'It is time to pay'
   
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

And you will reget a response like this:

{
    "message": "Hosted Link",
    "status": "success",
    "data": {
        "checkout_url": "https://checkout.chapa.co/checkout/payment/27291184910"
    }
}

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 callback__url with 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 an email receipt to your customer if the payment was successful (unless you’ve disabled that).
  4. 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.

Initialize Transaction

When a user clicks on the payment button, it will initialize a transaction by creating a POST request to our API. Users will have to provide their email, amount and any other information that is required for the API call to be successful.

If the API call is successful, the user will be redirected to the authorization URL, and the user wil be able to add their payment information to complete the transaction.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.chapa.co/v1/transaction/initialize',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('amount' => '100','currency' => 'ETB','email' => 'abebe@bikila.com','first_name' => 'Abebe','last_name' => 'Bikila','tx_ref' => 'tx-myecommerce12345','customization[title]' => 'I love e-commerce','customization[description]' => 'It is time to pay'),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer CHASECK-AAAAAAAAAAAAAAAAAAAAA'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Overview
Verify Payments
Next →