Understanding Payment Plans

What is a payment plan

A payment plan is a schedule of recurring payments for a customer. The portal’s scheduler automatically creates payment intents for each upcoming payment date and processes them using the customer’s saved payment method.

Payment plans are created and managed in the portal. The API handles the individual payment intents that the scheduler creates.

Frequency options

Frequency type	Code	Example
Weekly	W	Every week
Monthly	M	Every month

Set a period to change the interval — period 2 with type W means every 2 weeks; period 3 with type M means every 3 months.

Amount structure

Field	Description
recurring_amount_cents	Amount for each scheduled payment (min 200, max 100,000 cents)
first_amount_cents	Optional different amount for the first payment
total_amount_cents	Optional fixed total, at most $999,999.99. Once it’s collected, the plan schedules nothing more but stays active: see When a plan reaches its total
until_further_notice	true for open-ended plans with no total amount

If neither total_amount_cents nor until_further_notice is set, the plan must be closed manually.

Plan states

State	Description	Payments scheduled?
draft	Created but not activated	No
active	Running and scheduling payments	Yes
inactive	Paused — future unprocessed intents deleted	No
suspended	Active, but not collecting until it’s resumed: suspended by you, by a failed payment method, or for your review. See Suspended plans	No: payments due meanwhile are skipped
closing	Collecting its final payments before it closes	Only its final payments
closed	Permanently ended; nothing more is collected	No

A closing plan can be suspended too, by a failed payment method or for your review: it shows as Closing and Suspended, and its final payments wait until it’s resumed.

Activate a draft plan to begin scheduling. A draft plan also activates automatically when a payment method is collected via the customer-creation or Collect Payment Details flow. An active plan can be closed, optionally collecting a final amount first; an inactive or suspended one with a final amount of 0. See Closing a plan.

When a plan reaches its total

A plan with a total stops scheduling payments once the payments sent for it cover the total. It stays Active, and the plan page says No further payments expected. It doesn’t wait for the money to settle. Through the API and MCP, remaining_amount_cents is 0 and there is no next_date: nothing more will be scheduled. The plan’s payments show whether the last ones have been sent or settled.

The plan isn’t closed, so it still follows its failure behaviour:

• If a payment fails later, for example a bank debit dishonoured or returned after it was collected, the plan collects it again under its failure behaviour:
  • NEW_AT_END collects it on the plan’s next payment date;
  • TRY_AGAIN retries it three days after the failure, or on the next payment date if that comes first;
  • DOUBLE_UP collects it one period after the failed payment, or today if that has passed;
  • DO_NOTHING takes it off the total, and nothing more is collected.
• A refund or a chargeback isn’t collected again. A refunded payment still counts as collected.
• You can still change the plan. Raise its total or add a payment to collect more, or deactivate it. Closing it with a final amount of 0 closes it once any payments still being processed have gone through, and a payment that fails after that isn’t collected again.

How payments are created

A plan schedules its payments up to 366 days ahead of today, in your time zone. Every Sunday the portal extends each plan’s schedule to 366 days ahead again, and any change to a plan does the same at once. So a plan that runs until further notice always has about a year of payments scheduled, and a plan with a total keeps scheduling until it reaches the total, however long that takes.

Each payment a plan schedules is a payment intent, with a process_at timestamp for its date. The portal’s payment intent is the record of the payment’s state: the dashboard, the API and MCP all read it.

When a payment falls due, the portal checks it again before sending it:

• Its plan is suspended on that date, or inactive: it isn’t sent. See Suspended plans.
• Its payment method has stopped, for example after a decline the card scheme says never to retry: it waits for a new payment method. See Payment method recovery.

Otherwise it’s sent on the plan’s payment method:

• Card: the portal hands the payment to ElasticPay’s payment service, which charges the card and reports the outcome back to the portal as soon as the card network answers.
• Bank debit (BECS Direct Debit): the portal adds the debit to its next file for the bank. The outcome comes from the bank: the debit clears, or it’s dishonoured, which can be days after it was sent. See Processing and settlement.

The payment intent then becomes succeeded or failed, and the plan records the outcome. A failed payment follows the plan’s failure behaviour.