Installments

The Installments API lets merchants offer buy-now-pay-later style payment plans. A merchant can collect an optional upfront deposit and then automatically charge the customer on a recurring schedule until the full amount is paid.

This page is intentionally high-level. It explains the model, the lifecycle, and the automatic behaviors so teams know how installment billing works before they move into endpoint-level implementation.

Overview

Installments are designed for finite payment plans.

Unlike an ongoing subscription, an installment has a defined payoff structure:

• a total amount to collect
• an optional deposit charged up front
• a recurring payment amount
• a number of cycles
• a payment token to charge against

The system automatically generates the future charge schedule and processes each charge on its due date.

Supported recurring cadences include:

• weekly
• biweekly
• monthly
• every 28 days

Related Endpoints

1. Create an installment
2. Delete an installment
3. Activate an installment
4. Deactivate an installment
5. Update installment payment token

Key concepts

Installment

An installment is the full payment-plan record tied to a specific customer and merchant.

It defines:

• the total amount to collect
• the optional deposit amount
• the recurring schedule
• the stored payment token used for charges

Deposit

The deposit is the optional upfront amount charged at the time the installment is created.

Payments schedule

The recurring schedule is defined by:

• frequency
• payment amount
• number of cycles

Execution

An execution is an individual scheduled charge event.

When an installment is created, the system automatically creates all future executions and then runs them on their due dates.

Payment token

Every installment charges against a payment token, such as a credit-card token or e-check token.

Business rule

The installment totals must reconcile to the full amount owed.

totalAmount = deposit.amount + (payments.amount × payments.qty)

This is the core rule to validate before creating an installment.

Status lifecycle

Installments follow this lifecycle:

INACTIVE → ACTIVE → PAUSED
             ↑
             └── resume via updatePaymentToken

An installment moves to PAUSED after three consecutive payment failures.

Automatic behaviors

Auto-charge

The system automatically runs each scheduled execution on its due date.

Retry logic

If a scheduled charge fails, the system retries it. After three consecutive failures, the installment moves to PAUSED.

Resume flow

A paused installment can be resumed by updating the payment token.

Webhooks

The system automatically emits these events:

• ON_INSTALLMENT_CREATED
• ON_INSTALLMENT_ACTIVATED
• ON_INSTALLMENT_DEACTIVATED
• ON_INSTALLMENT_PAUSED
• ON_EXECUTION_SUCCEEDED
• ON_EXECUTION_FAILED

Card validation when no deposit is charged

If no deposit is collected at creation time, the system performs a $1 authorization and then voids it immediately to validate the card.

Typical lifecycle

1. Define the payment plan

Confirm the total amount, deposit, payment amount, quantity, and recurring cadence.

2. Validate the math

Make sure the installment follows the required total-amount formula before you create it.

3. Attach a payment token

Use a valid credit-card token or e-check token that the system can charge throughout the life of the plan.

4. Create the installment

When the installment is created, the platform generates the future executions automatically.

5. Let the platform run the schedule

The system charges each execution on its due date and retries failed payments automatically.

6. Monitor status and webhooks

Watch execution outcomes and lifecycle events so support and operations teams can react quickly.

7. Recover paused installments

If repeated failures pause the installment, update the payment token to resume the plan.

When to use installments

Use installments when the customer is paying toward a fixed total over a known number of payments.

Common examples include:

• split-pay offers
• deposit plus follow-up payments
• buy-now-pay-later style payment plans
• short-term financed purchases with a defined payoff schedule

Operational notes

Monthly vs. every 28 days

These are not the same schedule.

• Monthly follows calendar months
• Every 28 days follows a fixed four-week cadence

Be explicit about which behavior the merchant expects.

Why a customer may see a $1 auth

If there is no deposit on creation, the platform validates the card with a $1 authorization and immediate void. This is expected behavior.