Note: You may need to fully verify your account to perform the actions in this guide. Please follow the steps here to complete verification.

Once you’ve set up Direct Debit mandates with your users’ end customers, you can start collecting payments from them using one-off payments, automatically-recurring subscriptions, or in a fixed set of instalments.

With the mandate created, you’re ready to go - there’s no need to wait for it to become active, as GoCardless will automatically submit payments at the right time to charge the end customer as soon as possible.

Three ways to collect payments

There are three ways to set up payments - which one is right for you will depend on the kinds of payments your users want to take, and how you want to manage the process through your product:

One-off payments
Trigger a payment against a mandate at any time with the API. This allows your user to charge their end customers ad-hoc amounts.

You can add an app_fee on top of GoCardless's fees or receive a share of GoCardless's collected fees.

You can use one-off payments to build your own subscriptions logic, for example if you want to add additional amounts based on usage to a fixed regular payment.

Subscriptions
Set up an automatic recurring payment. This works great for users that want to take the same payment on a regular basis (for instance £5 per week, or £20 on the first of each month).

You can add an app_fee on top of GoCardless's fees or receive a share of GoCardless's collected fees.

When you setup an app fee, your fee will be taken from every payment created for that subscription.

Instalment Schedules
Set up a fixed number of payments, billed at a cadence of your choosing. This is great for when you have an invoice too large to collect from a customer in a single payment, and thus would like to split it into smaller payments.

You can add an app_fee on top of GoCardless's fees or receive a share of GoCardless's collected fees.

When you setup an app fee, your fee will be taken from every payment created for that instalment schedule.

Your integration may either apply app fees or receive a revenue share from GoCardless's fees. No app can have both app fees and a revenue share. For more information or to set up a revenue share, contact the partnerships team.

Collecting one-off payments

Let’s start by collecting a one-off payment of £10 from an end customer:

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

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

$payment = $client->payments()->create([
  "params" => [
      "amount" => 1000, // 10 GBP in pence collected from end customer
      "app_fee" => 10, // 10 pence, to be paid out to you
      "currency" => "GBP",
      "links" => [
          "mandate" => "MD0000XH9A3T4C" // The mandate ID from last section
      ],
      // Almost all resources in the API let you store custom metadata,
      // which you can retrieve later
      "metadata" => [
          "invoice_number" => "001"
      ]
  ],
  "headers" => [
      "Idempotency-Key" => "random_payment_specific_string"
  ]
]);

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

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

payment = client.payments.create(
    params={
        "amount" : 1000, # 10 GBP in pence collected from end customer.
        "app_fee": 10, # 10 pence, to be paid out to you.
        "currency" : "GBP",
        "links" : {
            "mandate": "MD0000XH9A3T4C"
                     # The mandate ID from the last section
        },
        # Almost all resources in the API let you store custom metadata,
        # which you can retrieve later
        "metadata": {
          "invoice_number": "001"
        }
    }, headers={
        'Idempotency-Key' : 'random_key',
})

# Keep hold of this payment ID - we will use it in a minute
# It should look like "PM000260X9VKF4"
print("ID: {}".format(payment.id))

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
	environment: :sandbox
)

payment = client.payments.create(
  params: {
    amount: 1000, # 10 GBP in pence, collected from the end customer.
    app_fee: 10, # 10 pence, to be paid out to you.
    currency: 'GBP',
    links: {
      mandate: 'MD0000XH9A3T4C'
             # The mandate ID from last section
    },
    # Almost all resources in the API let you store custom metadata,
    # which you can retrieve later
    metadata: {
      invoice_number: '001'
    }
  },
  headers: {
    'Idempotency-Key' => 'random_payment_specific_string'
  }
)

# Keep hold of this payment ID - we will use it in a minute
# It should look like "PM000260X9VKF4"
puts "ID: #{payment.id}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Payment;
import com.gocardless.services.PaymentService.PaymentCreateRequest.Currency;

public class SinglePayment {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        Payment payment = client.payments().create()
            .withAmount(1000) // 10 GBP in pence collected from end customer.
            .withAppFee(10) // 10 pence, to be paid out to you.
            .withCurrency(Currency.GBP)
            .withLinksMandate("MD0000XH9A3T4C")
            .withMetadata("invoice_number", "001")
            .withIdempotencyKey("random_payment_specific_string")
            .execute();
        // Keep hold of this payment ID - we'll use it in a minute
        // It should look like "PM000260X9VKF4"
        System.out.println(payment.getId());
    }
}

const payment = await client.payments.create(
  {
    amount: 1000,
    currency: "GBP",
    links: {
      mandate: "MD0000XH9A3T4C"
    },
    metadata: {
      invoice_number: "001"
    }
  },
  "random_payment_specific_string"
);

