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, we will walk you through the Hosted Payment API endpoint both the Request and the Response parameters that you may deal with in the payloads. We will clarify each parameter data type, min/max length, the purpose of using this parameter, and whether it's required or not as shown in the below table to assist you more in handling those parameters within your own code:


Parameter 

Data Type 

Min 

Max 

Required 

Purpose 

profile_id 

INT 

Accept only valid profile number 

✔ 

Indicates the profile of the merchant associated to this call 

tran_type 

STRING 

Valid string from this list  

What is the "tran_type" (transaction type)? 

✔ 

Indicates the type of payment transaction such as sale, refund, void, etc. 

tran_class 

STRING 

Valid string from this list  

What is the "tran_class" (transaction class)? 

✔ 

Indicates the category/class this transaction will follow such as ECommerce, Recurring, etc 

cart_id 

STRING 

1 

64 

✔ 

Indicates the cart/order id at the merchant end to easily relate the transaction to 

cart_description 

STRING 

1 

128 

✔ 

Indicates the cart/order description at the merchant end to easily relate the transaction to 

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 will the customer be charged with 

cart_amount 

DECIMAL  

0.01 

9999999999.99 

✔ 

Indicates the amount the customer is about to charged with. 
 
Both min and max values are subjected to the merchant transaction limits 

return 

STRING 

- 

255 
(Valid URL) 

❌ 

The return URL is the URL that PayTabs will redirect the customer to after he finishes with 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 ended (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? 

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? 

 

Parameter 

Data Type 

Min 

Max 

Required 

Purpose 

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 

customer_details 

Object 

- 

- 

❌ 

Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data. 

shipping_details 

Object 

- 

- 

❌ 

Indicates the shipping details for this payment. If provided, the payment page will be prefilled with the provided data. 

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 our 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 

framed_return_top 

BOOLEAN 

- 

- 

❌ 

Indicates whether to reload the whole page on redirections or just reload the current frame. 

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. 

paypage_lang 

STRING 

Either “en” or “ar” 

❌ 

Indicates the payment page displaying language. 

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. 

user_defined.udf1 

STRING 

1 

255 

❌ 

 

user_defined.udf2 

STRING 

1 

255 

❌ 

 

user_defined.udf3 

STRING 

1 

255 

❌ 

 

user_defined.udf4 

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 

card_discounts.[].discount_cards 

STRING 

- 

- 

❌ 

provide a comma-separated list of card prefixes (usually first 6, can be up to first 11) 

card_discounts.[].discount_amount 

DECIMAL  

0.01 

9999999999.99 

❌ 

The actual discount should be deducted from the cart_amount 

card_discounts.[].discount_title 

STRING 

 

 

❌ 

Description of the discount that will be displayed for the customer on the hosted payment page 

card_filter 

STRING 

 

 

❌ 

 

card_filter_title 

STRING 

 

 

❌ 

 

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) 

show_save_card 

BOOLEAN  

- 

- 

❌ 

For showing the “save this card” option within the payment page. 

cart_min 

DECIMAL  

0.01 

9999999999.99 

❌ 

 

cart_max 

DECIMAL  

0.01 

9999999999.99 

❌ 

 

payment_methods 

STRING 

Pass one or more of the following list: 

    "creditcard" 

    "amex" 

    "mada" 

    "urpay" 

    "unionpay" 

    "stcpay", 

    "valu" 

    "fawry" 

    "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. 

token 

STRING 

- 

- 

❌ 

Valid token 

tran_ref 

STRING 

- 

- 

❌ 

Valid transaction reference