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.

Hosted Payment Page integration type is suitable for merchants with PCI SAQ A or merchants who do not have any PCI levels. To customize the UI of the hosted payment page, check this article, and to know more about the Hosted Payment Page PCI DSS merchant requirements, please check this article.

In this article, we will walk you through how to initiate a payment request via this integration type. You will be introduced to the required parameters that need to be passed to initiate the request, along with all the possible optional parameters as well. We highly recommend that you and your team check our "3.1.1 Hosted Payment Page | Payment Workflow" solution article first to understand the business/logic this integration type relay on.

In this article, you will be going to know about:

The Endpoint and Related Postman Collection
The Minimum Required Parameters
- Sample Request Payload
- Sample Response Payload
The Available Optional Parameters
- Sample Request Payload
- Sample Response Payload
The Payment Page Experience
The Merchant Dashboard Page Experience

In this tutorial, we will rely on the PayTabs Hosted Payment Page API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access from here. The endpoint will need to be accessed with a POST request on the below-mentioned URL

Post	{{domain}}/payment/request

Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.

The Minimum Required Parameters

To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below:

Parameter	Data Type	Min	Max	Required	Purpose
profile_id	INT	Accept only valid profile number		✔	The merchant Profile ID you can get from your PayTavs dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article. To know more about this parameter please click here.
tran_type	STRING	Valid string from this list		✔	the identification of the type of the transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article. To know more about this parameter please click here.
tran_class	STRING	Valid string from this list		✔	the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article. To know more about this parameter please click here.
cart_id	STRING	1	64	✔	Indicates the cart/order id at the merchant end to easily relate the transaction to To know more about this parameter please click here.
cart_description	STRING	1	128	✔	Indicates the cart/order description at the merchant end to easily relate the transaction to To know more about this parameter please click here.
cart_currency	STRING	Valid string from the following list: • AED • BHD • EGP • EUR • GBP • HKD • IDR • INR • IQD • JOD •JPY • KWD • MAD • OMR • PKR • QAR • SAR • USD Accepts both upper- and lower-case characters		✔	Indicates the transaction currency, which the customer will be charged with. To know more about this parameter please click here.
cart_amount	DECIMAL	0.01	9999999999.99	✔	Indicates the amount of the transaction the customer is about to be charged Both min and max values are subjected to the merchant transaction limits. To know more about this parameter please click here.

Sample Request Payload

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

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

Sample Response Payload

{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500.00",
    "return": "none",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
    "serviceId": 2,
    "profileId": 9*****4,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}

The Available Optional Parameters

Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your payment request as much as possible it could be. The specification of these optional parameters is clarified below:

