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
Payment Flow
The Request Mandatory Payload (Body) Parameters
- Request Payload
- Response Payload
Post Payment Process
The Request Optional Payload (Body) Parameters

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

Transaction type (tran_type)

Value	Description
sale	Purchase Transaction
auth	Transaction in auth and capture mode
capture	Capturing authorized transaction
void	Voiding authorized transaction
refund	Refund Transaction of fully captured transaction

Transaction class (tran_class)
Value Description
ecom ECommerce Online Transaction
moto Mail Order Telephonic Order Transaction
recurring Recurring 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 protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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)

.....

Value	Description
ecom	ECommerce Online Transaction
moto	Mail Order Telephonic Order Transaction
recurring	Recurring token-based transaction

Hosted Payment Page Print