Now we’ve set up our first customer with a mandate, we’re ready to start taking payments. There are two ways to set up your payments - which one is right for you will depend on what you’re using GoCardless for:
- One-off payments: Trigger a payment against a mandate at any time with the API. Great if you want to charge your customers ad-hoc amounts.
- Subscriptions: Set up an automatic recurring payment. Great if you 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 even use these together - once you have a mandate, you have complete flexibility to charge your customers whenever you want.
Let’s try both - we’d recommend spending a few minutes on each to get to understand the full power of the API.
One-off payments
To create a payment for a customer, the following fields are required:
amount - Amount in pence (GBP), cents (AUD/EUR), öre (SEK), or øre (DKK).
currency - ISO 4217 currency code. Currently GBP, EUR, SEK and AUD are supported.
links[mandate] - ID of the customer’s mandate against which this payment should be collected.
You’ll need to use the currency appropriate for the mandate you set up. This depends on what Direct Debit scheme you are using - the scheme of your mandate set up through the redirect flow will depend on your location (though you can set it manually by specifying a scheme):
| Location | currency |
|---|---|
| UK | GBP |
| Sweden | SEK |
| Australia | AUD |
| Everywhere else | EUR |
In addition to these fields, the following optional parameters can be sent:
app_fee - The amount to be deducted from the payment as the OAuth app’s fee, in pence/cents/öre/øre. (only applicable to partners)
charge_date - A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. This must be on or after the mandate’s next_possible_charge_date, and will be rolled-forwards by GoCardless if it is not a working day.
description - A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).
metadata - Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
reference - An optional payment reference that will appear on your customer’s bank statement. For Bacs payments this can be up to 10 characters, for SEPA payments the limit is 140 characters, for Betalingsservice payments the limit is 30 characters and for Autogiro payments the limit is 11 characters. Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you’re on the GoCardless Plus or Pro packages.
For example code samples, please refer to the guide found here.
Idempotency keys
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.
Subscriptions
Subscriptions allow payments to be created according to a schedule.
To create a subscription for a customer, the following fields are required:
amount - Amount in pence (GBP), cents (AUD/EUR), öre (SEK), or øre (DKK).
currency - ISO 4217 currency code. Currently GBP, EUR, SEK, AUD and DKK are supported.
interval_unit - The unit of time between customer charge dates. One of weekly, monthly or yearly.
links[mandate] - ID of the customer’s mandate which the subscription will create payments against.
In addition to these fields, the following optional parameters can be sent:
name - Optional name for the subscription, which will also set the description of each payment.
interval - the number of interval_units between each charge date. This must result in at least one charge per year, and will default to 1 if not provided.
count - the total number of payments to be taken by the subscription. If no count is specified, the subscription will continue indefinitely.
day_of_month - the day of the month (1-28) you’d like your customer to be charged on. You can also use -1 to indicate the last day of the month.
month - the name of the month in which to charge a customer.
start_date - the date on which the first payment should be charged. This date must be within a year of the subscription being created, and on or after the mandate’s next_possible_charge_date. If this parameter isn’t included, the first payment will be charged as soon as possible.
payment_reference - This parameter is restricted to Pro accounts only. An optional payment reference that will be set for all payments and will appear on your customer’s bank statement.
For example code samples, please refer to the guide found here.
For further details relating to recurrence rules and implementation tips, please refer to our more in-depth article here.