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  

 

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

tran_class 

STRING 

Valid string from this list  

 

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. 

 

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 
 

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