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.