Skip to main content

Request/Response: Tokenization (tokenise/token)

Warning

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

The tokenise and token parameters play a crucial role in securely handling customer payment information in modern payment systems. The tokenize parameter, used in the payment request, allows merchants to securely store card details as a unique token for future transactions. The token parameter, returned in the payment response or callback, serves as a reference to the stored card information, enabling future payments without needing to re-enter card details. Together, these parameters enhance security and streamline the payment process for both merchants and customers.


Next, we can delve into the specifics of how to implement the tokenise parameter in your requests. And how to receive the Token

How these parameters could benefit you?​

Here are some scenarios to help you understand when to use the token and tokenise parameters:

  • Secure Card Storage for Future Transactions: By including the tokenise parameter in your request payload, the card details will be securely stored as a token for future use. The token returned in the response can then be used to process payments without requiring the customer to re-enter their card information on subsequent transactions.

  • Enable Recurring Billing with Ease: The tokenise parameter is perfect for businesses offering subscription-based services or recurring payments. Once the card details are tokenized, you can use the token to process automatic payments without needing to ask customers to enter their card information repeatedly.

  • Faster, Frictionless Checkout: By securely storing your customers' card details as a token, tokenization allows for faster and more convenient transactions. Your customers can complete their purchases with just one click, significantly improving their shopping experience and boosting your conversion rates.

  • Enhanced Security and Fraud Prevention: With tokenization, your business benefits from an additional layer of security. The token is stored securely on our platform, reducing the risk of data breaches. Even if tokens are compromised, they cannot be used for unauthorized transactions, ensuring that your customers’ sensitive information remains protected.

  • PCI DSS Compliance Made Easier: As a PCI-certified payment gateway, we handle the sensitive card data for you. By using the tokenise parameter, you avoid the complexities of storing and managing card information directly, simplifying your PCI compliance and reducing your responsibility for sensitive data.

  • Reduced Risk of Chargebacks: With tokenization, you can securely store cards for future use and avoid having to repeatedly ask for CVV details. This helps reduce fraud-related chargebacks while maintaining a secure payment process.

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

  • E-commerce:For online stores, tokenization enables fast, secure checkouts and seamless repeat purchases, enhancing customer experience while reducing PCI DSS compliance scope

  • Subscription Services:Businesses offering subscription-based models (e.g., streaming services, SaaS, memberships) can easily manage recurring payments by securely storing card details for automatic billing.

  • GamingOnline gaming platforms can use tokenization to securely store players' payment information for in-game purchases, recurring subscriptions, and one-click transactions, providing a smoother gaming experience.

  • Streaming Platforms:Streaming services (e.g., video or music streaming) can securely store customer payment information for subscription renewals, enabling a seamless and convenient user experience.

  • InsuranceInsurance companies can use tokenization for managing premium renewals and payments, offering customers a secure, hassle-free payment experience without re-entering card details.

  • Travel and Hospitality:Travel agencies, airlines, and hotels can securely store payment details for frequent customers, simplifying booking processes and ensuring smoother transactions.

  • Healthcare:Medical services and telemedicine platforms benefit from tokenization by securely storing patient payment information for future visits, improving billing efficiency and security.

Limitations​


  • Limited to Supported Payment Methods:Tokenization may only be available for certain types of payment methods or cards. While most major card networks support tokenization, it may not be applicable to all card types or alternative payment methods, depending on the network's support for tokenization.

  • Card Updates:If a customer updates their card details (e.g., a new expiration date, card number, or other changes), the old token becomes invalid. In this case, the customer can revoke the old token and save the new one for future use, ensuring continuity in their payment process.

  • Geographical Restrictions:Tokenization may be subject to local regulations or restrictions in certain regions or countries. Merchants should verify that tokenization is supported in the regions where their customers are located to avoid potential issues.

  • Secure Handling of Tokens: Even though tokenized data is secure, merchants must ensure that tokens are stored and handled properly in their systems. Incorrect management or insecure storage of tokens could expose the business to security risks, so proper precautions must be taken.

  • Merchants' Access to Tokenized Data: While tokenized card information is securely stored by the payment gateway, merchants do not have access to the full card details (e.g., card number or CVV). This ensures the security and confidentiality of the customer's payment information

How to Use?​

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

  • Within the initiation of the request payload of the payment page/invoice in Step 3 via any of the supported integration types by this parameter, you will use the Optional parameter tokenise within the main request payload itself as shown below:

    {
        ...
        "tokenise": 2,
        ....
    }

  • Once you post the payment is authorised completed , you will receive a response that includes a token of the tokenised customer bank card credential:

    be aware of
    you will receive the token after finishing the transaction, don't expect to receive the token in the first response, you will receive it after payment in the return/callback Response.

    {
       ...
       "token": 2C4652BD67A3E936C6B490FC658B75B1,
       ....
    }

  • Finally some transactions type are direct transactions that don't need any further payment process and other will need to you to redirect the customer to a page for either authenticate the cardholder via the 3D Secure or processed with asking to fill the bank card details within the payment page. You may need to check his customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

  • tokenise

    Parameter
    tokenise
    DescriptionThe tokenization format the generated token should follow. Hosted Payment Page APIs | Token Based Transactions .
    To know more about this parameter please click here.
    Data TypeSTRING
    Required✘
    Validation RulesPass one of the following list:
    • 1 - no tokenization
    • 2 - Hex32
    • 3 - AlphaNum20
    • 4 - Digit22
    • 5 - Digit16
    • 6 - AlphaNum32
    Sample
    {
        "tokenise": 2,
    }
  • token

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

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.

be aware of
You will not receive the token in any of the following response. You will receive the response after you go the redirect_urland complete the payment, you will receive the token in the post-payment response.
{
    "profile_id": {{profile_id}},
    "cart_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_amount": 25000.2,
    "cart_currency": "SAR"
    "tokenise": 2
}

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 redirect URL. This means you have initiated a correct payment request/page successfully.

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

  3. Next, you should embed this url inside your checkout page directly using the needed mark up tags

  4. After this, your customer would proceed normally with payment by providing his card information, and he will be able to do that withing your story as you can see below:

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

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