Webhook Listener

Receive Webhook callbacks for created Payment Requests or Payments

Suggest Edits

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

EnvironmentIP
Production3.99.39.224
3.96.30.80
52.6.229.252
Sandbox99.79.143.93
3.96.21.104
52.60.117.97

Webhook Listener Resource Description

FieldDescription
eventTypestring
A code for the type of event that triggered the webhook call.
Enum: [ PAYMENT-COMPLETED, PAYMENT-FAILED, PAYMENT-LINK-FOLLOWED]
messagestring
example: The payer successfully completed the transaction.
Text value that provides context for the event.
resourceTypestring
minLength: 1
The type of resource contained in the resource property.
Enum: [ Payment Requests API, Payments API ]

📘

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.

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.

Updated 2 days ago