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
- The Available Optional Parameters
- The Payment Page Experience
- The Merchant Dashboard Page Experience
The Endpoint and Related Postman Collection
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 |
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. | ||
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. | ||
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. | ||
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. | |
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. | |
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. | ||
DECIMAL | 0.01 | 9999999999.99 | ✔ | Indicates the amount of the transaction the customer is about to be charged 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 |
STRING | - | 255 | ❌ | 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. To know more about this parameter please click here. | |
String | - | 255
| ❌ | 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. To know more about this parameter please click here. | |
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. | |
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. | |
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. | |
STRING | 3 | 128 | ❌ | ||
STRING | Valid email format | ❌ | |||
STRING | Valid number + country code prefix | ❌ | |||
STRING | 3 | 128 | ❌ | ||
STRING | 3 | 128 | ❌ | ||
STRING | 2 | 2 | ❌ | ||
STRING | ISO 3166-1 alpha-2 codes (two-letter country codes) | ❌ | |||
STRING | Valid zip code | ❌ | |||
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. | |
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. | |
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. | |
STRING | Either “en” or “ar” | ❌ | Indicates the payment page displaying language. To know more about this parameter please click here. | ||
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 | |
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
Array of objects | - | - | ❌ | To provide discounts for specific customers. To know more about this parameter please click here. | |
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. | |
DECIMAL | 0.01 | 9999999999.99 | ❌ | The actual discount should be deducted from the cart_amount To know more about this parameter please click here. | |
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. | |||
STRING | ❌ | To know more about this parameter please click here. | |||
STRING | ❌ | To know more about this parameter please click here. | |||
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. To know more about this parameter please click here. | ||
BOOLEAN | - | - | ❌ | For showing the “save this card” option on the payment page. To know more about this parameter please click here. | |
DECIMAL | 0.01 | 9999999999.99 | ❌ | To know more about this parameter please click here. | |
DECIMAL | 0.01 | 9999999999.99 | ❌ | To know more about this parameter please click here. | |
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. | ||
STRING | - | - | ❌ | Valid token To know more about this parameter please click here. | |
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": "[email protected]",
"phone": "0522222222",
"street1": "address street",
"city": "cc",
"state": "C",
"country": "AE",
"zip": "12345"
},
"shipping_details": {
"name": "FirstName LastName",
"email": "[email protected]",
"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 protected]",
"phone": "0522222222",
"street1": "address street",
"city": "cc",
"state": "AZ",
"country": "AE",
"ip": "197.47.93.193"
},
"shipping_details": {
"name": "name1 last1",
"email": "[email protected]",
"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.