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


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

profile_id 

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.

tran_type 

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.

tran_class 

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.

cart_id 

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.

cart_description 

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.

cart_currency 

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.

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.



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.


{
    "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 */
  }
}
Generic

 
Sample Response Payload
         

{
    "tran_ref": "TST2412801866182",
    "tran_type": "Sale",
    "cart_id": "cart_11111",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "12.30",
    "tran_total": "0",
    "return": "none",
    "redirect_url": "https://secure.paytabs.sa/payment/wr/5CC9E2AE82E6180563763B9A2D1D1A68D2270F4BFF3AA15293E759F7",
    "serviceId": 2,
    "profileId": xxxxx,
    "merchantId": xxxxx,
    "trace": "PMNT0402.663A27B7.000D1F33"
}

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 

return 

STRING

-

255
(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.

callback 

String

-

255
(Valid URL)

 

❌

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. 

 
What is the Return URL vs the Callback URL? 

To know more about this parameter please click here.

hide_shipping 

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.

customer_details 

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.

shipping_details 

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.

customer_details.name  

shipping_details.name  

STRING

3

128

❌

customer_details.email  

shipping_details.email  

STRING

Valid email format

❌

customer_details.phone  

shipping_details.phone  

STRING

Valid number + country code prefix

❌

customer_details.street1  

shipping_details.street1  

STRING

3

128

❌

customer_details.city  

shipping_details.city  

STRING

3

128

❌

customer_details.state  

shipping_details.state  

STRING

2

2

❌

customer_details.country  

shipping_details.country  

STRING

ISO 3166-1 alpha-2 codes (two-letter country codes)

❌

customer_details.zip  

shipping_details.zip  

STRING

Valid zip code

❌

framed 

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.

framed_return_top 

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.

framed_return_parent 

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.

paypage_lang 

STRING

Either “en” or “ar”

❌

Indicates the payment page displaying language. 

To know more about this parameter please click here.

user_defined 

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

user_defined.udf1  

STRING

1

255

❌

user_defined.udf2  

STRING

1

255

❌

user_defined.udf3  

STRING

1

255

❌

user_defined.udf3  

STRING

1

255

❌

user_defined.udf5  

STRING

1

255

❌

user_defined.udf6  

STRING

1

255

❌

user_defined.udf7  

STRING

1

255

❌

user_defined.udf8  

STRING

1

255

❌

user_defined.udf9  

STRING

1

255

❌

card_discounts 

Array of objects

-

-

❌

To provide discounts for specific customers.
  
 Transactions With Card Discounts 

To know more about this parameter please click here.

card_discounts.[].discount_cards 

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.

card_discounts.[].discount_amount  

DECIMAL

0.01

9999999999.99

❌

The actual discount should be deducted from the cart_amount 

To know more about this parameter please click here.

card_discounts.[].discount_title  

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.

card_filter 

STRING



❌

 To know more about this parameter please click here.

card_filter_title  

STRING



❌

 To know more about this parameter please click here.

tokenise 

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.  

 
Token Based Transactions (Recurring) 

To know more about this parameter please click here.

show_save_card 

BOOLEAN

-

-

❌

For showing the “save this card” option on the payment page. 

To know more about this parameter please click here.

cart_min 

DECIMAL

0.01

9999999999.99

❌

 To know more about this parameter please click here.

cart_max 

DECIMAL

0.01

9999999999.99

❌

 To know more about this parameter please click here.

payment_methods 

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.

token 

STRING

-

-

❌

Valid token 

To know more about this parameter please click here.

tran_ref 

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.


{
   "profile_id":"**Your profile ID**",
   "tran_type":"sale",
   "tran_class":"ecom",
   "cart_description":"Description of the items/services",
   "cart_id":"Unique order reference00",
   "cart_amount":25000.2,
   "cart_currency":"SAR",
   "paypage_lang":"en",
   "return":"** Valid Return URL **",
   "callback":"** Valid callback URL **",
   "customer_details":{
      "name":"FirstName LastName",
      "email":"email1@domain.com",
      "phone":"0522222222",
      "street1":"address street",
      "city":"cc",
      "state":"C",
      "country":"AE",
      "zip":"12345""   "
   },
   "shipping_details":{
      "name":"FirstName LastName",
      "email":"email1@domain.com",
      "phone":"971555555555",
      "street1":"street2",
      "city":"dubai",
      "state":"dubai",
      "country":"AE",
      "zip":"54321""   "
   },
        "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": 2, /* e.g. every 1 week, or every 4 days etc */
        "first_installment_due_date": "08/May/2024" /* Cannot be on or before today */
  },
   "user_defined":{
      "test":"UDF1 Test",
      "test2":"UDF2 Test",
      "udf3":"UDF3 Test",
      "udf4":"UDF4 Test",
      "udf5":"UDF5 Test",
      "udf6":"UDF6 Test",
      "udf7":"UDF7 Test",
      "udf8":"UDF8 Test",
      "udf9":"UDF9 Test"
   },
   "card_discounts":[
      {
         "discount_cards":"41111,520000",
         "discount_amount":"30.00",
         "discount_percent":"25",
         "discount_title":"30.00 SAR and 25% discount on cards starts with 41111, 520000",
         
      }
   ],
   "config_id":2188,
   "card_filter":"411111",
   "card_filter_title":"Only accept cards start with 41111",
   "tokenise":2,
   "show_save_card":true,
   "hide_shipping":true,
   "donation_mode":true,
   "cart_min":5,
   "cart_max":10,
   "framed":true,
   "framed_return_top":true,
   "framed_return_parent":true
}
HTML


Sample Response Payload


{
   "tran_ref":"TST223XXXXXXXXXX",
   "tran_type":"Sale",
   "cart_id":"Unique order reference00",
   "cart_description":"Description of the items/services",
   "cart_currency":"SAR",
   "cart_amount":"0.00",
   "tran_currency":"",
   "tran_total":"0",
   "callback":"** callback URL **",
   "return":"** return URL **",
   "redirect_url":"https://secure.paytabs.sa/payment/page/595AXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "customer_details":{
      "name":"first last",
      "email":"email@domain.com",
      "phone":"0522222222",
      "street1":"address street",
      "city":"cc",
      "state":"AZ",
      "country":"AE",
      "ip":"197.47.93.193"
   },
   "shipping_details":{
      "name":"name1 last1",
      "email":"email1@domain.com",
      "phone":"971555555555",
      "street1":"street2",
      "city":"dubai",
      "state":"DU",
      "country":"AE"
   },
   "serviceId":2,
   "profileId":100181,
   "merchantId":46656,
   "trace":"PMNT0403.63A99D49.0003A345"
}
JavaScript


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.




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.