Parameter	Data Type	Min	Max	Required	Purpose
return	STRING	-	255 (Valid URL)	❌	The return URL is the URL that PayTabs will redirect the customer to after he finishes the payment process (whether it's authenticated or not). It will redirect the customer with a POST response that is sent with the client/cardholder redirection through his browser containing the basic transaction information once the payment process ends (whether the customer cancels, paid, or failed to pay). It depends on the customer's actions, which means if the customer closes the browser right after the payment without waiting to be redirected back to your system, you will not receive this response. What is the Return URL vs the Callback URL? To know more about this parameter please click here.
callback	String	-	255 (Valid URL)	❌	The callback response is a server-to-server POST response that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process has ended (whether the customer cancels, paid, or failed to pay). It does not depend on the customer's actions; the response will be sent anyway. What is the Return URL vs the Callback URL? To know more about this parameter please click here.
hide_shipping	BOOLEAN	-	-	❌	Indicates whether to hide shipping and billing information or not from the payment page Note: The customer details are still required and must be passed in case any of the details are missing or passed with invalid values; the hide_shipping option will be ignored, and the cardholder will be required to enter any of the missing details on the payment page To know more about this parameter please click here.
customer_details	Object	-	-	❌	Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data. To know more about this parameter please click here.
shipping_details	Object	-	-	❌	Indicates the shipping details for this payment. If provided, the payment page will be prefilled with the provided data. To know more about this parameter please click here.
customer_details.name shipping_details.name	STRING	3	128	❌
customer_details.email shipping_details.email	STRING	Valid email format		❌
customer_details.phone shipping_details.phone	STRING	Valid number + country code prefix		❌
customer_details.street1 shipping_details.street1	STRING	3	128	❌
customer_details.city shipping_details.city	STRING	3	128	❌
customer_details.state shipping_details.state	STRING	2	2	❌
customer_details.country shipping_details.country	STRING	ISO 3166-1 alpha-2 codes (two-letter country codes)		❌
customer_details.zip shipping_details.zip	STRING	Valid zip code		❌
framed	BOOLEAN	-	-	❌	Indicates whether to preview the payment page within the current check page instead of redirection or not. If ✔, preview the redirect URL sent in the response in <iframe> HTML tag, which will preview the whole payment page within this frame To know more about this parameter please click here.
framed_return_top	BOOLEAN	-	-	❌	Indicates whether to reload the whole page on redirections or just reload the current frame. To know more about this parameter please click here.
framed_return_parent	BOOLEAN	-	-	❌	Indicates whether to reload the main base (could be div or another iFrame tag) that contained the payment page framed element. To know more about this parameter please click here.
paypage_lang	STRING	Either “en” or “ar”		❌	Indicates the payment page displaying language. To know more about this parameter please click here.
user_defined	Object	-	-	❌	For more customizations, you can pass to the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response. To know more about this parameter please click here
user_defined.udf1	STRING	1	255	❌
user_defined.udf2	STRING	1	255	❌
user_defined.udf3	STRING	1	255	❌
user_defined.udf3	STRING	1	255	❌
user_defined.udf5	STRING	1	255	❌
user_defined.udf6	STRING	1	255	❌
user_defined.udf7	STRING	1	255	❌
user_defined.udf8	STRING	1	255	❌
user_defined.udf9	STRING	1	255	❌
card_discounts	Array of objects	-	-	❌	To provide discounts for specific customers. Transactions With Card Discounts To know more about this parameter please click here.
card_discounts.[].discount_cards	STRING	-	-	❌	provide a comma-separated list of card prefixes (usually first 6, can be up to first 11) To know more about this parameter please click here.
card_discounts.[].discount_amount	DECIMAL	0.01	9999999999.99	❌	The actual discount should be deducted from the cart_amount To know more about this parameter please click here.
card_discounts.[].discount_title	STRING			❌	Description of the discount that will be displayed for the customer on the hosted payment page To know more about this parameter please click here.
card_filter	STRING			❌	To know more about this parameter please click here.
card_filter_title	STRING			❌	To know more about this parameter please click here.
tokenise	STRING	Pass one of the following list: 2=>Hex32 3=>AlphaNum20 4=>Digit22 5=>Digit16 6=>AlphaNum32		❌	The tokenization format the generated token should follow. Token Based Transactions (Recurring) To know more about this parameter please click here.
show_save_card	BOOLEAN	-	-	❌	For showing the “save this card” option on the payment page. To know more about this parameter please click here.
cart_min	DECIMAL	0.01	9999999999.99	❌	To know more about this parameter please click here.
cart_max	DECIMAL	0.01	9999999999.99	❌	To know more about this parameter please click here.
payment_methods	STRING	Pass one or more of the following list: "creditcard" "amex" "mada" "urpay" "unionpay" "stcpay", "valu" "aman" "meezaqr" "omannet" "knet" "knetdebit" "knetcredit "applepay" "samsungpay"		❌	To initiate the payment page with one or more specific payment methods, which should be configured first in your profile. To know more about this parameter please click here.
token	STRING	-	-	❌	Valid token To know more about this parameter please click here.
tran_ref	STRING	-	-	❌	Valid transaction reference To know more about this parameter please click here.

Sample Request Payload

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

{
    "profile_id": **Your profile ID**,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_description": "Description of the items/services",
    "cart_id": "Unique order reference00",
    "cart_amount": 25000.2,
    "cart_currency": "USD",
    "paypage_lang": "en",
    "return":"** Valid Return URL **",
    "callback":"** Valid callback URL **",
    "customer_details": {
        "name": "FirstName LastName",
        "email": "email1@domain.com",
        "phone": "0522222222",
        "street1": "address street",
        "city": "cc",
        "state": "C",
        "country": "AE",
        "zip": "12345"
    },
    "shipping_details": {
        "name": "FirstName LastName",
        "email": "email1@domain.com",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "dubai",
        "country": "AE",
        "zip": "54321"
    },
    "user_defined": {
        "test": "UDF1 Test",
        "test2": "UDF2 Test",
        "udf3": "UDF3 Test",
        "udf4": "UDF4 Test",
        "udf5": "UDF5 Test",
        "udf6": "UDF6 Test",
        "udf7": "UDF7 Test",
        "udf8": "UDF8 Test",
        "udf9": "UDF9 Test"
    },
    "card_discounts":[
  {
  "discount_cards" : "41111,520000",
  "discount_amount" : "30.00",
    "discount_percent" : "25",
  "discount_title" : "30.00 SAR and 25% discount on cards starts with 41111, 520000",
  }
],
    "config_id": 2188,
    "card_filter": "411111",
    "card_filter_title": "Only accept cards start with 41111",
    "tokenise": 2,
    "show_save_card": true,
    "hide_shipping":true,
    "donation_mode":true,
    "cart_min":5,
    "cart_max":10,
     "framed": true,
    "framed_return_top": true,
    "framed_return_parent": true
}

Sample Response Payload

{
    "tran_ref": "TST223XXXXXXXXXX",
    "tran_type": "Sale",
    "cart_id": "Unique order reference00",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "0.00",
    "tran_currency": "",
    "tran_total": "0",
    "callback": "** callback URL **",
    "return": "** return URL **",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/page/595AXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "customer_details": {
        "name": "first last",
        "email": "email@domain.com",
        "phone": "0522222222",
        "street1": "address street",
        "city": "cc",
        "state": "AZ",
        "country": "AE",
        "ip": "197.47.93.193"
    },
    "shipping_details": {
        "name": "name1 last1",
        "email": "email1@domain.com",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    },
    "serviceId": 2,
    "profileId": 100181,
    "merchantId": 46656,
    "trace": "PMNT0403.63A99D49.0003A345"
}

The Payment Page Experience

As mentioned in "3.1.1 Hosted Payment Page | Payment Workflow", by creating the payment page, you will receive the redirect URL "redirect_url" within the response, which you will use to redirect your client to this payment page. Once you have redirected your client, the client browser will display the following page to the client.

The Merchant Dashboard Page Experience

When the client successfully completes the payment, on your dashboard, you will find the transaction details shown at Home > Transactions as shown below:

⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article. 
	

	

	

	
⇦ And to get familiar with the rest of the steps regarding the previous step "Step 2 - Configure the integration method" kindly click here.
	

	

	

	
⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here.
	

	

	

	
⇨ Or you can navigate to the next step in the process "Step 4 - Accepting the payment" kindly click here.

PayTabs Support Portal

3.2.1 Hosted Payment Page APIs | Initiating the payment Print

The Minimum Required Parameters

Sample Request Payload

Sample Response Payload

The Available Optional Parameters

Sample Request Payload

Sample Response Payload

The Payment Page Experience

The Merchant Dashboard Page Experience

3.2.1 Hosted Payment Page APIs | Initiating the payment Print

The Endpoint and Related Postman Collection

The Minimum Required Parameters

Sample Request Payload

Sample Response Payload

The Available Optional Parameters

Sample Request Payload

Sample Response Payload

The Payment Page Experience

The Merchant Dashboard Page Experience

Related Articles