# Autopay



import Image from 'next/image';

Overview [#overview]

The *Autopay* feature enables insureds to set up a payment method and have regular payments executed automatically, so they don't have to worry about mailing a physical check or going online before the due date and possibly incurring late fees or policy lapses. This also leads to more predictability for payments and fewer mismatches between payments and amounts due.

The typical autopay process looks like this:

* Add an `autopayLeadDays` setting to your installment plans. This specifies the number of days before invoices become due that the autopay process will start.
* Installments and invoices will have their `autopayTime` value set using the lead days.
* At the autopay time for an invoice, the *Autopay Plugin* will fire.
* The plugin may be implemented to create a <ApiLink name="PaymentResponse">Payment</ApiLink> in `requested` state.
* The [Payment Execution Service](/features/billing/payment-execution-service) will attempt to execute the actual transaction with an external financial institution.
* If successful, the payment will advance to `posted` state and settle the invoice; otherwise retries may be attempted.

Installments and Invoices [#installments-and-invoices]

When [installments](/features/billing/installments-and-installment-lattices) are generated, the `autopayTime` will be set using the `autopayLeadDays` property on the installment plan. This time will be used to set the `autopayTime` on the invoice when it is generated.

If more than one installment is added to an invoice, the invoice's autopay time will be the *earliest* autopay time of its installments.

The autopay timing looks like this:

<Image src="/images/autopay/autopay-timing.png" alt="autopay timing" width={800} height={337} unoptimized />

<Callout>
  To suppress autopay for an invoice, you can set its `suppressAutopay` property to `true` using the <ApiLink name="updateInvoice" /> endpoint.
</Callout>

<span id="autopay-plugin" />

Autopay Plugin [#autopay-plugin]

The autopay plugin will receive the invoice for which autopay has triggered. It may then optionally provide a response with a <ApiLink name="PaymentCreateRequest" /> and a `next_request_time`. If a payment create request is returned, a payment will be created with the given data, including:

* The `type` of the payment, which must be one of the payment types configured
* The `amount` (typically this would be the same as the invoice amount)
* The desired payment `state` (typically `requested`)
* The `currency`, to match the invoice's currency
* The locator of the financial instrument which will be used to clear the payment
* The `targets` for the payment (typically the invoice itself)
* The `retryPlan` for the payment's execution, if it is desired to use a specific plan for this payment
* And any extension data needed to be tracked on the payment

If `next_request_time` is not specified, the payment execution service will be started immediately. You can set this to some time in the future to delay the first call to the external system.

<Callout>
  You may choose to call to an external system from the autopay plugin and execute the payment. If this is done, you can create the payment in `posted` state and the payment execution service will not be invoked.
</Callout>

Payment Requests [#payment-requests]

After a payment is created in `requested` state the [payment execution service](/features/billing/payment-execution-service) will take over. The overall flow looks like this:

<Image src="/images/autopay/autopay-payment-request-flow.png" alt="autopay payment request flow" width={800} height={345} unoptimized />

See Also [#see-also]

* [Payments](/features/billing/payments)
* [Payment Execution Service](/features/billing/payment-execution-service)
* [Plugins Overview](/configuration/plugins/overview)
* [Payment Execution Plugin](/configuration/plugins/autopay-and-payment-execution)
* [Payments API](/api/billing/payments)
* [Payments Execution API](/api/billing/payment-execution)