Recurring payments

Recurring payments can be used to charge customers on a regular basis or to offer automatic top-ups with credits-based services. Since the amount for a recurring payment is variable, other innovative use-cases are possible as well. Like doing a partial prepayment and later a final recurring payment, for more expensive products. Or charging a customer in your Dashboard manually, for orders by phone. Recurring payments happen in the background so the customer goes through payment steps only once for the first payment.

Reducing the risk of chargebacks

To reduce the risk of chargebacks, it's recommended to communicate how often and how much the customer will be charged as clearly as possible. We suggest notifying the customer a couple of days in advance of the next payment. You can display an alert in their account or notify by email.

How to get started

In the following sections we explain the following topics.

Setting up the first payment

In order to get started with recurring payments you need to require the customer's consent through a first payment. It's like a regular payment but the customer is shown information about your organization, and they need to complete the payment with the account or card that will be used for recurring charges in the future. After the first payment is completed succesfully the customer's account or card will immediately be chargeable on-demand, or periodically through subscriptions.

  1. Create a unique customer using the Customer API.

    Request code

    $customer = $mollie->customers->create([
        "name"  => "Customer A",
        "email" => "customer@example.com",
    ]);
  2. Save the customer's id in your database. You need it when performing Payments API calls.
  3. Set the recurringType parameter to first to Create a first payment for this customer.

    Request code

    $payment = $mollie->payments->create([
        'amount'        => 0.01,          // 1 cent or higher
        'customerId'    => $customer->id,
        'recurringType' => 'first',       // important
        'description'   => 'First payment',
        'redirectUrl'   => 'https://webshop.example.org/order/12345/',
        'webhookUrl'    => 'https://webshop.example.org/payments/webhook/', // optional
    ]);
  4. Redirect the customer to the paymentUrl to complete the first payment.
  5. Once completed there will be a customer mandate that you can access via the Mandates API.

Note: Not all payment methods support a first payment. When the method parameter is not provided in the API, we take care of this automatically in our Checkout. The following payment methods support a first payment and are thus allowed as a value for the method parameter: belfius creditcard ideal kbc mistercash sofort

Charging immediately on-demand

Now that the customer has given their consent, it's possible to perform a recurring payment on-demand. Instead of the regular payment with a redirectUrl, a recurring payment happens in the background without a browser session, without the customer going through payments steps. You can create a recurring payment with the recurringType set to recurring when creating a payment with the Payments API.

Please note that in order to do recurring payments, direct debit or credit card has to be activated on your profile.

  1. Make sure the customer has valid mandates. Find out using the Mandates API.

    Request code

    $mandates = $mollie->customers_mandates->withParentId("cst_4qqhO89gsT")->all();
  2. If there's at least one mandate with a status of valid then continue.
  3. Set the recurringType parameter to recurring to charge the customer on-demand.

    Request code

    $payment = $mollie->payments->create([
        'amount'        => 25.00,
        'customerId'    => $customer->id,
        'recurringType' => 'recurring',       // important
        'description'   => 'Background payment',
    ]);
  4. Like regular payments your webhook is called for retrieving status updates.

Charging periodically with subscriptions

For simple regular recurring payments with constant amounts, you can create subscriptions with the Subscriptions API. Subscription payments will be spawned automatically at the specified frequency, and will show up in your Dashboard.

  1. Make sure the customer has a pending or valid mandate using the Mandates API.

    Request code

    $mandates = $mollie->customers_mandates->withParentId("cst_4qqhO89gsT")->all();
  2. Continue if there's a mandate with its status being either pending or valid, otherwise set up a first payment for the customer first.
  3. Create the subscription using the Subscriptions API.

    Request code

    $subscription = $mollie->customers_subscriptions->withParentId("cst_stTC2WHAuS")->create([
        "amount"      => 25.00,
        "times"       => 4,
        "interval"    => "3 months",
        "description" => "Quarterly payment",
        "webhookUrl"  => "https://webshop.example.org/payments/webhook", // optional
    ]);
  4. In the above example the customer is charged €25.00 every 3 months, starting today.
  5. The webhook URL will be triggered for every payment to communicate any status updates.

On the Mollie GitHub page you'll find our API clients that include more examples.

How do webhooks for subscriptions work?

When using our Subscriptions API to charge a customer periodically, new payments are created by Mollie every time the customer is charged. We will call your webhook as usual for these payments. The only difference is, the payment ID will not be known by your system yet when we call the webhook to report the payment's status.

The payment object will, however, contain a subscriptionId field that contains the subscription ID you've received when the subscription was created. This allows you to recognize where the payment belongs to.

We currently do not provide webhooks specifically for status changes of a Subscription itself.