Initiating The Payment

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

---

The Endpoint and Related Postman Collection

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 PayTabs Postman APIs Collection. 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.

KSA

https://secure.paytabs.sa/payment/link/create

UAE

https://secure.paytabs.com/payment/link/create

Egypt

https://secure-egypt.paytabs.com/payment/link/create

Oman

https://secure-oman.paytabs.com/payment/link/create

Jordan

https://secure-jordan.paytabs.com/payment/link/create

Kuwait

https://secure-kuwait.paytabs.com/payment/link/create

Global

https://secure-global.paytabs.com/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:

The Minimum Required Parameters

Parameter	Data Type	Min	Max	Required
profile_id	INT	Accept 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 PT Dashboard? solution article. To know more about this parameter please click here.
	{ "profile_id": 987654 }
cart_currency	STRING	1	128	✔
	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	DECIMAL	0.01	9999999999.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 }
link_title	STRING	Valid PayLink title		✔
	this is a string field that contain PayLink title to identify between links
	{ "link_title":"PayLink title" }

The Available Optional Parameters

Parameter	Data Type	Min	Max	Required
return_url	STRING	N/A	255 Characters (Valid URL)	✘
	The return URL is the URL that PayTabs will redirect the customer to after he finishes 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 ends (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? To know more about this parameter please click here.
	{ "return_url": "https://example.com/order/10001" }
cart_min	DECIMAL	0.01	9999999999.99	✘
	This parameter is required only if donation_mode property is present to represent the minimum amount that the customer can enter
	{ "cart_min":5 }
cart_max	DECIMAL	0.01	9999999999.99	✘
	This parameter is required only if donation_mode property is present to represent the maximum amount that the customer can enter.
	{ "cart_max":500 }
donation_mode	BOOLEAN			✘
	This parameter will define whether this payment has a predefined amount or the customer will be entering the amount based on the passed cart_min and cart_max.
	{ "donation_mode ":true }
link_url	STRING			✘
	Indicates the link to which customers should be directed to complete their PayLink payment.
	{ "link_id": 600883, "profile_id": 100181, "link_url": "https://secure.paytabs.com/payment/link/100XXX/600XXXX" }
link_id	INT			✘
	Indicates the PayLink ID you can find on your merchant dashboard PayLinks menu.
	{ "link_id": 600883 }
link_status	BOOLEAN			✘
	Indicates whether the PayLink status is Actively enabled or disabled, by default is true 'Active'.
	{ "link_id": 600883 }

---

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.

Required Parameters Sample Payloads

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.

Sample Request Payload

{
    "profile_id": 109XXX,
    "link_title": "AK-Test Title",
    "cart_amount": "400",
    "cart_currency": "SAR"
}

Sample Response Payload

{
    "link_id": 147XXX,
    "profile_id": 109XXX,
    "link_url": "https://secure.paytabs.com/payment/link/109XXX/1474XXX",
    "link_title": "AK-Test Title",
    "cart_currency": "SAR",
    "cart_amount": "400",
    "cart_min": "0",
    "cart_max": "0",
    "shipping_required": false,
    "link_status": true,
    "donation_mode": false,
    "created_at": "2024-10-02T09:39:41Z",
    "updated_at": "2024-10-02T09:39:41Z"
}

Optional Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned optional 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.

Sample Request Payload

{
    "profile_id": 109XXX,
    "link_title": "AK-Test Title",
    "cart_amount": "200",
    "cart_currency": "SAR",
    "shipping_required": true,
    "return_url": "https://example.com/order/10001",
    "cart_min": "100",
    "cart_max": "500",
    "donation_mode": true,
    "discount_cards": "44444,400000",
    "discount_amount": "120",
    "discount_percent": "12",
    "discount_title": "120 SAR discount on cards start with 44444,400000",
    "opengraph": {
        "status": true,
        "title": "PayLink OpenGraph Title",
        "desc": "PayLink OpenGraph Description",
        "type": "testtype", 
        "filename": "thumbnail.png",
        "img": "iVBORw0KGgoAAAANCYII="
    }
}

Sample Response Payload

{
    "link_id": 147XXX,
    "profile_id": 109XXX,
    "link_url": "https://secure.paytabs.com/payment/link/109XXX/1474XX7",
    "link_title": "AK-Test Title",
    "cart_currency": "SAR",
    "cart_amount": "0",
    "cart_min": "100",
    "cart_max": "500",
    "return_url": "https://example.com/order/10001",
    "shipping_required": true,
    "link_status": true,
    "donation_mode": true,
    "created_at": "2024-10-02T14:09:22Z",
    "updated_at": "2024-10-02T14:09:22Z"
    "opengraph": 
    {
        "status": true,
        "title": "PayLink OpenGraph Title",
        "desc": "PayLink OpenGraph Description",
        "imgPath": "paylink/1804/47122/82045/opengraph.png",
        "imgExt": "png",
        "imgW": 640,
        "imgH": 640,
        "type": "website"
    }

}
                }

---

The Payment Page Experience

Reaching this point, you are now able to initiate a PayLinke 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 link URL. This URL is crucial for guiding your customer through the payment process.

    "link_url": "https://secure.paytabs.com/payment/link/109XXX/1474XX7",

In the meantime, your PayLink would be already created on your dashboard, which you can access from your merchant dashboard.

2. 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:

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