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 an Auth transaction with a minimum amount such as (1 USD) and then after storing the token you can Release this amount back to the client.



Step 1: Enable Recurring Payment Mode



You will need to coordinate with your ClickPay relationship manager to enable Acquirer/ Processor Tokenization and ClickPay 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: support@clickpay.sa 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_1234",
  "tokenise": "2",
  "cart_currency": "SAR",
  "cart_amount": 9876.54,
  "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@domain.com",
    "phone": "0500000000",
    "street1": "address street",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "zip": "12345",
    "ip": "100.10.1.10"
  }
}

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_12345",
  "cart_description": "Description of the items/services",
  "cart_currency": "SAR",
  "cart_amount": "9876.54",
  "tran_currency": "SAR",
  "tran_total": "10.00",
  "tran_type": "Sale",
  "tran_class": "ECom",
  "customer_details": {
    "name": "first name last name",
    "email": "addr@email.com",
    "phone": "0500000000",
    "street1": "address street",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "ip": "196.219.145.121"
  },
  "payment_result": {
    "response_status": "A",
    "response_code": "G20348",
    "response_message": "Authorised",
    "cvv_result": " ",
    "avs_result": " ",
    "transaction_time": "2022-11-03T12: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_12345",
  "tokenise": "2",
  "show_save_card": true,
  "cart_currency": "SAR",
  "cart_amount": 9876.54,
  "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@domain.com",
    "phone": "0522222222",
    "street1": "address street",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "zip": "12345",
    "ip": "110.101.3.5"
  }
}

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": "SAR",
  "cart_amount": 9876.54,
  "cart_description": "Description of the items/services",
  "callback": "{{callback_url}}"
}


Sample Response Payload

..

{
  "tran_ref": "SFT2105900091549",
  "tran_type": "Sale",
  "cart_id": "cart_55555",
  "cart_description": "Description of the items/services",
  "cart_currency": "SAR",
  "cart_amount": "100",
  "callback": "https://webhook.site/66d0f832-c55c-40c9-9da3-c43b0bc194c4",
  "customer_details": {
    "name": "first last",
    "email": "email@domain.com",
    "phone": "0522222222",
    "street1": "address street",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "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@domain.com",
    "phone": "0522222222",
    "street1": "address street",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "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 previous 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"
}


...