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
INT

STRING		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
}
agreement
OBJECTN/A✔
This object will contain the agreement parameters that will specify all the agreement details and options.
{
    "agreement": {
        "agreement_description": "Agreement Description",
        "agreement_currency": "{{currency}}",
        "initial_amount": 12.3,
        "repeat_amount": 100,
        "final_amount": 70,
        "repeat_terms": 3,
        "repeat_period": 1,
        "repeat_every": 4,
        "first_installment_due_date": "05/Dec/2025"
    }
}
agreement's Nested Parameters

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.