Installment

Technically, we can sell any Products by Installments. To us it, a Product (e.g. MembershipPlan) must have an installment based Price.

When you created an installment-based Price, you need to specify:

• installments_number: A number of installments the total amount should be divided to.
• recurrence: how often the installment should be paid. It’s always monthly so far, but technically it can use other intervals.

It’s possible to pay by installments:

• manually from Payer’s Billing page
• automatically by cron, when there is a Stored Payment Method exist for the Payer/Installment Owner. In this case the application will send some required email notifications to inform a Payer about upcoming charge(s).

Use Cases

We use Installment-based Prices for:

• expensive products, such as BootcampCohort (deprecated).
• for less expensive Products when a one-time payment attempt failed due to "insufficient funds" error (e.g. for MembershipPlan)

Payments by Installments

When a Payer buys a Product with an installment-based Price, the application creates a set of Installments for the Payer (installments_number pcs.). In the current implementation, the first installment should be paid immediately, and the rest of them should be paid monthly (see recurrence).

Within the first installment, the application creates an Installments schedule that is basically a set of scheduled Installments:

On this diagram, pending is a state when the application will make charge attempts.

Lifecycle

Installment has few dates:

• pay_at: A time when a charge should be made for the Installment. Usually we make few attempts to charge between pay_at and stop_attempts_at. If we haven’t able to charge a Customer, we recall the product/service, associated with the Installment.
• stop_attempts_at: A deadline when charge attempts should be stopped. If we were not able to charge a Customer, we recall the product/service, associated with the Installment.
• paid_at: A time when the application received a successful payment for the Installment.

• Upcoming: before pay_at date. Usually, a Payer can pay it manually anytime.
• Pending: between pay_at and stop_attempts_at dates. The application is trying to pay it automatically (till successful payment or stop_attempts_at date).
• Overdue: it was not paid before the stop_attempts_at date. Usually, a Payer can still manually pay it, but the application will stop trying to pay it automatically. Also, MEx should handle such cases manually.
• Paid: an installment that was paid successfully.
• Canceled: Product was cancelled (e.g. MembershipPlan) or we received payment using an alternative way. To improve diagram readability, we have hidden Upcoming --> Canceled, Pending --> Canceled and Unpaid --> Canceled state transitions. They are possible, but not common: it’s when a Payer cancels the Product.