Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of whether they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.
Repeat billing is a feature that allows merchants to send repeated payable invoices to their customers at predefined intervals (weekly, monthly, or annually) for subscription products, or services, and it is currently supported via our Merchant dashboard.
You can learn more about how you can initiate and manageg your Repeat Billing payment through PayTabs merchant dashboard by clicking here.
Note that in order to create any Repeat Billing agreements, you MUST have a secured terms & conditions URL configured inside your PayTabs profile, so if you do not have it already configured, you should contact your account manager or customer care and provide them with the URL to configure it for you. Following the steps mentioned in this article with configuring the URL will result in your request being declined.
In this article, we are going to walk you through how you can initiate your Repeat Billing payments and create agreements via our PT2 API Endpoints. 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.
In this article, you will be going to know about:
- The Endpoint and Related Postman Collection
- The Minimum Required Parameters
- The Available Optional Parameters
- The Payment Page Experience
- The Merchant Dashboard Page Experience
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 here. The endpoint will need to be accessed with a POST request on the below-mentioned URL
Post | {{domain}}/payment/request |
Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.
The Minimum Required 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 | Data Type | Min | Max | Required | Purpose |
INT | Accept only valid profile number | ✔ | The merchant Profile ID you can get from your PayTavs 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. | ||
STRING | Valid string from this list | ✔ | 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. | ||
STRING | Valid string from this list | ✔ | 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. | ||
STRING | 1 | 64 | ✔ | Indicates the cart/order id at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
STRING | 1 | 128 | ✔ | Indicates the cart/order description at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
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 the customer will be charged with. To know more about this parameter please click here. | ||
DECIMAL | 0.01 | 9999999999.99 | ✔ | Indicates the amount of the transaction the customer is about to be charged To know more about this parameter please click here. |
Now in order to create a Repeat Billing agreement through our APIs, you will need - in addition to the general required parameters mentioned above- to include new parameters required specific to the agreement. Find below the Additional required parameters for the Repeat Billing Agreement payment:
Parameter | Required | Purpose |
agreement | ✔ | This object will contain the agreement parameters that will specify all the agreement details and options. |
agreement_description | ✔ | This parameter indicates the agreement description which you can use to distinguish your agreements and you can also use it as a title for your agreement. |
agreement_currency | ✔ | This parameter indicates the currency that this agreement will be initiated in and you need to make sure that this is the same currency that you have passed inside the cart_currency parameter and that this currency is configured in your PayTabs profile |
initial_amount | ✔ | This parameter indicates the initial amount that you will be requesting your customer to pay in this agreement, and you need to make sure that it is the same amount as the one you passed inside the cart_amount parameter |
repeat_amount | ✔ | This parameter indicates the repeated amount the you want to charge your customer with at the specified time intervals that you will be passing in the below parameters. |
final_amount | ✔ | This parameter indicates if you want to charge your customer with a final amount after completing the whole agreement payments. Note that this will not be applicable to unlimited term agreements (when setting the "repeat_terms" to 0) |
repeat_terms | ✔ | This parameter indicates the number of times you want to repeat the payment or charge your customers and here you will be repeating the charge of the amount specified in the "repeat_amount" parameter. Note that if you passed 0 to this parameter, it means that you will be initiating an open agreement that will keep charging the customer forever or until you cancel the agreement through your dashbaord. |
repeat_period | ✔ | This parameter indicates the interval period that you want to initiate your agreement to be repeated at (days, week, month). 1 => Day 2 => Week 3 => Month |
repeat_every | ✔ | This parameter indicates the number of times you want to pass between charging intervals, |
first_installment_due_date | ✔ | This parameter indicates the due date for the first payment after the initial payment created once you initiate the request. |
Sample Request Payload
The below sample request payload will show you how you can pass the above-mentioned parameters, which need to be passed with valid values to perform a request.
Sample Response Payload
The Available Optional Parameters
Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your payment request as much as possible it could be. The specification of these optional parameters is clarified below:
Parameter | Data Type | Min | Max | Required | Purpose |
STRING | - | 255 | ❌ | 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. To know more about this parameter please click here. | |
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. To know more about this parameter please click here. | |
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 To know more about this parameter please click here. | |
Object | - | - | ❌ | Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data. To know more about this parameter please click here. | |
Object | - | - | ❌ | Indicates the shipping details for this payment. If provided, the payment page will be prefilled with the provided data. To know more about this parameter please click here. | |
STRING | 3 | 128 | ❌ | ||
STRING | Valid email format | ❌ | |||
STRING | Valid number + country code prefix | ❌ | |||
STRING | 3 | 128 | ❌ | ||
STRING | 3 | 128 | ❌ | ||
STRING | 2 | 2 | ❌ | ||
STRING | ISO 3166-1 alpha-2 codes (two-letter country codes) | ❌ | |||
STRING | Valid zip code | ❌ | |||
BOOLEAN | - | - | ❌ | Indicates whether to preview the payment page within the current check 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 To know more about this parameter please click here. | |
BOOLEAN | - | - | ❌ | Indicates whether to reload the whole page on redirections or just reload the current frame. To know more about this parameter please click here. | |
BOOLEAN | - | - | ❌ | Indicates whether to reload the main base (could be div or another iFrame tag) that contained the payment page framed element. To know more about this parameter please click here. | |
STRING | Either “en” or “ar” | ❌ | Indicates the payment page displaying language. To know more about this parameter please click here. | ||
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. To know more about this parameter please click here | |
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
STRING | 1 | 255 | ❌ | ||
Array of objects | - | - | ❌ | To provide discounts for specific customers. To know more about this parameter please click here. | |
STRING | - | - | ❌ | provide a comma-separated list of card prefixes (usually first 6, can be up to first 11) To know more about this parameter please click here. | |
DECIMAL | 0.01 | 9999999999.99 | ❌ | The actual discount should be deducted from the cart_amount To know more about this parameter please click here. | |
STRING | ❌ | Description of the discount that will be displayed for the customer on the hosted payment page To know more about this parameter please click here. | |||
STRING | ❌ | To know more about this parameter please click here. | |||
STRING | ❌ | To know more about this parameter please click here. | |||
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. To know more about this parameter please click here. | ||
BOOLEAN | - | - | ❌ | For showing the “save this card” option on the payment page. To know more about this parameter please click here. | |
DECIMAL | 0.01 | 9999999999.99 | ❌ | To know more about this parameter please click here. | |
DECIMAL | 0.01 | 9999999999.99 | ❌ | To know more about this parameter please click here. | |
STRING | Pass one or more of the following list: "creditcard" "amex" "mada" "urpay" "unionpay" "stcpay", "valu" "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. To know more about this parameter please click here. | ||
STRING | - | - | ❌ | Valid token To know more about this parameter please click here. | |
STRING | - | - | ❌ | Valid transaction reference To know more about this parameter please click here. |
Sample Request Payload
The below sample request payload will show you how you can pass the above-mentioned parameters, which need to be passed with valid values to perform a request.
Sample Response Payload
The Payment Page Experience
As mentioned in "3.1.1 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 page to the client.
![](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/60113019602/original/Sk9dzbA6-tAKlw3q7Uhs78pzpix95Nu1Cw.png?1715087922)
The Merchant Dashboard Page Experience
ONCE and ONLY if the customer completes the above payment, a new agreement will be created in your merchant dashboard and you will be able to manage and view all the agreement history, related transactions, and invoices. If you are looking to learn how you can manage your agreement, you should visit our Repeat Billing article.
![](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/60113020802/original/mGRmWIC7VVRKtyp2FcL1N2QPHkIWbT2ETQ.png?1715088643)