Installment plans

Installment plans can be used to periodically charge customer by specifying the amount and scheduling information. With the PayPro Installment plans API, you can set up recurring payments with fixed amounts.

Unlike subscriptions, which continue indefinitely, an installment plan is designed for a specific number of payments and a fixed total amount. After the initial payment, subsequent installments are processed automatically until the plan is completed.

This guide is focused on creating installment plans with the API, but you can also use our no code solutions like the Payment page or other integrations.

Installment plan flows

There are two primary ways to create an installment plan:

• Installment plan with an Authorization Payment: The customer makes the first payment, and then a mandate is saved for future billing.

• Installment plan with an Existing Mandate: If you already have the customer’s mandate, you can start the installment plan without an authorization payment.

Creating an Installmen plan

To create an installment plan, follow these basic steps:

1. Create a Customer: Use the Customer API to create a new customer or use an existing customer ID.
2. Create an Installment plan: Use the Installment plan API to set up an installment plan for the customer.
3. Listen for Webhook Events: Set up webhook listeners to handle events like installment plan cancellations, payment confirmations, and chargebacks.

Create a Customer

The first step in setting up an installment plan is to create a Customer. This Customer object represents represents the entity (person or company) that will be billed. You can create a Customer using the Customer API.

PHP

$customer = $paypro->customers->create(
  [
    'email' => 'customer@example.com',
    'first_name' => 'First name',
    'last_name' => 'Last name'
  ]
);

Ruby

client = PayPro::Client.new('pp_...')

customer = client.customers.create(
  email: 'customer@example.com',
  first_name: 'First name',
  last_name: 'Last name'
)

Once the Customer object is created, you can use it to set up an installment plan by referencing the customer's unique ID.

Create a Installment plan with an Authorization Payment

To create a installment plan, use the Installment plan API.

When creating a installment plan, you need to provide:

• customer: The ID of the customer who is subscribing.
• description: A description of the installment plan.
• currency: The currency code for the installment plan.
• period: The settings for recurring billing, defining when new periods should be created and their amounts. The period parameter includes the following fields:
  • amount: The billing amount for each period.
  • vat: The VAT (tax) applied to each period.
  • interval: The frequency of the billing period (e.g., week, month).
  • multiplier: The number of intervals between each billing (e.g., every 1 month, every 3 months).
• number_of_periods: The number of installment plan periods.

Optionally, you can specify additional payment details, such as return_url - the URL to which the customer will be redirected after the payment is processed. More details are available here.

PHP

$installment_plan = $paypro->installment_plans->create(
  [
    'customer' => 'CUSTOMER_ID',
    'description' => 'Installment plan description',
    'currency' => 'EUR',
    'period' => [ 'amount' => 500, 'vat' => 21, 'interval' => 'month', 'multiplier' => 1 ],
    'number_of_periods' => 3
  ]
);

Ruby

installment_plan = client.installment_plans.create(
  customer: 'CUSTOMER_ID',
  description: 'Installment plan description',
  currency: 'EUR',
  period: { amount: 500, vat: 21, interval: 'month', 'multiplier': 1 },
  number_of_periods: 3
)

Once the installment plan object is created, you can redirect the customer to the checkout URL to complete the first payment. This checkout link is available in the created installment plan object:

PHP

$checkout_url = $installment_plan->links['checkout'];
header('Location: ' . $checkout_url);
exit();

Ruby

# This assumes you are using Rails which has a redirect_to method
checkout_url = installment_plan.links['checkout']
redirect_to checkout_url

When redirecting the customer to the checkout URL, they will leave your site. Depending on the payment method, they may need to provide additional information and could be directed to their bank or card issuer to authenticate the transaction.

After the customer completes the payment, they will be redirected either to a PayPro hosted success page or to the return_url specified in the payment_details. The installment plan status will become "active" once the payment is successfully processed.

Create a Installment plan with a Mandate

Recurring payments, like with an Installment plan, require a Mandate from the Customer. A Mandate symbolizes the permission the Customer gave you to charge their payment method. When using the authorization flow we automatically create a Mandate object when the Customer pays, but you can also create mandates for your customers manually.

For instance, if you already have the customer's IBAN and account holder name, you can create a "direct-debit" mandate using the create Mandate API. This "direct-debit" mandate can than be used to create subscriptions without having to go through the authorization flow.

IMPORTANT

