Skip to main content

Initiating The Payment

PayTabs Technical Portal 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.

PayLinks integration type is suitable for merchants with PCI SAQ A or merchants does not have any PCI levels. To customize the UI of the PayPage, check thisHow to customize the PayPage (Hosted Payment Page) UI?, and to know more about the Hosted Payment Page PCI DSS merchant requirements, please check this article.

In this manual, 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 PayLinks | Payment Workflow manual first to understand the business/logic this integration type relay on.

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 po_link. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST{{domain}}/payment/link/create
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/link/create

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:

Parameter
profile_id
Data TypeINT
Required✔
Validation RulesAccept only valid profile number
DescriptionThe merchant Profile ID you can get from your PayTabs dashboard. For more information please check ourHow to get your account information from PT2 Dashboard?tutorial article.
To know more about this parameter pleaseclick here.
Code Sample
{
    "profile_id": "987654"
}
Parameter
link_title
Data TypeSTRING
Required✔
Validation Rules
Min
1 character
Max
128 character
DescriptionThe title will be displayed in the PayLink list in your Dashboard so it will be easy to find. So it's preferred to use a shortened title with a semantic meaning.
To know more about this parameter pleaseclick here.
Code Sample
{
     "link_title": "Donation campaign"
}
Parameter
cart_currency
Data TypeSTRING
Required✔
Validation RulesValid string from the following list: SAR AED BHDEGP EUR GBP HKD IDRINR IQD JOD JPY KWDMAD OMR PKR QAR USD
Accepts both upper- and lower-case characters.
DescriptionIndicates the transaction currency, which the customer will be charged with.
To know more about this parameter pleaseclick here.
Code Sample
{
     "cart_currency": "SAR"
}
Parameter
cart_amount
Data TypeDECIMAL
Required✔
if donation_mode is enabled this parameter will not require instead cart_min and cart_min will be.
Validation Rules
Min
0.01
Max
9999999999.99
DescriptionIndicates 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 pleaseclick here.
Code Sample
{
     "cart_amount": 500
}

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": 109XXX,
    "link_title": "AK-Test Title",
    "cart_amount": "400",
    "cart_currency": "SAR"
}

The Payment Page Experience​

As mentioned in 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 payment page to the client:

Sample Payment Page