Setup Recurring Payment

This API allows you to create and manage automated recurring payment schedules for both card and ACH payment methods.

Using this API, you can configure recurring billing frequencies such as weekly, monthly, quarterly, annually, or fully custom intervals. It also supports flexible end conditions, including subscriptions that never expire, subscriptions that stop after a specific number of payments, or subscriptions that end on a defined date.

This endpoint supports-

Card and ACH recurring payments
Weekly, monthly, quarterly, annual, and custom billing schedules
Fixed payment count or end-date termination
ACH SEC code configuration
Updating existing subscriptions using subscription_id

All requests must be authenticated using a valid token header.

Header Parameters

token*string

Auth token must be included in the header for all API requests to authenticate and authorize access.

Request Body

application/json

customer_id?string

Unique identifier of the consumer whose tokens are being retrieved.The Consumer ID is available in the Merchant Portal under My Customers. Required when creating a new subscription. Not used when editing an existing subscription via subscription_id.

subscription_id?string

Required only when editing an existing subscription. Omit when creating a new subscription (use customer_id instead).

recurring_frequency*string

The frequency of the recurring payment. Allowed values- WEEKLY, BI_WEEKLY, MONTHLY, BI_MONTHLY, QUARTERLY, BI_ANNUALLY, ANNUALLY, CUSTOM.

amount*number

The recurring payment amount in cents. Range- 1 to 999999 cents.

currency*string

The currency code (e.g., "USD").

tpn*string

Terminal Processing Number for the recurring payment.

end_criteria*string

Defines when the recurring payment should stop. Allowed values- NEVER, COUNT, DATE.

Value in"NEVER" | "COUNT" | "DATE"

end_value?integer

Required if end_criteria is DATE or COUNT. If DATE, value is (YYYY-MM-DD). If COUNT, value is a number (1 to 100). Not used if end_criteria is NEVER.

start_date?string

The date of the first recurring payment. Required for all frequencies except BI_MONTHLY and BI_ANNUALLY.

Formatdate

custom_interval_days?integer

The interval in days for custom recurring frequency. Required only when recurring_frequency is CUSTOM.

reference_id?string

Reference ID for the recurring payment (1–12 alphanumeric characters, or empty)

card_token?string

Required for card-based recurring payments when creating a new subscription. Not required when editing an existing subscription via subscription_id.

ach_token?string

Required for ACH (account-to-account bank transfer) recurring payments when creating a new subscription. Not required when editing an existing subscription via subscription_id.

sec_code?string

Allowed for ACH only. Accepted values- PPD, WEB, CCD, TEL. If a sec_code isn’t provided, the system auto-assigns in this order- PPD → WEB → CCD → TEL. Example- if both WEB and CCD tokens are available, system uses WEB.

Value in"PPD" | "WEB" | "CCD" | "TEL"

preferred_day?string

Preferred day of the week (e.g., 'FRIDAY'). Values are MONDAY to SATURDAY. Required if recurring_frequency is WEEKLY or BI_WEEKLY.

day_1?integer

Required only for bi-monthly and bi-annual frequencies. If BI_MONTHLY, value is 1–31 (day of month). If BI_ANNUALLY, value is a date (YYYY-MM-DD).

day_2?integer

Required only for bi-monthly and bi-annual frequencies. If BI_MONTHLY, value is 1–31 (day of month). If BI_ANNUALLY, value is a date (YYYY-MM-DD).

Response Body

`application/json`

curl -X POST "https://example.com/setup" \  -H "token: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "",    "recurring_frequency": "CUSTOM",    "amount": 1000,    "currency": "USD",    "tpn": "",    "end_criteria": "COUNT",    "end_value": 1,    "start_date": "2026-11-11",    "custom_interval_days": 1,    "reference_id": "",    "card_token": "",    "preferred_day": "WEDNESDAY",    "day_1": 1,    "day_2": 15  }'

{
  "data": {
    "subscription_id": "V7XJKGG7FJ6HL9B",
    "customer_id": "LMN7JCZ61GGICDW",
    "recurring_frequency": "WEEKLY"
  },
  "message": "subscription added successfully",
  "response_code": "SUCCESS",
  "status_code": 200,
  "request_id": "TEST-20251112011500-LQJL3G",
  "timestamp": "2025-11-12T06:15:00.271Z"
}

{
  "errors": [
    {
      "field": "end_criteria",
      "messages": [
        "End criteria is required."
      ]
    },
    {
      "field": "start_date",
      "messages": [
        "Start date cannot be today or in the past. Please choose a future date."
      ]
    }
  ],
  "status_code": 400,
  "request_id": "TEST-20251112012935-X04_2R",
  "timestamp": "2025-11-12T06:29:35.513Z"
}

Setup Recurring Payment

Header Parameters

Request Body

Response Body

200application/json

400application/json

`application/json`

`application/json`