// Keep hold of this payment ID - we'll use it in a minute
// It should look like "PM000260X9VKF4"
console.log(payment.id);

var createResponse = await client.Payments.CreateAsync(new PaymentCreateRequest
{
    Amount = 1000,
    Currency = PaymentCreateRequest.PaymentCurrency.GBP,
    Links = new PaymentCreateRequest.PaymentLinks
    {
        Mandate = "MD0000XH9A3T4C",
    },
    Metadata = new Dictionary<string, string>
    {
        {"invoice_number", "001"}
    },
    IdempotencyKey = "random_payment_specific_string"
});

var payment = createResponse.Payment;

// Keep hold of this payment ID - we'll use it in a minute
// It should look like "PM000260X9VKF4"
Console.WriteLine(payment.Id);

You’ll need to use the currency appropriate for the mandate. When an end customer goes through the Redirect Flow, we'll choose the right Direct Debit scheme based on their bank account, and each scheme supports a single currency. You will likely want to use the mandates API to read the mandate's scheme attribute, and translate that into a currency using this table:

scheme currency
bacs GBP
ACH USD
autogiro SEK
betalingsservice DKK
becs AUD
becs_nz NZD
pad CAD
sepa_core EUR
You’ll notice here that we provide an Idempotency-Key header. If we provide a unique string specific to this payment (for example its ID in our own database), the API will ensure this payment is only ever created once.

This means that if an API request times out or something goes wrong on your end, you won’t ever accidentally bill a customer twice - see our blog post for more details. You can use idempotency keys whenever you create something with the API.

In the live environment, we would debit £10.00 from the end customer’s bank account. From that, before paying it out to your user, GoCardless would deduct its fees, and any app_fee you’ve specified which would be deducted and passed on to you.

Taken from end customer's bank account £10.00
GoCardless fee £0.20
Your app_fee £0.10
Paid out to your user £9.70
If you're creating payments in bulk (or making many requests in a short period for any other reason), you'll need to make sure you don't exceed our rate limit and handle any 429 Too Many Requests errors appropriately. You can make up to 1000 requests per minute for each of your access tokens (i.e. for each of your users).

You can earn revenue from payments collected through your product either by adding an app_fee to what GoCardless charges, or by receiving a share of GoCardless’s fees.

The choice of whether you want to charge an app_fee, and if so, how much, is yours. However, it may not be more than half the value of the payment and must be made clear to your user.

For any questions about app fees, GoCardless fees or revenue sharing, please don’t hesitate to contact our partnerships team.

Creating a payment returns details on the payment you’ve set up, including its ID. Once you have the ID, you can also perform useful functions on the payment, like cancelling it or retrying it if it has failed.

Let’s try grabbing our payment, and then cancelling it, taking a look at its status before and after:

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

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

$payment = $client->payments()->get("PM000260X9VKF4");
                              // Payment ID from above

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

$payment = $client->payments()->cancel("PM000260X9VKF4");
print("Status: " . $payment->status);

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

payment = client.payments.get("PM000260X9VKF4")
                         # Payment ID from above.

print("Amount: {}".format(payment.amount))
print("Cancelling...")

payment = client.payments.cancel("PM000260X9VKF4")
print("Status: {}".format(payment.status))

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
	environment: :sandbox
)

payment = client.payments.get('PM000269VJAR6M')
                         # Payment ID from above.

puts "Status: #{payment.status}"
puts 'Cancelling...'

payment = client.payments.cancel('PM000269VJAR6M')
puts "Status: #{payment.status}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Payment;

public class CancelPayment {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        Payment payment = client.payments().get("PM000260X9VKF4").execute();
                                              // Payment ID from above.
        System.out.printf("Amount: %s%n", payment.getAmount());
        System.out.println("Cancelling...");

        payment = client.payments().cancel("PM000260X9VKF4").execute();
        System.out.printf("Status: %s%n", payment.getStatus());
    }
}

// Payment ID from above
const paymentId = "PM000260X9VKF4";

let payment = await client.payments.find(paymentId);

console.log(`Amount: ${payment.amount}`);
console.log("Cancelling...");

payment = await client.payments.cancel(paymentId);
console.log(`Status: ${payment.status}`);

// Payment ID from above
const string paymentId = "PM000260X9VKF4";

var paymentResponse = await client.Payments.GetAsync(paymentId);
var payment = paymentResponse.Payment;

Console.WriteLine($"Amount: {payment.Amount}");
Console.WriteLine("Cancelling...");

var cancelResponse = await client.Payments.CancelAsync(paymentId);
var payment = cancelResponse.Payment;
Console.WriteLine($"Status: {payment.Status}");

Using recurring subscriptions

