Guides & Tutorials
Jenga PGW
Instant Payment Notifications

Instant Payment Notifications (IPN)

This feature will enable you to set up your callback URL whenever customers make payments.

By default, you will receive a notification for both Failed and Successful Transactions, but you can specify to receive only successful transactions ONLY.

Setup

To receive IPNs:

  1. Sign in on JengaHQ (opens in a new tab).
  2. Select the Settings menu on the sidebar.
  3. Choose the IPN submenu. You will be able to see a list of configured IPNs.
  4. Click New IPN button on the top right of the dashboard.
  5. Fill in your callback URL, username and password.

Being a Fintech Company, we embrace security in all aspects, and we provide a mechanism for you to get assured the notification is coming from the right source. We expect your URL to have a Basic Auth authentication, which will authenticate as per your username and password registered alongside your URL.

Request Format

Below is the description of the payload that is sent to the URL you specify

Example payload
POST /send/callback/here HTTP/1.1
Host: myserver.com
Content-Type: application/json
Authorization: Basic 67ew8n31me
 
{
  "callbackType": "IPN",
  "customer": {
    "name": "John Doe",
    "mobileNumber": "254712345678",
    "reference": "071648816466242"
  },
  "transaction": {
    "date": "2023-10-11 14:15:20",
    "reference": "328411183176",
    "paymentMode": "CARD" || "MPESA" || "PWE" || "EQUITEL" || "PAYPAL" ,
    "amount": 150,
    "currency": "KES",
    "billNumber": "INVZCF",
    "servedBy": "EQ",
    "additionalInfo": "CARD",
    "orderAmount": 150,
    "serviceCharge": 5.25,
    "orderCurrency": "KES",
    "status": "SUCCESS" || "FAILED",
    "remarks": "00:Approved"
  },
  "bank": {
    "reference": "328411183176",
    "transactionType": "C",
    "account": null
  }
}

Below is the description of the payload that is sent to the URL you specify

Field NameDescriptionTypeRequired
callbackTypeThe type of callback. In this case IPNStringYes
customer.nameThe customer nameStringYes
customer.mobileNumberThe customer mobile numberStringYes
customer.referenceThe customer referenceStringYes
transaction.dateThe transaction dateStringYes
transaction.referenceThe transaction referenceStringYes
transaction.paymentModeThe transaction mode of paymentStringYes
transaction.amountThe transaction amountDoubleYes
transaction.currencyThe transaction currency e.g., KESStringYes
transaction.orderCurrencyThe initial currency of the order (e.g., KES, EUR, USD)StringYes
transaction.billNumberThe transaction bill number. This is the account numberStringYes
transaction.orderAmountThe transaction order amountDoubleYes
transaction.serviceChargeThe transaction service chargeDoubleYes
transaction.servedByThe entity that served the transactionStringNo
transaction.additionalInfoAny additional information for the transactionStringNo
transaction.statusTransaction statusStringYes
transaction.remarksTransaction remarksStringNo
bank.referenceThe bank system reference idStringYes
bill.transactionTypeThe bill transaction typeStringYes
bill.accountThe bill account numberStringYes