Skip to main content

Request/Response: Callback URL (callback)

Warning

This parameter ONLY working with those integration types (Hosted Payment Page, Managed Form, Own Form, Invoices, and Invoices(Payment Endpoint)).

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.

Instead of relying solely on browser redirects or manual transaction checks, the callback_url parameter enables merchants to receive real-time transaction notifications directly on their servers. This automated communication helps ensure timely payment status updates, improves system synchronization, and allows merchants to process orders, update records, and trigger business workflows without additional customer interaction.

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

How this parameter could benefit you?​

The callback_url parameter plays a vital role in automating your payment workflow by enabling PayTabs to send transaction results directly to your server. Here’s how it can benefit you:

  • Real-Time Payment Notifications: The callback_url allows your system to receive payment updates immediately after a transaction is processed, ensuring that order statuses are updated without manual intervention.

  • Automated Order Management: By receiving transaction results directly on your server, you can automatically confirm orders, activate services, issue licenses, or trigger fulfillment processes.

  • Improved Reliability: Customer browsers may close, disconnect, or fail to return to your website after payment. The callback_url ensures your system still receives the transaction outcome directly from PayTabs.

  • Enhanced System Integration: It enables seamless communication between PayTabs and your backend systems, allowing you to synchronize payments with ERP, CRM, inventory, or accounting platforms.

  • Reduced Manual Effort: Automatic transaction updates help minimize manual reconciliation and operational workload, improving overall efficiency.

  • Better Transaction Tracking: The callback_url provides a reliable mechanism for recording payment statuses, making monitoring, reporting, and auditing more accurate.

Name but a few different Businesses/Industries that can benefit from this API parameter:

  • E-commerce Platforms: Online stores can automatically confirm orders, update inventory, and initiate shipment processes once successful payment notifications are received.

  • Subscription Services: Streaming platforms, SaaS providers, and membership-based businesses can instantly activate or renew subscriptions following successful payment confirmation.

  • Digital Product Providers: Businesses selling software, e-books, online courses, or digital content can automatically grant access immediately after payment completion.

  • Travel and Hospitality: Airlines, hotels, and travel agencies can automatically confirm reservations and send booking confirmations upon receiving payment notifications.

  • Education Institutions: Schools, universities, and training providers can validate tuition or course payments and automatically update student enrollment records.

  • Healthcare Providers: Clinics, hospitals, and telemedicine platforms can automate appointment confirmations and payment reconciliation processes.

  • Event Management Companies: Event organizers can automatically issue tickets, registrations, and attendee confirmations when payments are successfully completed.

  • Non-Profit Organizations: Charities and fundraising platforms can record donations instantly, trigger donation receipts, and maintain accurate donor records.

Limitations​

  • Follow-up Transactions: Callback notifications are sent for transactions that are initiated through the API with a valid callback URL. However, follow-up operations such as Refund, Capture, and Void may not trigger a callback notification if these actions are performed manually through the PayTabs Dashboard.

  • Public Accessibility: The callback URL must be publicly accessible from external servers. If the endpoint is protected by firewall rules, network restrictions, or other security measures that block incoming requests from external sources, callback notifications may not be delivered successfully. In such cases, it is recommended to whitelist the PayTabs IP addresses to allow callback requests to reach your server.

  • Redirections Are Not Supported: The callback URL must respond directly and should not enforce HTTP redirections. If your application implements global redirection rules, ensure that the callback endpoint is excluded from those rules. Additionally, verify that the endpoint can be reached and processed normally from external servers without any redirection or interruption during the handshake process.

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​

  • callback

    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]

  2. You will use the "callback" parameter according to the above 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. Then after adding the card details and clicking on the "Pay Now" button, your customer will be redirected to the 3DS page and proceed.

  6. 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
{
    "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.