Now, let’s create a subscription. Subscriptions collect a fixed, regular amount from a customer.

Let’s try collecting £15 per month on the 5th of each month from an end customer:

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

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

$subscription = $client->subscriptions()->create([
    "params" => [
        "amount" => 1500, // 15 GBP in pence, collected from the end customer
        "app_fee" => 10, // 10 pence, to be paid out to you
        "currency" => "GBP",
        "interval_unit" => "monthly",
        "day_of_month" => "5",
        "links" => [
            "mandate" => "MD0000XH9A3T4C"
                         // Mandate ID from the last section
        ],
        "metadata" => [
            "subscription_number" => "ABC1234"
        ]
    ],
    "headers" => [
        "Idempotency-Key" => "random_subscription_specific_string"
    ]
]);

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

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment="sandbox"
)

subscription = client.subscriptions.create(
    params={
        "amount" : 1500, # 15 GBP in pence, collected from the end customer.
        "app_fee": 10, # 10 pence, to be paid out to you.
        "currency" : "GBP",
        "interval_unit" : "monthly",
        "day_of_month" : "5",
        "links": {
            "mandate": "MD0000XH9A3T4C"
                     # Mandate ID from the last section
        },
        "metadata": {
            "subscription_number": "ABC1234"
        }
    }, headers={
        'Idempotency-Key': "random_subscription_specific_string"
})

# Keep hold of this subscription ID - we'll use it in a minute
# It should look a bit like "SB00003GKMHFFY"
print("ID: {}".format(subscription.id))

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
	environment: :sandbox
)

subscription = client.subscriptions.create(
  params: {
    amount: 1500, # 15 GBP in pence, collected from the customer
    app_fee: 10, # 10 pence, to be paid out to you
    currency: 'GBP',
    interval_unit: 'monthly',
    day_of_month: '5',
    links: {
      mandate: 'MD0000XH9A3T4C'
              # Mandate ID from the last section
    },
    metadata: {
      subscription_number: 'ABC1234'
    }
  },
  headers: {
    'Idempotency-Key' => 'random_subscription_specific_string'
  }
)

# Keep hold of this subscription ID - we'll use it in a minute
# It should look a bit like "SB00003GKMHFFY"
puts "ID: #{subscription.id}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Subscription;
import com.gocardless.services.SubscriptionService.SubscriptionCreateRequest.IntervalUnit;

public class CreateSubscription {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        Subscription subscription = client.subscriptions().create()
            .withAmount(1500) // 15 GBP in Pence, collected from the end customer.
            .withAppFee(10) // 10 pence, to be paid out to you.
            .withCurrency("GBP")
            .withIntervalUnit(IntervalUnit.MONTHLY)
            .withDayOfMonth(5)
            .withLinksMandate("MD0000YTKZKY4J")
                             // Mandate ID from the last section
            .withMetadata("subscription_number", "ABC123")
            .withIdempotencyKey("random_subscription_specific_string")
            .execute();

        // Keep hold of this subscription ID - we'll use it in a minute.
        // It should look a bit like "SB00003GKMHFFY"
        System.out.printf("ID: %s%n", subscription.getId());
    }
}

const subscription = await client.subscriptions.create(
  {
    amount: 1500,
    app_fee: 10,
    currency: "GBP",
    name: "Monthly subscription",
    interval: 1,
    day_of_month: 5,
    interval_unit: "monthly",
    links: {
      mandate: "MD0123"
    }
  },
  "unique_subscription_specific_string"
);

console.log(subscription.id);

var createResponse = await client.Subscriptions.CreateAsync(new SubscriptionCreateRequest
{
    Amount = 1500,
    AppFee = 10,
    Currency = "GBP",
    Name = "Monthly subscription",
    Interval = 1,
    DayOfMonth = 5,
    IntervalUnit = SubscriptionCreateRequest.SubscriptionIntervalUnit.Monthly,
    Links = new GoCardless.Services.SubscriptionCreateRequest.SubscriptionLinks
    {
        Mandate = "MD0123"
    },
    IdempotencyKey = "unique_subscription_specific_string"
});

var subscription = createResponse.Subscription;

Console.WriteLine(subscription.Id);

You’ll need to set the currency depending on the customer’s mandate’s scheme.

Each month, on the 5th of the month, the subscription will generate a new payment for £15 to be collected from the end customer.

We will debit £15.00 from the end customer’s bank account. From that, before paying it out to your user, GoCardless would deduct its fees, and any app_fee you’ve specified which would be deducted and passed on to you.

Taken from end customer's bank account £15.00
GoCardless fee £0.20
Your app_fee £0.10
Paid out to your user £14.70

With the subscription ID which is returned when we create the subscription, we can grab it from the API.

