Scheduled payments

Scheduled payments let your collection module plan a policy's future payments and collect them automatically.

Prerequisites

Before you create scheduled payments:

1. Create a collection module.
2. Add a payment method to the policy.
3. Decide whether your provider is API-based or file-based. See Submit scheduled payments to compare the two paths and choose.
4. Confirm which hooks your module implements: lifecycle hooks such as afterPolicyIssued and afterPaymentSucceeded that return scheduling actions, plus your submission hook if you use an API provider. See Create and manage schedules and Submit scheduled payments.

How it works

A scheduled payment moves through three stages:

1. Schedule. A lifecycle hook in your module returns a schedule_payment action. The platform records the schedule. Nothing is collected yet; this is a forecast of a future payment.
2. Create. On the due date, or within the submissionLeadTime window, the platform turns the schedule into a real payment with pending status.
3. Submit. The platform sends the pending payment to a provider. For API providers, your module submits it through a hook you write.

You never call an API to create a schedule and you never write to billing tables. You return actions and write hooks; the platform does the rest.

Scheduled payment guides

Recommended path

1. Configure scheduled payments in root.config.json.
2. Create the first schedule and recurring schedules from lifecycle hooks.
3. Submit scheduled payments if you use an API provider.
4. Use events and troubleshooting to monitor the flow.
5. Compare your implementation with the scheduled payments example.