Skip to main content

​
Installment Plans

Installment plans let your customers pay in scheduled increments. You define the total amount, number of payments, and frequency — ZendFi calculates the per-installment amount and generates a payment schedule automatically.

​
Create an Installment Plan

POST /api/v1/installment-plans
​
customer_wallet
string
required
Solana wallet address of the customer.
​
customer_email
string
Optional email for notifications.
​
total_amount
number
required
Total amount to be paid across all installments.
​
installment_count
integer
required
Number of installments to split the total into.
​
payment_frequency_days
integer
required
Days between each installment due date.
​
first_payment_date
string
ISO 8601 date for the first installment. Defaults to tomorrow.
​
description
string
Description of what this plan covers.
​
late_fee_amount
number
Fee charged for late payments.
​
grace_period_days
integer
default:"7"
Days after due date before an installment is considered late.
​
metadata
object
Arbitrary key-value pairs.

​
Example

curl -X POST https://api.zendfi.tech/api/v1/installment-plans \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "customer_email": "buyer@example.com",
    "total_amount": 1200.00,
    "installment_count": 4,
    "payment_frequency_days": 30,
    "description": "Premium package - quarterly payments",
    "grace_period_days": 7
  }'

​
Response

{
  "id": "plan_test_abc123",
  "merchant_id": "merch_xyz789",
  "customer_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "customer_email": "buyer@example.com",
  "total_amount": 1200.00,
  "installment_count": 4,
  "amount_per_installment": 300.00,
  "paid_count": 0,
  "status": "active",
  "description": "Premium package - quarterly payments",
  "late_fee_amount": null,
  "grace_period_days": 7,
  "payment_schedule": [
    {
      "installment_number": 1,
      "due_date": "2026-04-01T00:00:00Z",
      "amount": 300.00,
      "status": "pending",
      "payment_id": null,
      "paid_at": null
    },
    {
      "installment_number": 2,
      "due_date": "2026-05-01T00:00:00Z",
      "amount": 300.00,
      "status": "pending",
      "payment_id": null,
      "paid_at": null
    }
  ],
  "created_at": "2026-03-01T12:00:00Z",
  "updated_at": "2026-03-01T12:00:00Z"
}

​
List Merchant Installment Plans

GET /api/v1/installment-plans
Returns all installment plans created by the authenticated merchant.
​
limit
integer
default:"50"
Maximum number of results.
​
offset
integer
default:"0"
Number of results to skip.
const plans = await zendfi.listInstallmentPlans();

​
Get an Installment Plan

GET /api/v1/installment-plans/{plan_id}
​
plan_id
string
required
Installment plan ID.
const plan = await zendfi.getInstallmentPlan('plan_test_abc123');

​
List Customer Installment Plans

GET /api/v1/customers/{customer_wallet}/installment-plans
Returns all installment plans for a specific customer wallet.
​
customer_wallet
string
required
Customer’s Solana wallet address.
const customerPlans = await zendfi.listCustomerInstallmentPlans(
  '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU'
);

​
Get Next Due Installment

GET /api/v1/installment-plans/{plan_id}/next-due
Returns the next pending or late installment for a plan.
​
plan_id
string
required
Installment plan ID.

​
Response

{
  "installment_number": 2,
  "due_date": "2026-05-01T00:00:00Z",
  "amount": 300.00,
  "status": "pending",
  "payment_id": null,
  "paid_at": null
}

​
Pay an Installment

POST /api/v1/installment-plans/{plan_id}/pay
Creates a payment for the next due installment. The payment follows the standard payment flow and settles to the merchant wallet.
​
plan_id
string
required
Installment plan ID.
curl -X POST https://api.zendfi.tech/api/v1/installment-plans/plan_test_abc123/pay \
  -H "Authorization: Bearer zfi_test_your_key"

​
Cancel an Installment Plan

POST /api/v1/installment-plans/{plan_id}/cancel
Cancels an active plan. Any remaining unpaid installments are voided.
​
plan_id
string
required
Installment plan ID.
curl -X POST https://api.zendfi.tech/api/v1/installment-plans/plan_test_abc123/cancel \
  -H "Authorization: Bearer zfi_test_your_key"

​
Plan Lifecycle

​
Status Reference

Plan StatusDescription
activePlan is in progress with pending installments
completedAll installments have been paid
defaultedCustomer missed payments beyond the grace period
cancelledPlan cancelled by merchant
Installment StatusDescription
pendingNot yet due or awaiting payment
paidPayment confirmed on-chain
latePast due date but within grace period