Hosted Payment Page solution is suitable for Merchants with PCI SAQ A or merchants does not have any PCI levels.

To customize the UI of the hosted payment page, check this article, and to know more about PCI and PCI DSS merchant requirements please check this article.


In this article you will be going to know about:



Postman Endpoint Example


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

Payment Flow


The Hosted Payment page uses Transaction API request which will return a response with a payment page link.

The merchant should navigate the customers to this previous payment page link; in order to complete the payment.

Once the payment is completed, ClickPay will redirect the customer back to the merchant’s website, to the return URL which was specified by the merchant in the API request and the payment results will be posted to that URL.



The Request Mandatory Payload (Body) Parameters


  1. Transaction type (tran_type)


    Value
    		Description
    salePurchase Transaction
    authTransaction in auth and capture mode
    captureCapturing authorized transaction
    voidVoiding authorized transaction
    refundRefund Transaction of fully captured transaction


  2. Transaction class (tran_class)
    ValueDescription
    ecomECommerce Online Transaction
    motoMail Order Telephonic Order Transaction
    recurringRecurring token-based transaction


Request Payload


You will need to initiate your call to the following endpoint URL, with the following request payload example.

Post{{domain}}/payment/request


{
  "profile_id": 49622,
  "tran_type": "sale",
  "tran_class": "ecom",
  "cart_id": "cart_11111",
  "cart_description": "Description of the items/services",
  "cart_currency": "SAR",
  "cart_amount": 100,
  "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218"
}


Response Payload


If the payment page is created successfully, you will receive an HTTP 200 OK response such as shown below including the payment page URL returned in a called redirect_url param.


You should navigate your customer to this URL to complete the payment


{
  "tran_ref": "SFT2110300142699",
  "tran_type": "Sale",
  "cart_id": "cart_11111",
  "cart_description": "Description of the items/services",
  "cart_currency": "SAR",
  "cart_amount": "100.00",
  "return": "https://webhook.site/4b3af623-085f-4b82-ab22-cb6cedeba218",
  "redirect_url": "https://secure.clickpay.com.sa/payment/page/3F76B62E82E417E6AB2104212437A16EA53E657E75232A6C4C544962"
}

Post Payment Process


Once the payment is completed, the user will be redirected back to the URL passed to the “return” parameter in the request payload. 


The return URL must be HTTPS, in order to receive the payment result details.


The payment result details will be posted to the “return” URL, as the example shown below:

acquirerMessage= 
&acquirerRRN= 
&cartId=cart_11111 
&customerEmail=test%40test.com 
&respCode=G96376 
&respMessage=Authorised 
&respStatus=A 
&token= 
&tranRef=SFT2110400143785 
&signature=db333934b8bd8d5f94d90ab28c72831d563dc10bb196ebd78a300af7df8fad7

The Request Optional Payload (Body) Parameters


The following are optional parameters that could be added in the main request payload in the merchant calls.



Framed Hosted Payment Page


To display the hosted payment page in an embed frame within the merchant website itself, the following parameter must be passed in the request payload.

"framed": true

Payment Page Language


The payment page can support either English (default) or Arabic language. So, to create a payment page in the Arabic language you will need to pass the following parameter in your payload. 

"paypage_lang": "ar"

Customer, Billing, and Shipping Details


The following are optional parameters and additional sections that can be added in addition to the main request payload. 



Pre-filled Customer, Billing, and Shipping Details


Passing the following parameters will display billing/shipping sections prefilled and collapsed on the payment page. 

{
  "customer_details": {
    "name": "first name last name",
    "email": "email@domain.com",
    "phone": "0501234567,
    "street1": "address street",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "zip": "12345",
    "ip": "1.1.1.1"
  },
  "shipping_details": {
    "name": "first name last name",
    "email": "email1@domain.com",
    "phone": "0501234567",
    "street1": "street2",
    "city": "riyadh",
    "state": "riyadh",
    "country": "SA",
    "zip": "54321",
    "ip": "2.2.2.2"
  }
}

Hide Shipping Details


In some cases that you will have digital products among your provided services to the customers, and you don’t require shipping details from your customers. You will not need to pass shipping details in the API request, you will just hide them from the created Hosted payment page by passing the following optional parameter in the main request payload of Transaction API

"hide_shipping": true



Hide Billing Details


To hide both billing and shipping details, you will need to (at least) pass the full valid customer details in addition to passing the following parameter: “hide_shipping”: true


{
  "profile_id": "profile_id",
  "tran_type": "sale",
  "tran_class": "ecom",
  "cart_id": "cart_12345",
  "cart_currency": "SAR",
  "cart_amount": 100,
  "cart_description": "Description of the items/services",
  "return": "https://webhook.site/6a2a359b-5dfc-43c7-a803-64b55d4cf092",
  "callback": "https://webhook.site/6a2a359b-5dfc-43c7-a803-64b55d4cf092",
  "hide_shipping": true,
  "customer_details": {
    "name": "first name",
    "email": "my@email.com",
    "phone": "05xxxxxxxx",
    "street1": "address street",
    "city": "Riyadh",
    "state": "Riyadh",
    "country": "SA",
    "zip": "12345",
    "ip": "172.16.1.1"
  }
}


The customer details are still required and must be passed in the API request and in case any of the details are missing or passed with invalid values; the hide_shipping option will be ignored and cardholder will be required to enter any of the missing details on the payment page

Only shipping details are optional and may not be passed in the API request (such as digital products case)


.....