Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.


Tokenization is the process of protecting sensitive data by replacing it with an algorithmically generated number called a token. This can be used to allow returning customers to purchase without re-entering credit card details (recurring), such as monthly subscription fees. In this article, we will walk you through the series of steps you need to create a token via our API payment request.


In this article, you will be going to know about:



In this tutorial, we will rely on the PayTabs invoices API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL


Post{{domain}}/payment/request


Or


Post{{domain}}/payment/invoice



Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.

Create a Payment Request


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, "Step 3.2 - Initiating the Payment Request", but with including the below parameters as a MUST among the original request payload.


The Required Parameters

To initiate a tokenized payment request, you need to include these parameters to allow PayTabs to tokenize the customer card and send you this token back in the response. The specification of these required parameters is clarified below:


Parameter

Data Type

Min

Max

Required

Purpose

tokenise

STRING

Accept only one of the following: 

2=>Hex32 

3=>AlphaNum20 

4=>Digit22 

5=>Digit16 

6=>AlphaNum32 

✔

The tokenization format the generated token should follow 

To know more about this parameter please click here.



Note that in order for you to recieve the tokenized details you need to include either th "return" or the "call_back" parameters. You can learn more about them in our What is the Return URL vs the Callback URL solution article



Sample Request Payload


The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.


{
  "profile_id": "profile_id",
  "tran_type": "sale",
  "tran_class": "ecom",
  "cart_id": "cart_11111",
  "tokenise": "2",
  "cart_currency": "USD",
  "cart_amount": 200,
  "cart_description": "Description of the items/services",
  "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
  "callback": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
  "hide_shipping": true,
  "customer_details": {
    "name": "first last",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "du",
    "country": "AE",
    "zip": "12345",
    "ip": "1.1.1.1"
  }
}
Generic


Sample Response Payload


{
    "tran_ref": "TST2105900091503",
    "tran_type": "Sale",
    "cart_id": "cart_444441",
    "cart_description": "Payment with tok enabled, save card enabled",
    "cart_currency": "EGP",
    "cart_amount": "1",
    "callback": "https://webhook.site/ebe60b53-4158-4d82-aa16-231f2823378d",
    "return": "http://localhost/default/checkresponse.php",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/page/3F3856B482E417B4D619EA58B2F511BACCCB35681E2A0DD91F1E6103",
    "customer_details": {
        "name": "first last",
        "email": "[email protected]",
        "phone": "0522222222",
        "street1": "address street",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    },
    "shipping_details": {
        "name": "name1 last1",
        "email": "[email protected]",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    }
}


Sample Response Payload via Return


After the customer processes the payment, the return URL will have the raw content with the token ONLY IF the payment was processed successfully.


acquirerMessage=
&acquirerRRN=
&cartId=cart_11111
&customerEmail=email%40domain.com
&respCode=G20348
&respMessage=Authorised
&respStatus=A
&token=2C4651BF67A3EC34C6B691FB638B7BBC
&tranRef=TST2111000149667
&signature=237d6d2067094366864e093692dfdaa1762f5da4e2265f7374cf37e8be969f38
Generic


Sample Response Payload via Callback/IPN


If the callback URL or IPN service is enabled, the sent JSON response will have the token, as shown below


{
  "tran_ref": "TST2111000149667",
  "merchant_id": 3469,
  "profile_id": 65945,
  "cart_id": "cart_11111",
  "cart_description": "Description of the items/services",
  "cart_currency": "USD",
  "cart_amount": "200.00",
  "tran_currency": "USD",
  "tran_total": "200.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    "name": "first last",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "DU",
    "country": "AE",
    "ip": "196.219.145.121"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G20348",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2021-04-20T12:05:48Z"
  },
  "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 11,
    "expiryYear": 2023,
    "IssuerCountry": "",
    "IssuerName": ""
  },
  "token": "2C4651BF67A3EC34C6B691FB638B7BBC"
}
Generic









⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article. 

⇦ And to get familiar with the rest of the steps regarding the previous step "Step 2 - Configure the integration method" kindly click here.

⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here. 

⇨ And to navigate to the next step in the integration process "Step 4 - Accepting the payment" kindly click here.