To start accepting payments, you'll need to create a checkout session on our platform & render the Express payment page for the customer to complete the payment. We can break down the implementation into three broad steps:

1. Get the checkout details

2. Create an Express URL

To make thing easier, we provide SDKs for some common languages.

They are completely open-source and publicly accessible. In case you encounter and issue, feel free to issues on the respective repository or seek support on our discussion forum.

3. Setup Payment Notifications

We send out IPNs on the callback_url provided on the checkout payload. The payment notifications are in the form of HTTP request from our platform.

We send a HTTP POST request to the merchant's callback URL. With the fields below:

HTTP POST Request Body

Parameter Name	Type	Description
checkout_request_id	`Double`	A unique identifier on Cellulant’s end.
merchant_transaction_id	`String`	Unique ID the merchant raised for the request
request_amount	`Double`	The converted amount for the request raised by the merchant
original_request_amount	`Double`	The original request amount raised by the merchant in the invoice currency
request_currency_code	`String`	Converted currency for the request the customer made the payment in
original_request_currency_code	`String`	ISO Code of the currency code the merchant raised the request in
account_number	`Double`	Merchant reference the customer was paying for
currency_code	`String`	ISO Currency code of the payment made
amount_paid	`Double`	Amount the customer paid for the request
service_charge_amount	`Double`	Charges added to the service for the request initiated
request_date	`Date`	Date when the request was raised in
service_code	`String`	Unique service code identifying the service the payment request was raised for.
request_status_code	`String`	Overall request code indicating the status of the service 177 - partially paid requests 178 - indicating the request was fully paid for 179 - indicating the request was partially paid for but expired 129 - Request expired without payments 102 - Insufficient funds 101 - Invalid pin/canceled 99 - Generic Failed Payment Status
request_status_description	`String`	Description of the status given back on the webhook request
MSISDN	`String`	The mobile number the person came with from the merchant site
payments	`JSON Array`	An array of successful payments made to the request
failed_payments	`JSON Array`	An array of any payments initiated but not successfully authorized
extra_data	`String`	metadata
country_abbrv	`String`	Abbreviation of the country

Payments array for both failed and successful payments array.

Parameter Name	Type	Description
customer_name	string	Customer name of the person who made the payment
account_number	string	Merchant reference the customer was paying for.
cpg_transaction_id	String	Unique Cellulant identity
currency_code	string	ISO Currency code of the payment made
payer_client_code	string	Payment option customer paid with e.g. Airtel
payer_client_name	String	Payment option customer name
amount_paid	double	Amount customer paid for
service_code	String	Code of service paid to
date_payment_received	Date	When the payment was made and received
MSISDN	string	The mobile number the customer is paying for
payer_transaction_id	string	Unique ID the MNO or bank generated for the transaction
hub_overall_status	string	The overall status of the payment made is described on the status code table below
payer_narration	String	Payment description is given by MNO, bank, or card acquirer.

Here is a sample JSON request body that you'll receive in the IPN:

{
  "request_status_code": 178,
  "account_number": "11800",
  "merchant_transaction_id": "56679792",
  "amount_paid": 15,
  "service_charge_amount": 0,
  "request_amount": "10",
  "payments": [
    {
      "account_number": "11800",
      "payer_client_name": "Mula Checkout",
      "amount_paid": 5,
      "payer_narration": "The service request is processed successfully.",
      "date_payment_received": "2021-11-26 14:47:45.0",
      "currency_code": "KES",
      "payer_transaction_id": "PKQ082LB08",
      "cpg_transaction_id": "1195072932",
      "payer_client_code": "MULACHECKOUT_KEN",
      "hub_overall_status": 139,
      "service_code": "MULACHECKOUTONLINE",
      "customer_name": "Customer",
      "msisdn": 254700000000
    },
    {
      "account_number": "11800",
      "payer_client_name": "Mula Checkout",
      "amount_paid": 5,
      "payer_narration": "The service request is processed successfully.",
      "date_payment_received": "2021-11-26 14:47:45.0",
      "currency_code": "KES",
      "payer_transaction_id": "PKQ082LB08",
      "cpg_transaction_id": "1195072932",
      "payer_client_code": "MULACHECKOUT_KEN",
      "hub_overall_status": 139,
      "service_code": "MULACHECKOUTONLINE",
      "customer_name": "Customer",
      "msisdn": 254700000000
    },
  ],
  "original_request_amount": 10,
  "checkout_request_id": 6,
  "currency_code": "KES",
  "failed_payments": [],
  "request_currency_code": "KES",
  "request_date": "Fri Nov 26 11:47:04 GMT 2021",
  "service_code": "MULACHECKOUTONLINE",
  "request_status_description": "Success payment",
  "original_request_currency_code": "KES",
  "msisdn": "254700000000",
	"extra_data": "abcd",
	"country_abbrv": "KEN"
}

HTTP response

After receiving the HTTP POST request on the callback_url specified on the checkout payload, you have to respond with the following JSON payloads to either accept or reject the payment according to your business processes.

Parameter Name	Type	Description
checkout_request_id	`String`	The unique Cellulant ID on the database
merchant_transaction_id	`String`	Unique ID the merchant raised for the request
status_code	`String`	Indicate if a request is received successfully, failed, or accepted 183 - Successful 180 - Payment rejected 188 - Payment received and will be acknowledged later
status_description	`String`	A narration of the status code meaning
receipt_number	`String`	Unique identifier of the acknowledgment response given back

Sample Response for payments processed

{
  "status_code": "183", 
  "checkout_request_id": 4826296,
  "receipt_number": "r77az121236884",
  "merchant_transaction_id": "abcd-efg-hijklm", 
  "status_description": "Successfully" 
}

{
  "status_code": "180",
  "checkout_request_id": 4826296,
  "receipt_number": "r77az121236884",
  "merchant_transaction_id": "abcd-efg-hijklm",
  "status_description": "Payment rejected"
}