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


The Parameter Tag/Namecallback
JSON Example
{
    "callback": "https://www.example.com/notifications"
}
Data TypeString
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 Length255 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": "[email protected]",
    "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.