If you want to change the amount that a customer is being debited, you’ll need to update the subscription. Let’s update the amount by £10:

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

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

$subscription = $client->subscriptions()->get("SB00003GKMHFFY");
                                        // Subscription ID from above.

print("Previous Amount: " . $subscription->amount . "<br />");
print("Updating...<br />");

$newAmount = $subscription->amount + 1000;

$subscription = $client->subscriptions()->update($subscription->id, [
  "params" => ["amount" => $newAmount]
]);

print("Updated amount: " . $subscription->amount . "<br />");

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

subscription = client.subscriptions.get("SB00003GKMHFFY")
                                   # Subscription ID from above.

print("Previous amount: {}".format(subscription.amount))
print("Updating...")

newAmount = subscription.amount + 1000

subscription = client.subscriptions.update(subscription.id, params={
  "amount": newAmount
})

print("Updated amount: {}".format(subscription.amount))

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
  environment: :sandbox
)

subscription = client.subscriptions.get('SB00003GKMHFFY')
                                   # Subscription ID from above.

puts "Previous amount: #{subscription.amount}"
puts 'Updating...'

newAmount = subscription.amount + 1000

subscription = client.subscriptions.update(
  subscription.id,
  params: {
    amount: newAmount
  }
)

puts "Updated amount: #{subscription.amount}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Subscription;

public class UpdateSubscription {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        Subscription subscription = client.subscriptions().get("SB00003GKMHFFY").execute();


        System.out.printf("Previous amount: %s%n", subscription.getAmount());
        System.out.println("Updating...");

        int newAmount = subscription.getAmount() + 1000;

        subscription = client.subscriptions().update(subscription.getId())
        .withAmount(newAmount)
        .execute();

        System.out.printf("Updated amount: %s%n", subscription.getAmount());
    }
}

// Subscription ID from above
const subscriptionId = "SB00003GKMHFFY";

const subscription = await client.subscriptions.find(subscriptionId);

console.log(`Previous amount: ${subscription.amount}`);
console.log("Updating...");

const newAmount = subscription.amount + 1000;

const subscriptionRequest = {
  amount: newAmount
};

subscription = await client.subscriptions.update(
  subscriptionId,
  subscriptionRequest
);

console.log(`Previous amount: ${subscription.amount}`);

// Subscription ID from above
const string subscriptionId = "SB00003GKMHFFY";

var subscriptionResponse = await client.Subscriptions.GetAsync(subscriptionId);
var subscription = subscriptionResponse.Subscription;


Console.WriteLine($"Previous amount: {subscription.Amount}");
Console.WriteLine("Updating...");

var newAmount = subscription.Amount + 1000

var subscriptionRequest = new GoCardless.Services.SubscriptionUpdateRequest()
{
    Amount = newAmount
};

var updateResponse = await gocardless.Subscriptions.UpdateAsync(subscriptionId, subscriptionRequest);

subscription = updateResponse.Subscription;
Console.WriteLine($"Updated amount: {subscription.Amount}");

You may also wish to consider updating the app_fee if this is calculated as a percentage of the total amount.

If you want to stop charging the customer, you’ll need to then cancel the subscription. Let’s try doing that via the API so no further payments are taken:

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

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

$subscription = $client->subscriptions()->get("SB00003GKMHFFY");
                                        // Subscription ID from above.

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

$subscription = $client->subscriptions()->cancel("SB00003GKMHFFY");

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

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

subscription = client.subscriptions.get("SB00003GKMHFFY")
                                   # Subscription ID from above.

print("Status: {}".format(subscription.status))
print("Cancelling...")

subscription = client.subscriptions.cancel("SB00003GKMHFFY")

print("Status: {}".format(subscription.status))

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
	environment: :sandbox
)

subscription = client.subscriptions.get('SB00003GKMHFFY')
                                   # Subscription ID from above.

puts "Status: #{subscription.status}"
puts 'Cancelling...'

subscription = client.subscriptions.cancel('SB00003GKMHFFY')
puts "Status: #{subscription.status}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Subscription;

public class CancelSubscription {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        Subscription subscription = client.subscriptions().get("SB00003GKMHFFY").execute();

        System.out.printf("Amount: %s%n", subscription.getStatus());
        System.out.println("Cancelling...");

        subscription = client.subscriptions().cancel("SB00003GKMHFFY").execute();

        System.out.printf("Status: %s%n", subscription.getStatus());
    }
}

// Subscription ID from above
const subscriptionId = "SB00003GKMHFFY";

let subscription = await client.subscriptions.find(subscriptionId);

console.log(`Amount: ${subscription.amount}`);
console.log("Cancelling...");

subscription = await client.subscriptions.cancel(subscriptionId);
console.log(`Status: ${subscription.status}`);

