Scheduled payment events and troubleshooting
Use scheduled payment events and troubleshooting checks to monitor scheduled collections and diagnose common issues.
Lifecycle events
Each stage emits an event you can act on through your module's lifecycle hooks. Event names use snake_case.
| Event | Emitted when |
|---|---|
collection_scheduled | A schedule is created from your schedule_payment action. |
collection_attempted | A pending payment is created (on or before the due date, per submissionLeadTime). |
collection_submitted | A payment is sent to the provider. |
collection_successful | The provider confirms the payment succeeded. |
collection_failed | The payment failed. |
collection_reversed | A previously successful payment was reversed, for example by a refund or chargeback. |
collection_rescheduled | A scheduled payment's date was changed. |
collection_unscheduled | A scheduled payment was cancelled before it was created. |
Troubleshooting
A scheduled payment was not created
Check that your lifecycle hook returned a schedule_payment action with all required fields. Confirm that scheduled_for, expected_amount, currency, premium_type, billing_period_start, and billing_period_end are present.
A payment was created but not submitted
Check billingSettings.batching.enabled, submitPaymentsFunction, and scheduleTimeUtc. For API payment providers, confirm that the function named in submitPaymentsFunction exists and returns one result for each input payment.
A payment was submitted after your provider cutoff
Set latestSubmissionTimeUtc comfortably before your provider's cutoff. At or after that time, the platform moves submission to the next day.
A policyholder was charged twice
Confirm that your provider submission uses payment_id as the idempotency key. The platform may redeliver a batch, and the provider should treat the same payment_id as the same charge request.
Next step
Compare your implementation with the scheduled payments example.