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. 


This article is dedicated to the clarification of the tokenise parameter. The tokenise is requesting Paytabs to save card details on Paytab's side, and return the token to be used with further payments with or without cardholder presence.


In this article, you will be going to know:

   

Specifications 


The Parameter Tag/Nametokenise
JSON Example
{
    "tokenise": 2,
}
Data TypeINT
Required
❌
Validation Rules

Accepts a value between 1-6, the return after payment IPN/callback will have the token parameter with data type as per the requested

  • 1 => no tokenization
  • 2 => Hex32
  • 3 => AlphaNum20
  • 4 => Digit22
  • 5 => Digit16 
  • 6 => AlphaNum32
Max Length1 Character 
Expected Response Samples
  • [1=>no tokenization ] :
    null
  • [2=>Hex32] :
    2C4652BD67A3E936C6B490FC658B75B1
  • [3=>AlphaNum20] :
    JfN1DVw6w7hrM7mk7P11
  • [4=>Digit22] :
    9784728714285600213410
  • [5=>Digit16] :
    7814287600213411
  • [6=>AlphaNum32] :
    JfN1DVw6w7hrM7mm1P11jNMbzFFAe9WU


Usage Workflow


Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the payment solution article, you will need to set the "tokenise" as shown below:


You can notice that the passed "tokenise" parameter is NOT included within the response object.


Sample Request Payload

   

{
    "profile_id": "987654",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "tokenise": 2
}


Sample Response Payload

   

{
    "tran_ref": "TST2231901382893",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500.00",
    "tran_currency": "",
    "tran_total": "0",
    "callback": "https://www.example.com/notifications",
    "return": "none",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/page/59801A2682E4BE2CF1C51795B97FF7075AC8939FC94067FFE7D46BD2",
    "serviceId": 2,
    "profileId": 81784,
    "merchantId": 31237,
    "trace": "PMNT0403.6373DF3F.000622E1"
}

The Expected Parameter Behaviors


While the payment workflow proceeds with redirecting the customer to the Paytabs or/and issuer side for transaction authentication in the below listed ordered steps:

  • The customer/cardholder would enter his card details and submit the "PAY NOW" button.
  • Usually, if the card details are valid, the customer would be redirected to the issuer bank 3DSecure page to authenticate using the card.
  • After that, the customer would be redirected to the return page as you provided on the initial request, whatever the transaction status
  • Instantly, along with completing the transaction, the IPNs and the callback would be triggered.

One of the following behaviors (according to the passed "tokenise" value) will occur.

The expected behaviors are:


  • Setting the tokenize with a value between 2-6


In this case, instantly once the transaction is done the callback object will be sent to the callback URL, the object will be like the following structure including the token parameter:


{
  "tran_ref": "TST2231901382893",
  "merchant_id": 31237,
  "profile_id": 81784,
  "cart_id": "CART#1001",
  "cart_description": "Description of the items/services",
  "cart_currency": "USD",
  "cart_amount": "500.00",
  "tran_currency": "USD",
  "tran_total": "500.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    "name": "Mohammed EL Rayes",
    "email": "[email protected]",
    "street1": "Unknown",
    "city": "Cairo",
    "state": "C",
    "country": "EG",
    "ip": "156.221.253.233"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G39059",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2022-11-15T19:04:19Z"
  },
  "payment_info": {
    "payment_method": "Visa",
    "card_type": "Credit",
    "card_scheme": "Visa",
    "payment_description": "4111 11## #### 1111",
    "expiryMonth": 12,
    "expiryYear": 2022
  },

  "token": "2C4652BD67A3EF30C6B390F9668175B9",

  "ipn_trace": "IPNS0004.6373E2B3.00010F2F"
}


You can use the token to make further payments with or without cardholder presence. Also, you can save the hashed card number for a better experience for customers.

  • Not Passing tokenise parameter OR passing it with value of "1"


In case of no token provided or provided with value of 1 , this would be expected on the callback/IPN