ClickPay provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.

This article is dedicated to the clarification of the callback parameter. The callback is a server-to-server POST-HTTP Request that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process has ended (whether the customer cancels, paid, or failed to pay). It does not depend on the customer's actions; the response will be sent anyway.

In fact, the callback is an IPN that is limited to this specific transaction, you may need to check the How to configure Instant payment notification (IPN)? solution article for a better understanding.

TABLE OF CONTENTS

Specifications
Usage Workflow
- Sample Request Payload
- Sample Response Payload
The Expected Parameter Behaviors
- Setting the callback with a valid URL
- Not Passing any Callback URL

Specifications

The Parameter Tag/Name	callback
JSON Example	{ "callback": "https://www.example.com/notifications" }
Data Type	String
Required	❌
Validation Rules	Valid URL Recommended to pass it as an HTTPS URL. Port Numbers are NOT allowed in the URL. Must be public and reachable (localhost is not valid)
Max Length	255 Character

Usage Workflow

Along with the required parameters mentioned in our Step 3 - API Endpoints | Initiating the payment solution article, you will need to set the "callback" as shown below:

You can notice that the passed "callback" parameter is already included within the create payment page response object.

Sample Request Payload

{
    "profile_id": "987654",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "callback": "https://www.example.com/notifications"
}

Sample Response Payload

{
    "tran_ref": "TST2231901382893",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500.00",
    "tran_currency": "",
    "tran_total": "0",
    "callback": "https://www.example.com/notifications",
    "return": "none",
    "redirect_url": "https://secure.clickpay.com.sa/payment/page/59801A2682E4BE2CF1C51795B97FF7075AC8939FC94067FFE7D46BD2",
    "serviceId": 2,
    "profileId": 81784,
    "merchantId": 31237,
    "trace": "PMNT0403.6373DF3F.000622E1"
}

The Expected Parameter Behaviors

While the payment workflow proceeds with redirecting the customer to the ClickPay or/and issuer side for transaction authentication in the below listed ordered steps:

The customer/cardholder would enter his card details and submit the "PAY NOW" button.
Usually, if the card details are valid, the customer would be redirected to the issuer bank 3DSecure page to authenticate using the card.
After that, the customer would be redirected to the return page as you provided on the initial request, whatever the transaction status
Instantly, along with completing the transaction, the IPNs and the callback would be triggered.

One of the following behaviors (according to the passed "callback" value) will occur.

The expected behaviors are:

Setting the callback results
Not Passing any Callback URL

Setting the callback with a valid URL

In this case, instantly once the transaction is done the callback object will be sent to the callback URL, the object will be like the following structure:

{
  "tran_ref": "TST2231901382893",
  "merchant_id": 31237,
  "profile_id": 81784,
  "cart_id": "CART#1001",
  "cart_description": "Description of the items/services",
  "cart_currency": "USD",
  "cart_amount": "500.00",
  "tran_currency": "USD",
  "tran_total": "500.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    "name": "Mohammed",
    "email": "mohammed@email.com",
    "street1": "Unknown",
    "city": "Riyadh",
    "state": "Riyadh",
    "country": "SA",
    "ip": "156.221.253.233"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G39059",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2022-11-15T19:04:19Z"
  },
  "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 12,
    "expiryYear": 2022
  },
  "ipn_trace": "IPNS0004.6373E2B3.00010F2F"
}

This transaction detailed callback object can be used according to your business needs to decide your next action after the payment phase, whether it's succeeded or failed.

Not Passing any Callback URL

In case of not passing any callback URL, ClickPay will not send the callback object.

Request/Response Parameters | The Callback URL (callback) Print