4. Implement Callback URL

Webhook from Cellulant Tingg Express. When a full payment is made a JSON request is sent to the merchant’s callback URL. Note: Webhook is only sent when the customer has made full payment for the request raised.

We do a POST request when sending the payment details to the merchant's callback URL

Webhook Request:

Parameter Name	Type	Description	Required
checkout_request_id	Double	A unique identifier on Cellulant’s end.	Yes
merchant_transaction_id	String	Unique ID the merchant raised for the request	Yes
request_amount	double	The converted amount for the request raised by the merchant	Yes
original_request_amount	double	The original request amount raised by the merchant in the invoice currency	Yes
request_currency_code	string	Converted currency for the request the customer made the payment in	Yes
original_request_currency_code	string	ISO Code of the currency code the merchant raised the request in	Yes
account_number	double	Merchant reference the customer was paying for	Yes
currency_code	string	ISO Currency code of the payment made	Yes
amount_paid	double	Amount the customer paid for the request	Yes
service_charge_amount	double	Charges added to the service for the request initiated	Yes
request_date	date	Date when the request was raised in	Yes
service_code	string	Unique service code identifying the service the payment request was raised for.	Yes
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	Yes
request_status_description	string	Description of the status given back on the webhook request	Yes
MSISDN	string	The mobile number the person came with from the merchant site	Yes
payments	JSON Array	An array of successful payments made to the request	Yes
failed_payments	JSON Array	An array of any payments initiated but not successfully authorized	Yes
extra_data	string	metadata	Yes
country_abbrv	string	Abbreviation of the country	Yes

Payments array for both failed and successful payments array.

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

Sample JSON Request:

{
  "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
    },
    {
      "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"
}

Webhook Response:

Parameter Name	Type	Description
checkout_request_id	`long`	The unique Cellulant ID on the database
merchant_transaction_id	string	Unique ID the merchant raised for the request
status_code	string	Status code to indicate if a request is received successfully, failed, or accepted
status_description	string	Status code explanation 183 - successful 180 - payment rejected 188 - payment received and will be acknowledged later by the merchant
receipt_number	string	Unique identifier of the acknowledgment response given back

Sample Response for Payment processed successfully:

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

Sample Response for Payment processing failed:

{
  "checkout_request_id": 4826296,
  "merchant_transaction_id": "abcd-efg-hijklm",
  "status_code": "180",
  "status_description": "Payment was not processed successfully",
  "receipt_number": "r77az121236884"
}