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 subscriptions fees.


In this article you will be going to know about:


Postman Endpoint Collection


For the purposes of this article, you will need to use the following postman endpoints collection for testing and integrating, for proceeding with this please click here.



Payment Flow


You will need to follow the following steps to get your customer token:
- Create a sale transaction with the first transaction occurrence to tokenize the customer card.
Store your token along with the returned tran_ref for further usage.
- For further transactions, just create a normal transaction and pass the tokenization information, and it will be captured directly from the customer.


You can initiate a Auth transaction with a minumum amount such as (1 USD) and then after storing the token you can Releas this amount back to the clinet



Step 1: Enable Recurring Payment Mode


You will need to coordinate with your PayTabs relationship manager to enable Acquirer/ Processor Tokenization and PayTabs recurring transaction option on your account first.


This is a must step. Tokenization (Recurring) will fail/declined without this step.
Please send an email to: [email protected] for further assistance.



Step 2: Card Token Creation


Send the first transaction request with the tokenization request parameter (tokenize: 2) to tokenize the customer card and get this token back.


Sample Request Payload


Post{{domain}}/payment/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"
  }
}

Sample Response Payload via Return

After the payment is processed by the customer, 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

Sample Response Payload via Callback/IPN

If the callback URL or IPN service is enabled with callback, the returned 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"
}


Save Card Checkbox for Hosted Payment Page

In case that you are using our hosted payment page, you can display the "Save Card" checkbox on the hosted payment page by passing an additional parameter (“show_save_card”: true), where the token will only be created if the cardholder checks the save card option

 

Sample Request Payload


{
  "profile_id": "profile_id",
  "tran_type": "sale",
  "tran_class": "ecom",
  "cart_id": "cart_11111",
  "tokenise": "2",
  "show_save_card": true,
  "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"
  }
}

Step 3: Processing payment using the token


To process the payment using the token, the tran_type should be recurring” and the token should be passed in the request, along with the original transaction reference used to create this token should be passed in the tran_ref parameter


Sample Request Payload


{
  "profile_id": "profile_id",
  "tran_type": "sale",
  "tran_class": "recurring",
  "token": "2C4651BE67A3E530C6B791F560837DB1",
  "tran_ref": "TST2105900091509",
  "cart_id": "cart_55555",
  "cart_currency": "EGP",
  "cart_amount": 100,
  "cart_description": "Description of the items/services",
  "callback": "{{callback_url}}"
}

Sample Response Payload


{
  "tran_ref": "TST2105900091549",
  "tran_type": "Sale",
  "cart_id": "cart_55555",
  "cart_description": "Description of the items/services",
  "cart_currency": "EGP",
  "cart_amount": "100",
  "callback": "https://webhook.site/66d0f832-c55c-40c9-9da3-c43b0bc194c4",
  "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": "G19498",
    "response_message": "Authorised",
    "transaction_time": "2021-02-28T13:38:18Z"
  },
  "payment_info": {
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111"
  }
}

Query Token


Query Token is a rest API request that returns the payment details and customer details linked to the token along with the original transaction ID used to create the token


Sample Request Payload


Post{{domain}}/payment/token


{
  "profile_id": "profile_id",
  "token": "2C4651BF67A3EC34C6B691F8638B75BC"
}

Sample Response Payload

{
  "tran_ref": "TST2111000149684",
  "payment_info": {
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111"
  },
  "customer_details": {
    "name": "first last",
    "email": "[email protected]",
    "phone": "0522222222",
    "street1": "address street",
    "city": "dubai",
    "state": "DU",
    "country": "AE",
    "ip": "196.219.145.121"
  }
}

Delete Token

The delete token is a rest API request to revoke a token.


Deleting token will never affect the previuos transactions performed with this token.


Sample Request Payload


Post{{domain}}/payment/token/delete


{
  "profile_id": "profile_id",
  "token": "2C4651BF67A3EC34C6B691FB638B7BBC"
}

Sample Response Payload


{
"code": 0,
"message": "success"
}