// Subscription ID from above
const string subscriptionId = "SB00003GKMHFFY";

var subscriptionResponse = await client.Subscriptions.GetAsync(subscriptionId);
var subscription = subscriptionResponse.Subscription;

Console.WriteLine($"Amount: {subscription.Amount}");
Console.WriteLine("Cancelling...");

var cancelResponse = await client.Subscriptions.CancelAsync(subscriptionId);
subscription = cancelResponse.Subscription;
Console.WriteLine($"Status: {subscription.Status}");

Whenever a subscription creates a payment, you’ll receive a webhook with resource_type “subscriptions” and action “payment_created”.

POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 68cfef92b143649f4ce9b9e4b3d182b879be77625bcd0b3ff1f37849d01f76e6
{
  "events": [
    {
      "id": "EV123",
      "created_at": "2014-08-04T12:00:00.000Z",
      "action": "payment_created",
      "resource_type": "subscriptions",
      "links": {
        "subscription": "SB123",
        "payment": "PM123",
        "organisation": "OR123"
      }
    }
  ]
}

It’s likely that you’ll want to record this newly-created payment in your database to provide your user with visibility over payments being collected, and so you can track its status over time, taking action if it fails later.

Using instalment schedules

Often, a subscription doesn’t quite fit the bill for what you’re trying to achieve. Enter the instalment schedule. An instalment schedule is a method of collecting a finite set of regular, recurring payments from customers. An example of where you might use an instalment schedule would be if you had a particularly large invoice that might be easier to collect were it split into a set of regular, smaller instalments.

