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. |
return | STRING | - | 255 | ❌ | 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. |
callback | 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. |
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 | 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 |
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 |