Direct Debit: Taking Instalment Payments

Using instalment schedules

Finally, let’s try collecting payments using an instalment schedule. Instalment schedules collect a finite set of recurring payments from a customer.

Let’s say we have an invoice for £100. We want to collect this in 3 instalments, with a cadence of 1 instalment every 2 weeks:

<?php
require "vendor/autoload.php";

$client = new \GoCardlessPro\Client([
    "access_token" => $currentUser->gocardlessAccessToken,
    "environment" => \GoCardlessPro\Environment::SANDBOX
]);

$instalment_schedule = $client->instalmentSchedules()->createWithSchedule([
    "params" => [
        "name" => "ACME Invoice 103",
        "total_amount" => 10000, // 100 GBP in pence, collected from the customer
        "app_fee" => 10, // Your 10 pence fee, applied to each instalment,
                         // to be paid out to you
        "currency" => "GBP",
        "schedule" => [
            "start_date" => "2019-08-20",
            "interval_unit" => "weekly",
            "interval" => "2",
            "amounts" => [
                3400,
                3400,
                3200
            ]
        ],
        "links" => [
            "mandate" => "MD0000XH9A3T4C"
                         // Mandate ID from the last section
        ],
        "metadata" => []
    ],
    "headers" => [
        "Idempotency-Key" => "random_instalment_schedule_specific_string"
    ]
]);

// Keep hold of this instalment schedule ID - we"ll use it in a minute
// It should look a bit like "IS00006FWHUIA"
print("ID: " . $instalment_schedule->id);

GoCardless will take responsibility for calculating the estimated charge dates of these payments. The charge date scheduling semantics are as follows:

We will create the first payment as close to the specified start date as possible.
The subsequent payment will be as close to two weeks after the specified start date as possible.

The important clarification is that we will always schedule from the originally specified start date, not the realised charge date of the first payment.

We will then debit £34, £34, and £32 from the end customer’s bank account in the 6 weeks following the specified charge date.

Charged on	2019-08-20	2019-09-03	2019-09-17
Amounts charged	£34.00	£34.00	£32.00

Scheduling Instalments

For your convenience, we also provide you with the ability to schedule the payments yourself if you have a specific or irregular cadence with which you’d like to collect instalments:

<?php
require "vendor/autoload.php";

$client = new \GoCardlessPro\Client([
    "access_token" => $currentUser->gocardlessAccessToken,
    "environment" => \GoCardlessPro\Environment::SANDBOX
]);

$instalment_schedule = $client->instalmentSchedules()->createWithDates([
    "params" => [
        "name" => "ACME Invoice 103",
        "total_amount" => 10000, // 100 GBP in pence, collected from the customer
        "app_fee" => 10, // Your 10 pence fee, applied to each instalment,
                         // to be paid out to you
        "currency" => 'GBP',
        "instalments" => [
            [
                "charge_date" => '2019-08-20',
                "amount" => 3400
            ],
            [
                "charge_date" => '2019-09-03',
                "amount" => 3400
            ],
            [
                "charge_date" => '2019-09-17',
                "amount" => 3200
            ],
          ],
          "links" => [
              "mandate" => 'MD0000XH9A3T4C'
                           // Mandate ID from the last section
          ],
          "metadata" => []
      ],
      "headers" => [
          'Idempotency-Key' => 'random_instalment_schedule_specific_string'
    ]
]);

// Keep hold of this instalment schedule ID - we'll use it in a minute
// It should look a bit like "IS00006FWHUIA"
print("ID: " . $instalment_schedule->id);

We will try to create the payments as close to the charge dates you specify as possible.

The process of setting up all the payments for an instalment schedule is quite expensive. For this reason, the instalment schedule starts off in the “pending” state and remains in this state while we create all the instalments for it. If you want to inspect the created instalment schedule yourself, we can do this using the instalment schedule ID which is returned when making the request to create the schedule:

GET https://api.gocardless.com/instalment_schedules/IS00006FWHUIA

HTTP/1.1 200 (OK)
{
  "instalment_schedules": {
    "id": "IS123",
    "name": "Bike Invoice 271",
    "currency": "GBP",
    "status": "pending",
    "amount": "10000",
    "metadata": {},
    "links": {
      "mandate": "MD0000XH9A3T4C",
      "payments": []
    }
  }
}

