Recurring Billing is a feature that allows merchants to automatically charge customers on a predefined schedule such as weekly, monthly, yearly, or one-time, without manually creating invoices or processing payments each time.

Recurring Billing is commonly used for subscriptions, memberships, service agreements, and installment-based billing.

How Recurring Billing Works (High-Level Flow)

• Configure recurring billing settings for the merchant
• Create or fetch a customer
• Tokenize the customer’s card
• Create a recurring contract (subscription)
• System automatically generates invoices and processes payments based on the schedule

Merchant-level Configuration

Recurring billing behavior is controlled at the merchant level. These settings determine how invoices are generated and scheduled.

The below settings can be updated via the PUT /checkout/v3/merchantsetting/{merchantId} endpoint.

To know more, kindly refer to the Merchant Configuration and Payment Controls.

Setting Up Recurring Billing for Customers

This section explains how to create and manage a recurring billing contract for a customer.

a. Create a Customer

A Customer represents the end user (cardholder) whose payment details you want to securely store for future use. It contains identifying information such as name, email, and mobile number.

If the customer already exists, you can skip this step.

• Use the POST /checkout/v3/customer?echo=true( endpoint to create a Customer, by passing following parameters:

  Parameter	Required	Description
  name	✓	Full name of the customer.
  merchantId	✓	Merchant location ID.
  email		Valid email address.
  mobile		Valid mobile number of the customer.

• The GET /checkout/v3/customer/{customerId} endpoint returns all details of a customer, including:

  • id: Customer's unique id.

b. Generate a Card Token (Customer Card Account)

• Once a Customer Profile exists, create a Customer Card Account to tokenize your card details. Use the POST /checkout/v3/customercardaccount/{customerId} endpoint.

  Parameter	Required	Description
  number	✓	13 to 17 digits of card number.
  expiryMonth	✓	Card expiry month.
  expiryYear	✓	Card expiry year.
  cvv	✓	Card verification value.
  avsStreet	✓	Billing street address line 1.
  avsZip	✓	5-9 digit Billing zip/postal code.

Note: Both avsStreet and avsZip are used to perform Address Verification Service (AVS) checks.

• The GET /checkout/v3/customercardaccount/{customerId} endpoint returns all card accounts for a customer, including:
  • id: Card Account id.
  • token: Secure card token for payments.

c. Create Contract

A Contract Subscription defines the full recurring agreement between the merchant and the customer.

It consists of:

• Contract → Financial and commercial terms
• Subscription → Billing execution and payment behavior

Follow below steps to Create Contracts for customers:

• Create a Contract using the POST /checkout/v3/contractsubscription?echo=true endpoint that includes:

  Parameter	Required	Description
  contract	✓	Root object that defines the financial and scheduling details of the recurring billing contract.
  contract.merchantId	✓	Identifier of the merchant creating the recurring contract.
  contract.frequency	✓	Interval multiplier for billing (e.g., 1 = every cycle).
  contract.interval		Billing cadence (Weekly, Monthly, Yearly, or Once).
  contract.totalAmount		Total contract amount including taxes and discounts.
  contract.quantity		Aggregate quantity of items in the contract.
  contract.billNow		If true, charges the first payment immediately upon contract creation.
  contract.taxes		List of taxes applied at the contract level.
  contract.discounts		List of discounts applied to the contract.
  contract.purchases	✓	Array of line items included in the contract.
  subscription	✓	Root object that defines billing execution and payment behavior.
  subscription.customerId	✓	Unique identifier of the customer associated with the contract.
  subscription.cardAccountId	Conditional	Tokenized payment method ID (required for Autopay).
  subscription.startDate	✓	Date when the recurring billing schedule begins.
  subscription.invoiceMethod		Payment method used for recurring billing: Autopay or Invoice.
  subscription.sendReceipt		Controls when payment receipts are sent (Always, Never, or Once).

• Key points:

  • Billing Cadence Rules: The timing of the first and subsequent payments depends on schedule parameters and the initial charge type (Regular vs. Bill Now).

    Term	Definition
    Regular Contract	bill_now is false. First payment occurs on the first scheduled date.
    Bill Now Contract	bill_now is true. First payment occurs immediately at contract creation.
    6-Day Gap Rule	Enforced for Weekly/Monthly Bill Now. If the immediate payment date and next scheduled date are less than 6 days apart, the system pushes the nextBillDate by one cycle. Yearly contracts ignore this rule.
    Next Bill Date	System-calculated date for the next payment execution.

  • contract.taxes can be managed separately. To know more, kindly refer to Sales Taxes.

  • contract.discounts can be managed separately. To know more, kindly refer to Discounts.

• PCE captures the contract details instantly. The GET /checkout/v3/contract/{id} endpoint gives a response including detailed contract information such as amount, frequency, status, next billing date, and associated payment method:

  • id: Unique identifier for the contract.

• Use the GET /checkout/v3/contractsubscription/{{contractId}} endpoint to retrieve details of the subscription associated with a specific contract, including billing schedule, pricing, and duration.

• Updating Recurring Billing Contract: After the contract is created, use the PUT checkout/v3/contractsubscription?id={{contractId}}&subId={{subId}} to update the Recurring Billing Contract created. Here, the contractId will be the ID of the contract you wish to update and subId will be the subscription Id. You can modify an existing recurring billing contract, such as updating the amount, frequency, payment method, or status, without creating a new contract record.

i. Retrieving a Contract’s Payments

Retrieve the list of all payments that have been processed under a specific recurring billing contract.

Use the GET /v3/contract/payment API endpoint to fetch transaction history including amounts, dates, and payment statuses.

ii. Retrieving a Contract History

Retrieve the change history and event log for a specific contract, including updates, pauses, cancellations, or payment modifications.

Use the GET /v3/contract/history API endpoint to recive metadata such as timestamps, user IDs, and change descriptions.

iii. Contract Attachments

You can add attachments related to a contract after it has been created.

Requirements

To retrieve or associate an attachment, you must provide:

• contractId – Identifier of the contract
• subAttachmentId – Identifier of the specific attachment

Use following endpoints for Contract Attachments:

• Add a Contract Attachment: Use POST /checkout/v3/contractattachment?id={{contractId}}&echo=true API endpoint to add file name and attachment to the created contract.
• Retrieve a Contract Attachment: Use GET /checkout/v3/contractattachment?id={{contractId}}&subId={{subAttachmentId}} API endpoint to get the details of the attached document.
• Deleting a Contract Attachment: Use DELETE checkout/v3/contractattachment?id={{contractId}}&subId={{subAttachmentId}} API endpoint to delete the attachment added to the contract.

Pending Items

• Customer API Tryout links
• Card Account API Tryout links
• All other endpoints mentioned need to be linked to API tryouts