Skip to main content

Initiating The Payment

Hosted Payment Page integration type is ideal for merchants with PCI SAQ A or those without any PCI levels. To customize the UI of the hosted payment page, check thisarticle, and to learn more about the PCI DSS merchant requirements for the Hosted Payment Page, please check thisarticle.

In this manual, we will rely on the PayTabs Hosted Payment Page API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access fromPayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST{{domain}}/payment/request
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/payment/request

Request 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:

ParameterData TypeMinMaxRequired
profile_id
INTAccept only valid profile number.✔
The merchant Profile ID you can get from your PayTabs 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.
{
    "profile_id": 987654
}
tran_type
INT

Valid string from this enum list:

sale auth void release capture refund register		✔
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.
{
    "tran_type": "sale"
}
tran_class
STRING

Valid string from this list

ecom recurring moto		✔
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.
{
     "tran_class": "ecom"
}
cart_id
STRING164✔
Indicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
{
     "cart_id": "CART#10001"
}
cart_description
STRING1128✔
Indicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
{
     "cart_id": "CART#10001"
}
cart_currency
STRING1128✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter please click here.
{
     "cart_currency": "SAR"
}
cart_amount
DECIMAL0.019999999999.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.
{
     "cart_amount": 500.99
}

Request & Response Payload Samples​

This section is dedicated give you a sample API request payload using both the above mentioned required and optional parameters, along with showing you the response payload received upon using each request payload.

The below sample request payload will show you how you can pass the above-mentioned required parameters, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

{
    "profile_id": "987###",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_currency": "SAR",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",
}

The Payment Page Experience​

Reaching this point, you are now able to initiate a Hosted Payment Page API request and as you now, the process involves several key steps that ensure a smooth payment and tracking experience for both you and customers. Here’s how it works:

  1. Initiating the Request: Once you initiate a payment request, you will receive a response that includes a redirect URL. This URL is crucial for guiding your customer through the payment process.
"redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
  1. Redirecting the Customer: You should redirect your customer to this URL as you normally would in a payment transaction. This step allows the customer to complete their payment securely and efficiently. Below are the resulted payment page that your customer will be redirected to:

Sample Payment Page

  1. Tracking in the Merchant Dashboard: After the payment is completed, the transaction will be displayed in your Merchant Dashboard. You can view the details of it in the transaction view.

This process ensures that you have full visibility and control over your split payouts, from initiating the transaction to tracking its completion in the dashboard.

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.