Skip to main content

Request: Manage the Hosted Payment Page's session expiry (paypage_ttl)

Warning

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

The PayPage Time to live (TTL) parameter one of the optional parameters. It allows the merchant to set the expiry value of the payment page in minutes, with a minimum duration of 1 minute..

ℹYou need to know

By default, the initial Payment Page URL will expire after 20 minutes.


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

How this parameter could benefit you?​

Implementing the paypage_ttl parameter can thus provide a more tailored and efficient payment experience, benefiting both your business operations and customer satisfaction.

  • Control Over Payment Window Duration: The parameter allows merchants to define how long a payment page remains active. This ensures that customers complete transactions within a specific timeframe, reducing the risk of abandoned carts and improving conversion rates.


  • Ideal for Time-Sensitive Products: For products or services with frequently changing prices, such as airline tickets, hotel bookings, and flash sale items, the parameter ensures that payment is made before the price changes. This reduces mismatched or outdated pricing issues, providing a smoother transaction experience for both merchants and customers.


  • Customizable Based on Business Needs: Merchants can customize the TTL based on their specific business needs, allowing for flexibility in managing payment windows according to different scenarios and requirements.


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

  • Airlines: Managing ticket sales with frequently changing prices.

  • Hotels: Handling bookings with dynamic pricing.

  • E-commerce: Managing flash sales and limited-time offers.

  • Event Management: Selling tickets for events with specific timeframes.

  • Subscription Services: Ensuring timely payments for subscription renewals.

  • Retail: Managing inventory for high-demand products.

Limitations​


  • The value must be specified as an integer representing minutes. Fractional values are not supported.

How to Use?​

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

  • Within the initiation of the request payload of the payment integration, you will use the parameter paypage_ttl within the main request payload itself as shown below:

    {
        "paypage_ttl": 1
    }

  • Once you post your request, you will receive a response that includes the redirect_url of the payment page that will need to direct the customer to complete the payment process, and will expire after the provided time session pass

    {
       ...
       "redirect_url": "https://secure.paytabs.com/payment/page/599458B1826B**************B4818688",
       ....
    }

Parameter Specifications​

  • paypage_ttl

    Parameter
    paypage_ttl
    DescriptionIndicates the Hosted Payment Page's session expiry in minutes.
    Data TypeINT
    Required✘
    Min1
    Max20 Minutes by default.
    Validation RulesThe PayPage link will expire once the TTL period expires, regardless of whether the link has been generated but not accessed before the TTL expires.
    Sample
    {
        "paypage_ttl": 1
    }

Request & Response Payloads Samples​

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

{
    "profile_id": "79000",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "cart_101",
    "cart_currency": "SAR",
    "cart_amount": 120,
    "cart_description": "Description of the items/services",
    "paypage_lang": "en",
    "customer_details": {
       "name": "Technical Support",
       "email": "[email protected]",
       "phone": "+966 55 xxxxxx6",
       "street1": "street2",
       "city": "Riyadh",
       "state": "Riyadh",
       "country": "SA",
       "zip": "54321"
    },
    "shipping_details": {
        "name": "Technical Support",
        "email": "[email protected]",
        "phone": "+966 55 xxxxxx6",
        "street1": "street2",
        "city": "Riyadh",
       "state": "Riyadh",
        "country": "SA",
        "zip": "54321"
    }
     "paypage_ttl": 1
}

Expected Payment Flow Behavior​

  1. As mentioned above in the How to use? section, As a merchant you would initiate a payment request per the above Specifications, same as the sample codes mentioned in the samples section above.

  2. Then, you will receive a response that includes the redirect URL. This means you have initiated a correct payment request/page successfully.

    {
        .
        .
        "redirect_url": "https://secure.paytabs.com/payment/page/52E5B6B*************B4818688",
        .
        .
    }

  3. Next, you should redirect your customer to this URL so the payment process can be finalized.

  4. After this, your customer would proceed normally with payment by choosing the preferred payment method (if available), and providing his card information.

    Payment Page

  5. However, if the merchant didn't make any action before the expiration of the PayPage TTL period, or if the PayPage link is accessed after this period has expire, the session will terminate, preventing the customer from proceeding further. The following message will be displayed:

    Payment Page session expire

  6. If the customer proceeds within the allowed time, Then, they will be redirected to their issuer bank 3DS/OTP page to authenticate the used card.

  7. Finally, he would be redirect to a success/error page accordingly. By this time, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.transaction view

    transaction view

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.