Skip to main content

Step 1: Creating the Token

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, Invoices, Managed Form, Own Form).

The first thing you need to create a token is to create a basic payment request with the required information via any integration type that suits your business needs more, as mentioned in the previous step "Initiating the Payment Request", but with including the below parameters as a MUST among the original request payload.

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 ot use the following parameter:

  • 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,
    }

Request & Response Payloads Samples​

You should know that the Return & callback parameters are not required, but you should use them to receive the generated token.

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_description": "Description of the items/services",
    "cart_id": "Unique order reference00",
    "cart_amount": 25000.2,
    "cart_currency": "SAR",

    "tokenise": 2,

    "callback": "{Your CallBack URL}",
    "return": "{Your Return URL}"

}

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.