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.




Tokenization is the process of protecting sensitive data by replacing it with an algorithmically generated number called a token. This can be used to allow returning customers to purchase without re-entering credit card details (recurring), such as monthly subscription fees.


In this article, we will walk you through how to make a payment request using the recurring transaction class type. You will be introduced to the required parameters that need to be passed to initiate the request.


We highly recommend you to check our Step 3.3 Token Based Transactions | Create and Manage Token to get the best out of this article, since this article is showing how to use the token.



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 Own-Form API Endpoint, mentioned on the 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 Recurring Payment Flow


You will need to follow the following steps to get your customer token:
- Create a sale/Auth transaction with the first transaction occurrence to tokenize the customer card.
- Store your token along with the returned tran_ref for further usage.
- For further transactions, just create a normal transaction and pass the tokenization information, and it will be captured directly from the customer.


You can initiate a Auth transaction with a minumum amount such as (1 USD) and then after storing the token you can Releas this amount back to the clinet




You will need to coordinate with your PayTabs relationship manager to enable the Acquirer/ Processor Tokenization and PayTabs recurring transactions option on your account first.


This is a MUST step. Tokenization (Recurring) will fail/declined without this step.


The Minimum Required Parameters


To initiate a recurring payment request, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below.

 

Parameter 

Required 

Purpose 

profile_id 

✔ 

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 

✔ 

the identification of the type of 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 

✔ 

For this request, the transaction type MUST be "recurring".


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 

✔ 

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 

✔ 

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 

✔ 

Indicates the transaction currency, which the customer will be charged with 


To know more about this parameter please click here.

cart_amount 

✔ 

Indicates the amount 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 the recurring payment request, you need - in addition to the general initial parameters - to include new parameters specific to the recurring payments. Find below the Additional required parameters for tokenization:


Parameter 

Required 

Purpose 

token

X

Valid pre-generated token


To know more about this parameter please click here.

tran_ref

✔ 

Indicates the transaction reference that returned on the same response along with the token.



Sample Request Payload  


The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.  

{
    "profile_id": "987654",
    "tran_type": "sale",

    "tran_class": "recurring",

    "cart_id": "CART#1001",
    "cart_currency": "USD",
    "cart_amount": 500,
    "cart_description": "Description of the items/services",

    "token": "2C4652BD67A3EF30C6B390F9668175B9",
    "tran_ref": "TST2235301413385"
}


Sample Response Payload


Once the payment request is validated and initiated, you will receive the following response. You can notice that the payment has already been performed, a transaction has been created, and you are already receiving the payment results.

{
    "tran_ref": "TST2233401397769",
    "previous_tran_ref": "TST2235301413385",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500.00",
    "tran_currency": "USD",
    "tran_total": "500.00",
    "customer_details": {
        "name": "Mohammed EL Rayes",
        "email": "elrayes@paytabs.com",
        "phone": "+201234567890",
        "street1": "address street",
        "city": "dubai",
        "state": "DU",
        "country": "AE"
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "G17534",
        "response_message": "Authorised",
        "transaction_time": "2022-11-30T14:12:14Z"
    },
    "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4111 11## #### 1111",
        "expiryMonth": 12,
        "expiryYear": 2023
    },
    "serviceId": 1,
    "profileId": 987654,
    "merchantId": 1234321,
    "trace": "PMNT0403.638764BE.000037CC"
}









⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article. 
		

		
⇦ And to get familiar with the rest of the steps regarding the previous step "Step 2 - Configure the integration method" kindly click here.
		

		
⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here. 
		

		
⇨ And to navigate to the next step in the integration process "Step 4 - Accepting the payment" kindly click here.