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 public 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.
ref no A unique reference given to each transaction.
currency no The currency in which all the charges are made. Currency allowed is Birr.
channels no A collection of payment methods that the customer has access to such as banks or credit cards.
metadata no Any additional information that may be relevant in the transaction will be available here.
label no This will take the place of the customer’s email as displayed on the checkout form.
callback no Once a payment is successful this method will be carried out. Should make use of the API to check the status of the transactions.
onClose no This function will be called out if a customer closes the payment window without making any payment.
onBankTransferConfirmationPending no This function is called if a customer closes the checkout before we receive the bank transfer.
For Split Payments    
subaccount yes Unique reference for the subaccount that owns the payment.
transaction_charge no A linear rate that is charged to the subaccount for any transaction made.
bearer no Choosing between account and subaccount on which will hold the transactions. The default is set on account.
For subscription    
plan yes This is brought about by creating a plan in return making the payment a subscription payment.
quantity no Multiplies the amount made by the plan created. above.

Customer information is stored in the database enabling an effortless retrival. An example of a customer’s information stored is shown below:

const paymentForm = document.getElementById('paymentForm');
    paymentForm.addEventListener("submit", payWithchapa, false);
    function Chapa(e) {
      e.preventDefault();
      let handler = ChapaPop.setup({
        key: 'pk_test_xxxxxxxxxx', // Replace with your public key
        email: document.getElementById("email-address").value,
        amount: document.getElementById("amount").value * 100,
        ref: ''+Math.floor((Math.random() * 1000000000) + 1), // generates a pseudo-unique reference. Please replace with a reference you generated. Or remove the line entirely so our API will generate one for you
        // label: "Optional string that replaces customer email"
        onClose: function(){
          alert('Window closed.');
        },
        callback: function(response){
          let message = 'Payment complete! Reference: ' + response.reference;
          alert(message);
        }
      });
      handler.openIframe();
    }

Initialize the Transaction

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 paymentForm = document.getElementById('paymentForm');
    paymentForm.addEventListener('payWithchapa, false);
    function payWithchapa() {
      var handler = chapaPop.setup({
        key: 'YOUR_PUBLIC_KEY', // Replayour public key
        email: document.getEle('email-address').value,
        amount: document.getElementById('avalue * 100, // the amount vmultiplied by 100 to convertlowest currency unit
        currency: 'ETB', 
        ref: 'YOUR_REFERENCE', // Replace reference you generated
        callback: function(response) {
          //this happens after the paycompleted successfully
          var reference = response.reference;
          alert('Payment complete! Referenreference);
          // Make an AJAX call to yourwith the reference to vertransaction
        },
        onClose: function() {
          alert('Transaction was not comwindow closed.');
        },
      });
      handler.openIframe();
    }

Callback Method

Once a transaction has been successfully achieved, a callback method will be sent out, including other actions you would like to carry out. An example of how that can be chieved would be:

callback: function(response){
    $.ajax({
      url: 'http://www.yoururl.com/verify_transreference='+ response.reference,
      method: 'get',
      success: function (response) {
        // the transaction status is in response status
      }
    });

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, for them to add their payment information to complete the transaction.

<?php
  $url = "https://api.chapa.co/transaction/initialize";
  $fields = [
    'email' => "customer@email.com",
    'amount' => "20000"
  ];
  $fields_string = http_build_query($fields);
  //open connection
  $ch = curl_init();
  
  //set the url, number of POST vars, POST data
  curl_setopt($ch,CURLOPT_URL, $url);
  curl_setopt($ch,CURLOPT_POST, true);
  curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer SECRET_KEY",
    "Cache-Control: no-cache",
  ));
  
  //So that curl_exec returns the contents of the cURL; rather than echoing it
  curl_setopt($ch,CURLOPT_RETURNTRANSFER, true); 
  
  //execute post
  $result = curl_exec($ch);
  echo $result;
?>

Overview
Webhooks
Next →