Webhook Listener

Use our Webhook Listener to get a real-time status update on a created Payment Requests or Payments transaction. Our system sends a real-time status update to your system via HTTPS.

Integration Requirements and Considerations:

• Requirement: We will send /payment-requests status notifications to a HTTPS URL. Provide us with your HTTPS URL during the integration testing. We recommend the integration URL to be different from the production URL.
• Requirement: Your server must run HTTPS and meet our authentication requirements (e.g., accept a basic authorization header. (Refer to Preparation / Prerequisites).
• Requirement: You must use port 443 for webhook servers.
• Consideration: You should configure how your system will respond to each notification status (refer to Webhook Listener Resource Description table).
• E-commerce Merchant Example: If your system receives a PAID notification status, you should inform your customer and fulfil the order. We recommend that you DO NOT fulfil the order until your system receives a PAID notification status

Webhook IP Addresses

Webhook Listener Resource Description

📘

Event Types

1. PAYMENT-COMPLETED: The transaction has been PAID, or in the case a refund has been ACCEPTED .
2. PAYMENT-FAILED: Transaction failed during processing.
3. PAYMENT-LINK-FOLLOWED: The QR Code has been scanned or the payer has followed the short URL.
4. PAYMENT-PROCESSING: Funds have left the payer's account and are in transit to the destination account.

Example Response

[
   {
      "message":"The payer successfully completed the transaction.",
      "eventType":"PAYMENT-COMPLETED",
      "resourceType":"payment-request",
      "resource":{
         "id":"8ecd810d-c0e2-40a6-8ab9-da12d72a3d6a",
         "merchantTransactionId":null,
         "amount":1.0,
         "type":"EBILL",
         "status":"PAID",
         "deliveryMode":"SMS",
         "merchant":{
            "id":"a7815ec3-72cd-4efe-b809-28f14501a5d3",
            "name":"Merchant name"
         },
         "payer":{
            "name":"firstName lastName",
            "merchantAccountId":"1234",
            "email":null,
            "mobileNumber":"5555555555",
            "preferredLanguage":"en"
         },
         "flexDetails":null,
         "dueDate":null,
         "createdDateTime":"2022-08-22T15:34:57.808Z",
         "shortCode":"ZFZDOFJ",
         "paymentLink":"https://pay.clik2pay.com/r/ZFZDOFJ",
         "qrCodeLink":"https://pay.clik2pay.com/qr/ZFZDOFJ",
         "displayMessage":null,
         "invoiceNumber":null,
         "businessUnit":null,
         "emailTemplate":null,
         "events":[
            {
               "status":"PAID",
               "dateTime":"2022-08-22T15:35:15.61Z"
            },
            {
               "status":"ACTIVE",
               "dateTime":"2022-08-22T15:35:11.701Z"
            },
            {
               "status":"SMS_SENT",
               "dateTime":"2022-08-22T15:34:58.105Z"
            },
            {
               "status":"CREATED",
               "dateTime":"2022-08-22T15:34:57.811Z"
            }
         ],
         "links":[
            {
               "rel":"self",
               "href":"https://api.clik2pay.com/v1/payment-requests/8ecd810d-c0e2-40a6-8ab9-da12d72a3d6a"
            }
         ]
      }
   }
]

Webhook Retries

Clik2pay webhooks have built-in retry methods for error response status codes. If Clik2pay doesn’t receive a 2xx response status code for an event, we will attempt sending a webhook event three times. After that we mark the event as failed and stop trying to send it to your endpoint.

Please ensure that your system handles webhook retries effectively to prevent duplicate payments logged.