API Reference

Create a PaymentPlan

post
https://api.vcita.biz/v3/sales/payment_plans

Create a PaymentPlan that charges the client's saved card on a recurring schedule. Omit payment_request_uid for a standalone plan; supply it to collect against an open invoice.

amount is validated, not derived. For a linked plan, divide the invoice's open balance by cycles and round up to two decimals — the final installment is then clamped down to the balance that actually remains, so the invoice lands on exactly zero. A 1,000.00 invoice over 3 cycles takes amount: 333.34, collecting 333.34, 333.34 and 333.32.

cycles is required for every frequency_type except one_time, where it is ignored and stored as 1.

Available for Staff Tokens.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required

A short name for the plan, shown to the staff member and to the client (e.g., "Kitchen remodel plan")

string

A free-text description of the plan (e.g., "3 monthly installments for invoice #1042")

string | null

The payment request this plan collects against.

  • When set — the plan is linked: each installment is charged against that payable's open balance instead of creating a standalone charge, reducing the invoice balance until it is paid.
  • When null — the plan is standalone: each installment is an independent charge, unconnected to any invoice.

Only an open invoice's payment request may be linked, and the value is immutable after creation. Treat it as an opaque identifier — the length varies by payable type. Obtain it from GET /business/payments/v1/payment_requests (e.g., "a1b2c3d4e5f6g7h8")

number
required

The amount charged per installment, in the plan's currency. Must be greater than 0. For a linked plan this is the per-installment amount the client calculated by dividing the invoice balance across cycles and rounding up to two decimals; the last installment is then clamped down to the remaining balance, so the amount actually collected on the final cycle may be lower than this value. (e.g., 333.34)

string
required

Three-letter ISO 4217 currency code. For a linked plan this must equal the currency of the linked payment request (e.g., "USD", "EUR", "GBP")

integer
1 to 100

The total number of installments the plan will collect. Must be between 1 and 100. Required unless frequency_type is one_time, in which case it is ignored and stored as 1 (e.g., 3)

string
enum
required

How often the plan collects an installment.

  • one_time - A single payment on start_date.
  • weekly - Every week.
  • bi_weekly - Every two weeks.
  • monthly - Every month.
Allowed:
date-time
required

When the first installment is collected, in ISO 8601 format (e.g., "2026-09-01T09:00:00Z")

string
required

The unique identifier of the client's matter this plan belongs to. For a linked plan this must be the same matter the payment request sits on (e.g., "m1m2m3m4m5m6m7m8")

boolean
required

Whether a receipt is emailed to the client after each collected installment. For a linked plan the receipt's subject is the invoice.

Required when creating a plan, but not returned in responses (e.g., true)

string
enum
required

The kind of saved payment method charged on every installment. Only a saved card is supported today (e.g., "card")

Allowed:
string
required
length ≤ 16

The unique identifier of the saved payment method to charge. It must belong to the matter's client and use the same payment provider as the business's payment gateway. For card, obtain it from GET /platform/v1/clients/{client_id}/payment/cards (e.g., "c1c2c3c4c5c6c7c8")

Responses

Updated about 1 hour ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 1 hour ago

Did this page help you?