You've chosen our Recurring Payments REST API

Create and update Recurring Payment Schedules using REST API

Introduction

Recurring payments, also known as subscription payments or auto-debit, are automatic transactions that are repeated on a regular schedule, such as daily, weekly, monthly or yearly, typically using a customer's credit card or stored token. Recurring Payments are commonly used for various services and products where a customer pays a fixed amount at regular intervals, like memberships, subscriptions or payment plans.

The TNS PayOrch platform offers REST API to create and manage Recurring Payments.

Let's start with an example. In this demonstration, we will guide you through the steps to set up a Recurring Payment Schedules using a credit card.

Additionally, you can create a Recurring Payment Schedules using a token instead of actual card data or establish a schedule using a bank account. For more details, see Create Recurring Payment on Token sections of our documentation.

Step 1

Get start with Authentication

All requests made through our system are authenticated using HMAC. To execute a sample request, you will need to obtain the API Key and Secret from TNS. Please reach out to our support team to acquire the API Key and Secret.

If you want to see how to create a HMAC signature, see Authentication section of our documentation.

Step 2

Try a sample Recurring Payment request

When you use our Recurring Payment REST APIs, you'll be making calls from your backend system directly to our payment system. To get started, you'll need to familiarize yourself with our APIs and calling options using your programming language of choice. Let's use our API Explorer to make a simple call together to help you see how our APIs work. To do this, let's run a simple recurring payment with monthly schedule request.

For information on header parameters and request body fields, see Create Recurring on Credit Card section of our documentation. 

                                                    

                                                    
    
                                                    
                                                    

                                                        View in Documentation
                                                        Run in API Explorer
Field Description Type Example

merchantId
Required

This is the unique identifier for the merchant in our system. Recurring Payment Schedules created can be viewed in the Merchant Portal under this merchant.

String 22d30d54-a733-4a7b-81fc-80f4d88febd5

startDate
Required

This is the effective start date of the Recurring Payment Schedules, formatted in UTC as YYYYMMDD. However, if a nextRun date is indicated, the recurring charges will transpire on that specified nextRun date instead.

String 20240615

endDate
Required

This is the effective final date of the recurring payment schedule, formatted in UTC as YYYYMMDD.

String 20250615

frequencyType
Required

Specifies the schedule type. The allowed enum values are as listed below. The value is formatted as string.
DAILY WEEKLY MONTHLY YEARLY

String MONTHLY

frequency

This indicates the frequency of the recurring payment. For example, if the value is 2 and the frequency type is MONTHLY, then the card will be charged every 2 months.

String 1

dateOfMonth

This specifies the date of the month on which to charge the card, applicable when the frequencyType is MONTHLY or YEARLY. Only dates from the 1st to the 28th are accepted to ensure all months accommodate the recurring cycle.

String 5

time

This specifies the time at which the recurring payment should be executed, formatted as HHmmss. Time is calculated based on the timezone provided in the request. If not provided, it defaults to 0000 hours UTC.

String 013000

timezone

Based on the timezone, the execution time of the recurring payment is calculated. The value of this field aligns with the geographic area's standard time and daylight saving adjustments. It is formatted as "Country/Region" and defaults to the merchant's timezone.

String America/Los_Angeles

paymentMethod
Required

This specifies the type of payment method to be used in this Recurring Payment Schedules. The allowed enum values are as listed below. The value is formatted as string.
CREDITCARD TOKEN

String CREDITCARD

paymentDetails
Required

This section outlines the details of the payment methods to be used. The fields within the paymentDetails section vary depending on the selected paymentMethod value.

Field Description Example Value
cardNumber
Required		 The customer's payment card number, also known as the Primary Account Number (PAN). The account number can be 12 to 21 digits long. 4005562231212123
expiry
Required		 This is the expiration date of the credit card formatted as MMYY 1225
transactionAmount
Required		 This is the total amount of the transaction converted to the lowest unit of currency formatted as a string. Amount can not be negative. Send the amount without a decimal in it. e.g. $10.25 should be sent as 1025. 1000
currencyCode
Required		 This is the 3-digit ISO 4217 numeric code 840
transactionReference The unique identifier for the transaction in your system formatted as a string 123456789

For more information on the request fields, see Create Recurring on Credit Card section of our documentation.

Sample Response

                                                

                                                        JSON
                                                    

                                                
{
    "recurringScheduleId": "767e1e5c-6a57-4804-b04f-64fd15a36c74",
    "transactionReference": "12345678",
    "token": "8220401324072123",
    "createdDate": "2024-05-31T02:56:12.000Z",
    "updatedDate": "2024-05-31T02:56:12.000Z"
}

For a complete reference and detailed information on response fields, see Response Format section of our documentation.

Step 3

Test payment

Use the following test card information to create a recurring payments schedule.

Test Card

4111 1111 1111 1111

Card Holder Valid Thru
Any valid cardholder name
Any future date in MM/YY format
CVV - Any three digit number
Address information - Any valid address
VISA

For more test cards to use, see Test Cards.

Explore our documentation to understand the various payment methods and schedule types available for setting up a Recurring Payment

Recurring Payments using different Payment Methods
Create Recurring Schedule using Credit Card
Create Recurring Schedule using Token
Retrieve Recurring Schedule Details

How to create different schedules
Daily Schedule
Weekly Schedule
Monthly Schedule
Yearly Schedule

That's It, You're Done!

You have successfully created a recurring payments schedule.

We use cookies to personalize your browsing experience. By continuing to visit this website you agree to our use of cookies. You may read more about this on our Terms & Conditions.
×