This should return the instalment schedule object we just created.

Once all the related payments for an instalment schedule have been created, it will transition into the “active” state. We will send you a webhook to notify you of this change. If you do not wish to rely on webhooks, we’d recommend polling the GET endpoint to check when an instalment schedule becomes active. Once all the instalments for a schedule have been created, their IDs will be included under the payments key in the “links” attribute of the response object.

Listing and cancelling a schedule

Let’s imagine that we no longer want to collect the payment in instalments, and we need to cancel the instalment schedule. This is accomplished as follows:

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    'access_token' => $currentUser->gocardlessAccessToken,
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$instalment_schedule = $client->instalment_schedules()->get("IS00006FWHUIA");
                                        // Instalment Schedule ID from above.

print("Status: " . $instalment_schedule->status . "<br />");
print("Cancelling...<br />");

$instalment_schedule = $client->instalment_schedules()->cancel("IS00006FWHUIA");

print("Status: " . $instalment_schedule->status . "<br />");

Cancelling an instalment schedule will cancel all remaining payments (i.e. payments that are not submitted, collected or failed) in the schedule. If you wish to collect the leftover amount for a given invoice, you can do so by creating a single payment to collect the remainder, or by splitting the remaining amount into a new instalment schedule. Instalment schedules cannot be cancelled if they are already cancelled, or completed. You will receive a webhook notifying you of when the instalment schedule and its remaining payments have been cancelled.

Advice on calculating your instalment amounts

You may have noticed that whilst GoCardless takes responsibility for figuring out the precise dates upon which payments will be collected, we are not prescriptive on how the original invoice amount is split between instalments. How much you charge your customers is, after all, your decision entirely!

We will use the top-level amount parameter as a checksum, to make sure all the individual instalment amounts add up to the right total. With that in mind, it’s crucial for you as the integrator to ensure you’ve worked out the right split between your instalment amounts. Below, we provide a sample algorithm (in pseudocode) to help you accomplish this:

// @param total - the total in GBP/USD etc.
// @param number_of_instalments - the number of instalments you'd like to split the
//                                invoice into

function calculateInstalmentValue(total, number_of_instalments)
{
    // work out the value of each instalment, rounded up to the nearest whole unit
    rounded_units = ceiling(total/number_of_instalments)

    if (rounded_units * (number_of_instalments - 1) >= total) {
        return floor(total / number_of_instalments);
    } else {
        return rounded_units;
    }
}

// @param total - the invoice total in GBP/USD etc.
// @param number_of_instalments - the number of instalments you'd like to split the
//                                invoice into
// @param normal_instalment_amount - the amount in pence/cents etc. for all payments
//                                   except the final 'balancing' payment

function getInstalmentAmounts(total, number_of_instalments, normal_instalment_amount)
{
    number_of_normal_instalments = floor(total / normal_instalment_amount);
    minimum = 200 // some "reasonable minimum" instalment amount

    amounts = [];

    for (i = 1; i < number_of_normal_instalments; i++) {
        amounts.push(normal_instalment_amount);
    }

    remainder = total % normalInstalmentAmount;

    if (remainder < minimum) {
        amounts[amounts.length - 1] += remainder;
    } else {
        amounts.push(remainder);
    }

    return amounts;
}

normal_instalment_amount = calculateInstalmentValue(total, number_of_instalments)
instalment_amounts = getInstalmentAmounts(
                      total,
                      number_of_instalments,
                      normal_instalment_amount
                    )

Instalment schedule modes of failure

There are two distinct “failure” states an instalment schedule can fall into. The first is creation_failed, which indicates we could not create the instalment schedule and its payments. You would be notified of this in the response to the POST create request.

The second is slightly more nuanced and is called errored. This indicates that one or more of the instalments is in a failed state. We will serve you a webhook should this occur, but you will need to reconcile the failed payment(s) yourself.

More Guides

Taking instalment payments against a mandate

Taking a one-off payment against a mandate

Taking subscription payments against a mandate

Need help?

Connect as a partner