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


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 hereThe 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 transactionTo 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, etcTo 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": "[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.