So, let’s go ahead and create an instalment schedule.

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->instalment_schedules()->create([
    "params" => [
        "name" => "ACME Invoice 103",
        "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);

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment="sandbox"
)

instalment_schedule = client.instalment_schedules.create(
    params={
        "name": "ACME Invoice 103",
        "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: {}".format(instalment_schedule.id))

require "gocardless_pro"

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
  environment: :sandbox,
)

instalment_schedule = client.instalment_schedules.create(
  params: {
    name: "ACME Invoice 103",
    amount: 10_000, # 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: [
        3_400,
        3_400,
        3_200,
      ],
    },
    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"
puts "ID: #{instalment_schedule.id}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.InstalmentSchedule;
import com.gocardless.services.InstalmentScheduleService.InstalmentScheduleCreateWithScheduleRequest.Instalments.IntervalUnit;

import java.util.Arrays;
import java.util.List;

import static com.gocardless.services.InstalmentScheduleService.InstalmentScheduleCreateWithScheduleRequest.*;

public class CreateInstalmentSchedule {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        List<Integer> amounts = Arrays.asList(3400, 3400, 3200);

        InstalmentSchedule instalmentSchedule = client.instalmentSchedules()
                        .createWithSchedule()
                        .withName("MacbookPro Cost")
                        // 100 GBP in Pence, collected from the customer.
                        .withTotalAmount(10000)
                        // Your 10 pence fee, applied to each instalment,
                        //to be paid out to you
                        .withAppFee(10)
                        .withCurrency(Currency.GBP)
                        .withInstalmentsIntervalUnit(IntervalUnit.WEEKLY)
                        .withInstalmentsInterval(2)
                        .withInstalmentsAmounts(amounts)
                        // Mandate ID from the last section
                        .withLinksMandate("MD0000YTKZKY4J")
                        .withMetadata("invoiceId", "006")
                        //idempotency:random_instalment_schedule_specific_string
                        .withIdempotencyKey("idempotency_string")
                        .execute();

        // Keep hold of this instalment schedule ID - we'll use it in a minute.
        // It should look a bit like "IS00006FWHUIA"
        System.out.printf("ID: %s%n", instalmentSchedule.getId());
    }
}

const amountsArray = [3400, 3400, 3200];

const instalmentSchedule = await client.instalmentSchedules.createWithSchedule(
  {
    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",
    name: "ACME Invoice 103",
    schedule: {
      start_date: "2019-08-20",
      interval_unit: "weekly",
      interval: "2",
      amounts: amountsArray
    },
    links: {
      mandate: "MD0000XH9A3T4C" // Mandate ID from the last section
    },
    metadata: {
      "Invoice ID": "001"
    }
  },
  "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"
console.log(instalmentSchedule.id);

int[] amountsArray = new int[]{ 3400, 3400, 3200 };

var createResponse = await client.InstalmentSchedules.CreateAsync(
    new InstalmentScheduleCreateRequest
    {
        Amount = 10000, // 100 GBP in pence, collected from the customer
        AppFee = 10, // Your 10 pence fee, applied to each instalment,
                     // to be paid out to you
        Currency = "GBP",
        Name = "ACME Invoice 103",
        Schedule = new GoCardless
            .Services
            .InstalmentScheduleCreateRequest
            .InstalmentSchedule
            {
                ChargeDates = datesArray,
                Amounts = amountsArray
            },
        Links = new GoCardless
            .Services
            .InstalmentScheduleCreateRequest
            .InstalmentScheduleLinks
            {
                Mandate = "MD0000XH9A3T4C" // Mandate ID from the last section
            },
        Metadata = new Dictionary<string, string>
        {
            {"Invoice ID", "001"}
        },
        IdempotencyKey = "random_instalment_schedule_specific_string"
    }
);

var instalmentSchedule = createResponse.InstalmentSchedule;

// Keep hold of this instalment schedule ID - we'll use it in a minute
// It should look a bit like "IS00006FWHUIA"
Console.WriteLine(instalmentSchedule.Id);

You’ll need to set the currency depending on the customer’s mandate’s scheme.

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. From each of those payments, before paying it out to your user, GoCardless would deduct its fees, and any app_fee you’ve specified which would be deducted and passed on to you.

Charged on 2019-08-20 2019-09-03 2019-09-17
Taken from end customer's bank account £34.00 £34.00 £32.00
GoCardless fee £0.20 £0.20 £0.20
Your app_fee £0.10 £0.10 £0.10
Paid out to your user £33.70 £33.70 £31.70

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->instalment_schedules()->create([
    "params" => [
        "name" => "ACME Invoice 103",
        "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);

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment="sandbox"
)

instalment_schedule = client.instalment_schedules.create(
    params={
        "name": "ACME Invoice 103",
        "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: {}".format(instalment_schedule.id))

require "gocardless_pro"

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
  environment: :sandbox,
)

instalment_schedule = client.instalment_schedules.create(
  params: {
    name: "ACME Invoice 103",
    amount: 10_000, # 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: 3_400,
      },
      {
        charge_date: "2019-09-03",
        amount: 3_400,
      },
      {
        charge_date: "2019-09-17",
        amount: 3_200,
      },
    ],
    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"
puts "ID: #{instalment_schedule.id}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.InstalmentSchedule;

import java.util.Arrays;

import static com.gocardless.services.InstalmentScheduleService.InstalmentScheduleCreateWithDatesRequest.Currency;
import static com.gocardless.services.InstalmentScheduleService.InstalmentScheduleCreateWithDatesRequest.Instalments;

public class CreateInstalmentSchedule {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

         Instalments firstInstalment = new Instalments()
                    .withAmount(3400)
                    .withChargeDate("2021-09-20")
                    .withDescription("First Installment for Macbook Pro");

        Instalments secondInstalment = new Instalments()
                    .withAmount(3400)
                    .withChargeDate("2021-10-03")
                    .withDescription("Second Installment for Macbook Pro");

        Instalments thirdInstalment =  new Instalments()
                    .withAmount(3200)
                    .withChargeDate("2021-10-17")
                    .withDescription("Third Installment for Macbook Pro");

         InstalmentSchedule instalmentSchedule = client.instalmentSchedules()
                    .createWithDates()
                    .withInstalments(
                        Arrays.asList(
                        firstInstalment,
                        secondInstalment,
                        thirdInstalment))
                    .withName("MacbookPro Cost")
                    // 100 GBP in Pence, collected from the customer.
                    .withTotalAmount(10000)
                    // Your 10 pence fee, applied to each instalment,
                    //to be paid out to you
                    .withAppFee(10)
                    .withCurrency(Currency.GBP)
                     // Mandate ID from the last section
                    .withLinksMandate("MD000G8PVYFZ9Z")
                    .withMetadata("invoiceId", "009")
                    //idempotency:random_instalment_schedule_specific_string
                    .withIdempotencyKey("idempotency_string")
                    .execute();

        // Keep hold of this instalment schedule ID - we'll use it in a minute.
        // It should look a bit like "IS00006FWHUIA"
        System.out.printf("ID: %s%n", instalmentSchedule.getId());
    }
}

const amountsArray = [3400, 3400, 3200];
const datesArray = ["2019-08-20", "2019-09-03", "2019-09-17"];

const instalmentSchedule = await client.instalmentSchedules.createWithDates(
  {
    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",
    name: "ACME Invoice 103",
    schedule: {
      charge_dates: datesArray,
      amounts: amountsArray
    },
    links: {
      mandate: "MD0000XH9A3T4C" // Mandate ID from the last section
    },
    metadata: {
      "Invoice ID": "001"
    }
  },
  "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"
console.log(instalmentSchedule.id);

int[] amountsArray = new int[]{ 3400, 3400, 3200 };
String[] datesArray = new String[]{ "2019-08-20", "2019-09-03", "2019-09-17" };

var createResponse = await client.InstalmentSchedules.CreateAsync(
    new InstalmentScheduleCreateRequest
    {
        Amount = 10000, // 100 GBP in pence, collected from the customer
        AppFee = 10, // Your 10 pence fee, applied to each instalment,
                     // to be paid out to you
        Currency = "GBP",
        Name = "ACME Invoice 103",
        Schedule = new GoCardless
            .Services
            .InstalmentScheduleCreateRequest
            .InstalmentSchedule
            {
                ChargeDates = datesArray,
                Amounts = amountsArray
            },
        Links = new GoCardless
            .Services
            .InstalmentScheduleCreateRequest
            .InstalmentScheduleLinks
            {
                Mandate = "MD0000XH9A3T4C" // Mandate ID from the last section
            },
        Metadata = new Dictionary<string, string>
        {
            {"Invoice ID", "001"}
        },
        IdempotencyKey = "random_instalment_schedule_specific_string"
    }
);

var instalmentSchedule = createResponse.InstalmentSchedule;

// Keep hold of this instalment schedule ID - we'll use it in a minute.
// It should look a bit like "IS00006FWHUIA"
Console.WriteLine(instalmentSchedule.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 make 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.

Instalment schedules cannot be edited. They can, however, be cancelled via the API:

<?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 />");

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

instalment_schedule = client.instalment_schedules.get("IS00006FWHUIA")
                                   # Instalment Schedule ID from above.

print("Status: {}".format(instalment_schedule.status))
print("Cancelling...")

instalment_schedule = client.instalment_schedules.cancel("IS00006FWHUIA")

print("Status: {}".format(instalment_schedule.status))

require "gocardless_pro"

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
  environment: :sandbox,
)

instalment_schedule = client.instalment_schedules.get("IS00006FWHUIA")
                                    # Instalment Schedule ID from above.

puts "Status: #{instalment_schedule.status}"
puts "Cancelling..."

instalment_schedule = client.instalment_schedules.cancel("IS00006FWHUIA")
puts "Status: #{instalment_schedule.status}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.InstalmentSchedule;

public class CancelInstalmentSchedule {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        InstalmentSchedule instalmentSchedule = client.instalmentSchedules()
            .get("IS00006FWHUIA") // InstalmentSchedule ID from above.
            .execute();

        System.out.printf("Status: %s%n", instalmentSchedule.getStatus());
        System.out.println("Cancelling...");

        instalmentSchedule = client.instalmentSchedules()
            .cancel("IS00006FWHUIA")
            .execute();

        System.out.printf("Status: %s%n", instalmentSchedule.getStatus());
    }
}

// InstalmentSchedule ID from above
const instalmentScheduleId = "IS00006FWHUIA";

let instalmentSchedule = await client.instalmentSchedules.find(
  instalmentScheduleId
);

console.log(`Status: ${instalmentSchedule.status}`);
console.log("Cancelling...");

instalmentSchedule = await client.instalmentSchedules.cancel(
  instalmentScheduleId
);
console.log(`Status: ${instalmentSchedule.status}`);

// InstalmentSchedule ID from above
const string instalmentScheduleId = "IS00006FWHUIA";

var instalmentScheduleResponse = await client.InstalmentSchedules.GetAsync(instalmentScheduleId);
var instalmentSchedule = instalmentScheduleResponse.InstalmentSchedule;

Console.WriteLine($"Status: {instalmentSchedule.Status}");
Console.WriteLine("Cancelling...");

var cancelResponse = await client.InstalmentSchedules.CancelAsync(instalmentScheduleId);
instalmentSchedule = cancelResponse.InstalmentSchedule;
Console.WriteLine($"Status: {instalmentSchedule.Status}");

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 the 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 invoice 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 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.

NB: If a single payment in an instalment schedule has failed, and the instalment schedule is cancelled, the failed payment will be unaffected by the cancellation of the instalment schedule, and can therefore still be retried. Please refer to the next section for advice on how to handle failed payments.

Handling payment failures

Payments collected via Direct Debit are not confirmed immediately - when a payment is created, it must be submitted to the banking system, and GoCardless won’t know for a few days whether the payment has been successful. For more details on how long payments take to process, see our guides for

Payment failures are rare - less than 1% of payments fail - but building a great experience for your users means handling these failures. A payment may fail, for example, if the end customer has insufficient funds in their account.

You’ll find out about a payment failure when you receive a webhook that includes an event with the resource_type of “payments” and action of “failed”:

POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 86f8bb84a4de63cff4af48f22b64b20970b415b066e3d21459ea515052860514
{
  "events": [
    {
      "id": "EV456",
      "created_at": "2014-08-03T12:00:00.000Z",
      "action": "failed",
      "resource_type": "payments",
      "links": {
        "payment": "PM456",
        "organisation": "OR123"
      },
      "details": {
        "origin": "bank",
        "cause": "mandate_cancelled",
        "description": "Customer cancelled the mandate at their bank branch.",
        "scheme": "bacs",
        "reason_code": "ARUDD-1"
      }
    },
    {
      "id": "EV123",
      "created_at": "2014-08-03T12:00:00.000Z",
      "action": "confirmed",
      "resource_type": "payments",
      "links": {
        "payment": "PM123",
        "organisation": "OR123"
      },
      "details": {
        "origin": "gocardless",
        "cause": "payment_confirmed",
        "description": "Payment was confirmed as collected"
      }
    }
  ]
}

You’ll need to think about how to handle failures in your product - the right thing to do will depend on your product and your users’ preferences. You might consider:

  • Updating your UI to show that a payment failed, and offering the option to try again
  • Offering an option which allows your users to have failed payments automatically retried
  • Sending the end customer an email telling them what happened and what they need to do next

The details object inside the event includes more details on why the payment failed. The cause field is especially useful, providing more context on why the payment was unsuccessful. The most common causes of payment failure you’ll want to handle include:

refer_to_payer
For UK payments using the Bacs scheme, this means the end customer had insufficient funds. For Eurozone payments using the SEPA scheme, the customer must contact their bank to find our what went wrong.
insufficient_funds
Only used for SEPA, this means that the customer did not have sufficient funds.
mandate_cancelled
The mandate was cancelled between when the payment was submitted to the banks and when it was due to be debited from the end customer's account.

You can find a full list of the cause values for payment-related webhook events, including failures in our reference documentation.

You’ll need to think about how to handle failures in your product - the right thing to do will depend on your product and your users’ preferences. You might consider:

  • Updating your UI to show that a payment failed, and offering the option to try again
  • Including a setting which allows your users to have failed payments automatically retried
  • Sending the customer an email telling them what happened and what they need to do next

You can read more in our user experience guide about collecting payments and clearly displaying error states.

If a payment has failed due to insufficient funds, you may wish to retry it. You don’t need to create a new payment to do this, but can rather retry the existing one through a simple API call:

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

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

$payment = $client->payments()->get("PM000260X9VKF4");
                              // Payment ID from above

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

$payment = $client->payments()->retry("PM000260X9VKF4");
print("Status: " . $payment->status);

import os
import gocardless_pro

client = gocardless_pro.Client(
    access_token=current_user.gocardless_access_token,
    environment='sandbox'
)

payment = client.payments.get("PM000260X9VKF4")
                         # Payment ID from above.

print("Amount: {}".format(payment.amount))
print("Retrying...")

payment = client.payments.retry("PM000260X9VKF4")
print("Status: {}".format(payment.status))

require 'gocardless_pro'

client = GoCardlessPro::Client.new(
  access_token: current_user.gocardless_access_token,
	environment: :sandbox
)

payment = client.payments.get('PM000269VJAR6M')
                         # Payment ID from above.

puts "Status: #{payment.status}"
puts 'Retrying...'

payment = client.payments.retry('PM000269VJAR6M')
puts "Status: #{payment.status}"

package com.gcintegration;

import com.gocardless.GoCardlessClient;
import com.gocardless.resources.Payment;

public class RetryPayment {
    public static void main(String[] args) {
        GoCardlessClient client = GoCardlessClient
            .newBuilder(CurrentUser.gocardlessAccessToken)
            .withEnvironment(GoCardlessClient.Environment.SANDBOX)
            .build();

        Payment payment = client.payments().get("PM000260X9VKF4").execute();
                                              // Payment ID from above.
        System.out.printf("Amount: %s%n", payment.getAmount());
        System.out.println("Retrying...");

        payment = client.payments().retry("PM000260X9VKF4").execute();
        System.out.printf("Status: %s%n", payment.getStatus());
    }
}

// Payment ID from above
const paymentId = "PM000260X9VKF4";

let payment = await client.payments.find(paymentId);

console.log(`Amount: ${payment.amount}`);
console.log("Retrying...");

payment = await client.payments.retry(paymentId);
console.log(`Status: ${payment.status}`);

// Payment ID from above
const string paymentId = "PM000260X9VKF4";

var paymentResponse = await client.Payments.GetAsync(paymentId);
var payment = paymentResponse.Payment;

Console.WriteLine($"Amount: {payment.Amount}");
Console.WriteLine("Retrying...");

var retryResponse = await client.Payments.RetryAsync(paymentId);
var payment = retryResponse.Payment;
Console.WriteLine($"Status: {payment.Status}");
Handling customer notifications →