Webhook: Payment Notification

Overview

This webhook is triggered whenever a payment is successfully processed. It allows your system to receive real-time updates about a transaction.

Your application must be able to receive HTTP POST requests from our server at the webhook URL you have configured.
Upon receiving the webhook, it is mandatory to verify the payment status using our Payment Verification API before taking any action.

---

Example Payload

Below is an example of the JSON payload sent to your webhook endpoint:

{
  "reference": "PISL2408200000000035",
  "amount": "3000",
  "amount_paid": "3051",
  "payment_status": "paid",
  "payment_channel": "card",
  "paid_at": "2024-08-20T11:43:57.000Z",
  "payment_name": "Abc Sample",
  "payment_item_id": 1,
  "meta_data": null
}

---

Field Description

Field	Type	Description
reference	string	Unique transaction reference generated for the payment.
amount	string	The expected amount for the transaction.
amount_paid	string	The actual amount paid by the customer (may include charges).
payment_status	string	Current status of the transaction. Possible value: paid,unpaid
payment_channel	string	The method used for payment (e.g., card, bank, bank-transfer).
paid_at	string (ISO8601)	Timestamp indicating when the payment was completed.
payment_name	string	Name or description of the payment item.
payment_item_id	number	Identifier of the specific payment item.
meta_data	object / null	Additional metadata (if any) sent with the transaction.

---

Verification Step (Mandatory)

After receiving a webhook, your system must call our Verification endpoint to confirm the authenticity and current status of the transaction.

Example Response

{
  "status": true,
  "message": "",
  "data": {
    "reference": "PISL2509280000000238",
    "payment_status": "pending",
    "amount": "1000",
    "payment_item": { /* complete payment item object */ },
    "customer": {
      "id": 46,
      "customer_tag": "Cus_208FZen2hmLqKTcTlj8hiV1PdR",
      "first_name": "John",
      "last_name": "Doe"
    },
    "business": {
      "business_name": "Dune Abc"
    }
  },
  "statusCode": 200
}

⚠️ Important:
Only treat the payment as successful after verifying through this endpoint. Do not rely solely on the webhook payload.

---

Expected Response

Your server must respond with HTTP 200 OK to acknowledge receipt of the webhook.

Example response:

{
  "status": true,
  "message": "Webhook received successfully"
}

If your endpoint fails to respond with a 200 status code, we will retry delivery multiple times before marking the webhook as failed.

---

Implementation Tips

• Always verify reference via the verification endpoint.
• Avoid performing heavy operations directly within the webhook handler.
• Respond quickly 200 OK to prevent retries.