To create mandates you still the need permission from the customer. When creating a mandate make sure to clearly state that the customer will agree to additional charges. Communicating this clearly will also lead to less chargebacks and costs.

PHP

$payment = $paypro->mandates->create(
  [
    'customer' => 'CUSTOMER_ID',
    'pay_method' => 'direct-debit',
    'iban' => 'IBAN',
    'account_holder_name' => 'Account Holder Name'
  ]
);

Ruby

payment = client.mandates.create(
  customer: 'CUSTOMER_ID',
  pay_method: 'direct-debit',
  iban: 'IBAN',
  account_holder_name: 'Account Holder Name'
)

After creating the mandate, you can proceed to create the installment plan. Since a mandate belongs to a customer, there's no need to specify a separate CUSTOMER_ID when creating the subscription this way.

PHP

$installment_plan = $paypro->installment_plans->create(
  [
    'mandate' => 'MANDATE_ID',
    'description' => 'Installment plan description',
    'currency' => 'EUR',
    'period' => [ 'amount' => 500, 'vat' => 21, 'interval' => 'month', 'multiplier' => 1 ],
    'number_of_periods' => 3
  ]
);

Ruby

installment_plan = client.installment_plans.create(
  mandate: 'MANDATE_ID',
  description: 'Installment plan description',
  currency: 'EUR',
  period: { amount: 500, vat: 21, interval: 'month', 'multiplier': 1 },
  number_of_periods: 3
)

The installment plan will be created and will become "active" immediately, with payments automatically processed based on the installment plan period.

Set up Installment plan with a First Period

To offer a different first period for an installment plan, use the first_period parameter when creating the plan. This parameter defines the initial period and includes attributes such as:

• amount: The charge amount for the first period.
• vat: The VAT (tax) applied to the first period.
• interval: The interval of the first period (e.g., day, week, month).
• multiplier: The number of intervals in the first period (e.g., 1 month, 2 weeks).

Once the first period ends, the installment plan automatically transitions to the regular billing period specified in the period parameter.

PHP

$installment_plan = $paypro->installment_plans->create(
  [
    'mandate' => 'MANDATE_ID',
    'description' => 'Installment plan description',
    'currency' => 'EUR',
    'first_period' => [ 'amount' => 100, 'vat' => 21, 'interval' => 'week', 'multiplier' => 2 ],
    'period' => [ 'amount' => 500, 'vat' => 21, 'interval' => 'month', 'multiplier' => 1 ],
    'number_of_periods' => 3
  ]
);

Ruby

installment_plan = client.installment_plans.create(
  mandate: 'MANDATE_ID',
  description: 'Installment plan description',
  currency: 'EUR',
  first_period: { amount: 100, vat: 21, interval: 'week', 'multiplier': 2 },
  period: { amount: 500, vat: 21, interval: 'month', 'multiplier': 1 },
  number_of_periods: 3
)

Installment plan Actions

You can manage the installment plan's lifecycle with the following actions:

• Pause Installment plan: You can temporarily pause a installment plan using the pause installment plan endpoint. While paused, no new installment plan periods will be created.

• Resume Installment plan: After a installment plan has been paused, you can reactivate it by calling the resume endpoint. The paused installment plan will return to the active state and will resume creating new installment plan periods.

• Cancel Installment plan: To permanently end a installment plan, use the cancel endpoint. A canceled installment plan will no longer create new installment plan periods. Once canceled, the installment plan cannot be resumed.

Listen for Webhook Events

It is important to stay informed about changes to installment plan statuses, such as when a user completes their first payment and the installment plan becomes "active."

To track these events, we recommend implementing our Webhooks. Webhooks will notify you about changes to various resources, including installment plans, created through our API. This allows you to take real-time actions based on installment plan events.

For more details on how to set up and manage webhooks, visit the webhooks page.

Difference between Installment plan and Subscription

Here you find a quick overview of the differences between an Installment plan and Subscription

	Installment plan	Subscription
Periods	Fixed number	Infinite (unless specified)
Amount	Fixed amount	Flexible per period
Invoicing	One invoice per installment plan	Invoice per period
Automatically stops	Always	Only when specified
Cancelling	Creates a credit invoice for the outstanding amount	Will not credit invoices

NOTE

When in doubt which API to use we recommend to use the Subscriptions API since it offers more flexibility and supports more use-cases.