Skip to main content

Token-Based Transactions - Recurring Payments

you should know

You should know that This step can be used and will behave the same in the following integration types:(Hosted Payment Page, Managed Form, Own Form).

In today's digital marketplace, businesses often need to securely handle recurring payments, such as monthly subscription fees. Tokenization plays a critical role in enabling these transactions by protecting sensitive customer data. Tokenization replaces sensitive card details with a unique, algorithmically generated token, allowing returning customers to make purchases without re-entering their credit card information.

This manual will guide you through the process of making a payment request using the recurring transaction class type. You’ll learn about the required parameters and steps to initiate these secure, recurring transactions for seamless customer experience.

warning
In order to use this type of token based transactions, you MUST have the **Recurring** mode enabled in your PayTabs profile. To enable it, you MUST contact your account manager or [email protected] specifying the exact profile that you want to enable the recurring in along with your business needs for that.
warning
Be aware that Recurring transactions for India-issued cards will be rejected

The Endpoint and Related Postman Collection​

In this manual, we will rely on the PayTabs Hosted Payment Page API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access fromPayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST{{domain}}/payment/request
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/payment/request

The Required Parameters​

Along with the required parameters specified in "Step 3" of the integration type you are using, you will need to use the following parameter:

  • token

    Parameter
    token
    DescriptionTo know more about this parameter please click here.
    Data TypeSTRING
    Required✘
    Sample
    {
        "token": "2C4652BD67A3EF30C6B390F9668175B9"
    }

Request & Response Payloads Samples​

You MUST use the "recurring" transaction class.

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "recurring",
    "cart_description": "Description of the items/services",
    "cart_id": "Unique order reference00",
    "cart_amount": 25000.2,
    "cart_currency": "SAR",
    "token": "{the generated token from step 1}",
}

Expected Payment Flow Behavior​

  1. First, you should initiate a payment by following the steps mentioned in Hosted Payment Page | Initiating the Payment manual.

  2. Next, you should use the tokenise parameter within your request as clarified in the above Sample Request Payload.

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

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

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

  5. After this, your customer would proceed normally with payment by providing his card information.

  6. Then, he will be redirected to his issuer bank 3DS/OTP page to authenticate the used card

  7. Finally, he would be redirected to a success/error page accordingly. By this time, you will receive the full transaction response in the specified return or callback urls, which will contain the generated token as shown below:

    {
        .
        .
        .
        "token":"{Generated Token}"
        .
        .
        .
    }

  8. Finally, you should save this token in you database so that you can use it to create token-based transactions.

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.