ClickPay 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 token parameter. The token is used to make payments with or without cardholder presence.


This Parameter is exclusively used with Token-Based Transactions Requests.


In this article, you will be going to know:

TABLE OF CONTENTS

Specifications


The Parameter Tag/Name
token
JSON Example
{
    "token": "2C4652BD67A3EF30C6B390F9668175B9"
}
Data TypeString
Required✔  Required exclusively with Token-Based Transactions
Validation RulesValid Token that was generated earlier with a payment request.
Max Length-


Usage Workflow


Based on the Token-Based transactions mentioned in the ClickPay API Endpoints | Token-Based Transactions solution article, you will need to set the "token" as shown below:


Sample Request Payload (1)

{
    "profile_id": "987654",
    "tran_type": "sale",

    "tran_class": "recurring",

    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "token": "2C4652BD67A3EF30C6B390F9668175B9",
    "tran_ref": "TST2235301413385"
}


Sample Request Payload (2)

{
    "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",

    "token": "2C4652BD67A3EF30C6B390F9668175B9"
}


The Expected Parameter Behaviors


While the payment workflow proceeds, using one of the above requests, there are two expected scenarios



Direct Payment (no cardholder presence required)


In this case, the request must have the following:


- Token


- The previous transaction ref (that was created earlier along with the token)


- The tran_class with the value "recurring" (which requires the recurring to be enabled on the merchant profile)


Passing the above within the payment request as follows would be considered as no cardholder presence is required and will return a payment response as follows.


{
    "profile_id": "987654",
    "tran_type": "sale",

    "tran_class": "recurring",

    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "token": "2C4652BD67A3EF30C6B390F9668175B9",
    "tran_ref": "TST2235301413385"
}


In this case, instantly once the transaction is done the response is received in the following structure including the transaction details :


{
    "tran_ref": "TST2236001418779",
    "previous_tran_ref": "TST2235301413385",
    "tran_type": "Sale",
    "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",
    "customer_details": {
        "name": "My Name",
        "email": "email@domain.com",
        "phone": "+9665000000",
        "street1": "address street",
        "city": "riyadh",
        "state": "riyadh",
        "country": "SA"
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "G77868",
        "response_message": "Authorised",
        "transaction_time": "2022-12-26T18:04:28Z"
    },
    "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4000 00## #### 0002",
        "expiryMonth": 12,
        "expiryYear": 2022
    },
    "serviceId": 1,
    "profileId": 987654,
    "merchantId": 1234321,
    "trace": "PMNT0404.63A9E22C.0003DCAE"
}

Payment Page with card details pre-filled (requires the cardholder to add the CVV)

In this case, the request must have the following:

- Token

Passing the above within the payment request as follows would be considered as a creating payment page request with card details pre-filled on the payment page, asking the cardholder to add the CVV and any other required entries to authenticate using the card, so the result of this request would be a response with a redirect URL to redirect the customer to it.


{
    "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",

    "token": "2C4652BD67A3EF30C6B390F9668175B9"
}


You can notice the redirect_url in the following response:

{
    "tran_ref": "TST2236001418775",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500",
    "tran_currency": "",
    "tran_total": "0",
    "return": "none",
    "redirect_url": "https://secure.clickpay.com.sa/payment/page/595A246582E46212B3EF506226A9B906920A3339495422C0AF94F5AD",
    "serviceId": 2,
    "profileId": 987654,
    "merchantId": 1234321,
    "trace": "PMNT0403.63A9E17C.0003DE04"
}

By redirecting the customer to the ClickPay or/and issuer side for transaction authentication in the below listed ordered steps:


  1. The customer/cardholder would enter his card CVV and submit the "PAY NOW" button.
  2. Usually, if the card CVV is valid, the customer would be redirected to the issuer bank 3DSecure page to authenticate using the card.
  3. After that, the customer would be redirected to the return page as you provided on the initial request, whatever the transaction status.











...