Skip to main content

Request/Response: Callback URL (callback)

The Callback URL parameter is one of the optional parameters that you can use while initiating a hosted payment page. It provides a server-to-server response with detailed transaction information. It ensures merchants receive transaction updates regardless of customer actions on the payment page.

Next, we can delve into the specifics of how to implement the Callback URL parameter in your requests.

How this parameter could benefit you?​

This is one of the optional parameters that you can use in a payment request to achieve the following:

  • Receive a full server-to-server transaction response request that contain all the transaction details and not subjected to customer behavior.

Limitations​


  • No Limitations: This parameter can be used with all types of integrations with no limitations

How to Use?​

In order for you to start use the callback feature, you kindly need to follow the below simple steps:

  • Within the initiation of the request payload of the payment request in Step 3 via any of the supported integration types by this feature, you will use the optional parameter callback within the main request payload itself as shown below:

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

        "callback": "https://www.{{ yoururl }}.com/{{ your_endpoint }}",
    }

  • Once you post your request, you will receive a response that includes redirect URL like the following:

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

  • Finally you will need navigate/redirect your customer to the the previous mentioned link as this is crucial for your customer to proceed through the payment process. You may need to check his customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

  • card_discounts

    Parameter
    callback
    DescriptionThe callback response is a server-to-server POST response 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. What is the Return URL vs the Callback URL?
    To know more about this parameter please click here.
    Data TypeSTRING
    Required✘
    MinN/A
    Max255 Characters (Valid URL)
    Sample
    {
        "callback": "https://www.example.com/notifications"
    }

Request & Response Payloads Samples​

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

Click to view the full Request Payload!
{
    "profile_id": "987###",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "callback": "https://www.{{ yoururl }}.com/{{ your_endpoint }}",
}
Click to view the full Response Payload!
{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "500.00",

    "callback": "https://www.{{ yoururl }}.com/{{ yourendpoit }}",

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
    "serviceId": 2,
    "profileId": 987###,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}

Expected Payment Flow Behavior​

  1. You will initiate a payment request using the guide mentioned [here](../Hosted-Payment-Page/HPP-Step-3-Initiating-Payment/HPP-Initiating-Payment)
  2. You will use the "callback" parameter according to the above [**Specifications**](#parameter-specifications)
  3. Then you will receive the response payload containing the "redirect_url" meaning you have initiated a correct payment request.
  4. Next, you should redirect your customer to this URL so the payment process can be finalized.
  5. Next, you should redirect your customer to this URL so the payment process can be finalized.Finally, once your customer complete the payment, a POST request containing all the transaction details will be sent to the URL you passed, below is a sample of the request that your endpoint will receive:
Click to view the full Response Payload via Non 3DS cards !
{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "500.00",
    "tran_currency": "SAR",
    "tran_total": "500.00",

    "callback": "https://www.{{ yoururl }}.com/{{ yourendpoit }}",

    "customer_details": {
        "name": "Demo Account",
        "email": "[email protected]",
        "phone": "+966 0000000000",
        "street1": "address street",
        "city": "city",
        "state": "state",
        "country": "SA",
        "zip": "45555",
        "ip": "1.1.1.1"
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "G17534",
        "response_message": "Authorised",
        "transaction_time": "2022-11-30T14:12:14Z"
    },
    "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4111 11## #### 1111",
        "expiryMonth": 12,
        "expiryYear": 2023
    },
    "serviceId": 8,
    "serviceId": 2,
    "profileId": 987###,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.