Skip to main content

Initiate Agreement Payments (Repeat Billing)

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.

Repeat billing is a feature that enables merchants to automatically send invoices to their customers at set intervals—weekly, monthly, or annually—for subscription products or services. This feature is available through our Merchant dashboard.

you should know

You can learn more about how you can initiate and manage your Repeat Billing payment through PayTabs merchant dashboard by clicking hereRepeat Billing & Repeat Invoicing

Be Aware Of

Please note that to create any Repeat Billing agreements, you must have a secure terms and conditions URL set up in your PayTabs profile. If you haven't done this yet, please reach out to your account manager or customer care and provide them with the URL so they can configure it for you. If you don't follow the steps outlined in this manual for setting up the URL, your request may be denied.

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/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 create a Repeat Billing agreement using our APIs, you need to include not only the general required parameters mentioned earlier but also some additional parameters specific to the agreement. Below are all the parameters needed for the Repeat Billing Agreement payment:

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
}
agreement
ObjectN/A✔
This object will contain the agreement parameters that will specify all the agreement details and options.
{"agreement":
{ 
.
.
.
}
}
agreement's Nested Parameters
Nested ParameterData TypeMinMaxRequired
agreement_description
STRINGN/AN/A✔
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":
{ 
  "agreement_description": "Test agreement"            
}
}
agreement_currency
STRINGN/AN/A✔
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.
{"agreement":
{ 
  "agreement_currency": "SAR",  
 /* Must match transaction request currency */             
}
}
initial_amount
DecimalN/AN/A✔
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.
{"agreement":
{ 
  "initial_amount": 12.3
 /* Must match transaction request amount */              
}
}
repeat_amount
DecimalN/AN/A✔
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.
{"agreement":
{ 
   "repeat_amount": 100         
}
}
final_amount
DecimalN/AN/A✔
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).
{"agreement":
{ 
   "final_amount": 70,
  /* Not applicable to unlimited term agreements */          
}
}
repeat_terms
IntN/AN/A✔
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 dashboard.
{"agreement":
{ 
   "repeat_terms": 3,    
}
}
repeat_period
Int13✔
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. 
{"agreement":
{ 
   "repeat_period": 1,    
}
}
repeat_every
IntN/AN/A✔
This parameter indicates the number of times you want to pass between charging intervals.
{"agreement":
{ 
   "repeat_every": 4,
 /* e.g. every 1 week, or every 4 days etc */     
}
}
first_installment_due_date
DateN/AN/A✔
This parameter indicates the due date for the first payment after the initial payment created once you initiate the request.
{"agreement":
{ 
   "first_installment_due_date": "05/May/2024" 
/* Cannot be on or before the current day */      
}
}

Request & Response Payload Samples​

{
"profile_id": 79010,    
"tran_type": "sale",   
"tran_class": "ecom",  
"cart_id": "cart_11111",   
"cart_currency": "SAR",   
"cart_amount": 12.3,    
"cart_description": "Description of the items/services",
"agreement": 
{
    "agreement_description": "Test agreement",
    "agreement_currency": "SAR",   /* Must match transaction request currency */        
    "initial_amount": 12.3, /* Must match transaction request amount */        
    "repeat_amount": 100,        
    "final_amount": 70, /* Not applicable to unlimited term agreements */        
    "repeat_terms": 3,        
    "repeat_period": 1,        
    "repeat_every": 4, /* e.g. every 1 week, or every 4 days etc */        
    "first_installment_due_date": "05/May/2024" /* Cannot be on or before today */ 
}
}

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 page to the client.

My Image Description

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 ourRepeat Billing & Repeat Invoicingarticle.

My Image Description

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.