Overview
This is the documentation for the GoCardless API.
If you’re just exploring or want to start building an integration, check out our getting started guide for a step-by-step introduction with PHP, .NET, Java, Ruby and Python code samples
For testing purposes we recommend you sign up for a sandbox account.
Supported Direct Debit Schemes
The GoCardless API currently supports the following Direct Debit schemes:
Scheme | Countries |
---|---|
Bacs | UK & Channel Islands (inc. Jersey & Guernsey) + Isle of Man + Gibraltar (The customer needs to select UK as the country) |
SEPA Core* | Åland Islands Austria Belgium Cyprus Estonia Finland France French Guiana Germany Greece Guadeloupe Ireland Italy Latvia Lithuania Luxembourg Malta Martinique Mayotte Monaco Netherlands Portugal Réunion San Marino Slovakia Slovenia Spain Saint Barthélemy Saint Martin Saint Pierre and Miquelon |
ACH | United States |
Autogiro | Sweden |
Betalingsservice | Denmark |
BECS | Australia |
BECS NZ | New Zealand |
PAD | Canada |
PayTo** | Australia |
Faster Payments*** | UK & Channel Islands (inc. Jersey & Guernsey) + Isle of Man + Gibraltar (The customer needs to select UK as the country) |
Note: There are practical issues with SEPA Direct Debit in some countries that mean we would not recommend using it to collect payments from end customers in those markets. Local implementation can cause problems in the Baltic states in particular - please contact us for more information.
* Collection from all non-Eurozone SEPA countries is also supported through the API, but since only a small percentage of bank accounts in these countries are reachable they have not been listed above.
** PayTo although not technically a Direct Debit scheme can be used as an alternative to BECS.
*** Faster Payments is not a Direct Debit scheme, but an alternative to BACS that can be used for instant and variable recurring payments.
Getting Started
There are three key parts to an integration with the API - you can do one, two or all three of them:
- Setting up mandates with your customers’ bank accounts
- Collecting payments against your mandates
- Staying up-to-date with webhooks
To get started with the API, check out our “getting started” guide, with copy and paste code samples in PHP, Ruby and Python guiding you through your integration from start to finish.
Restrictions
Whilst the entire GoCardless API is accessible in the sandbox environment, the following restrictions exist in live.
Payment page restrictions
Unless your payment pages have been approved as scheme rules compliant by our sponsor bank you must use the Billing Requests API to create customers, bank accounts and mandates.
The following endpoints are therefore restricted:
- Billing Requests: Create_customer_details, Collect_bank_account
- Customers: Create
- Customer bank accounts: Create
- Mandate: Create, Reinstate
- Javascript flow: All endpoints
Please get in touch to discuss having your payment pages approved.
Creditor management restrictions
Unless your account has previously been approved as a whitelabel partner you may only collect payments on behalf of a single creditor. The following endpoints are therefore restricted:
- Creditors: Create
Anatomy
The following state diagrams explain the flows of mandate setup to setup customers on a Direct Debit and payment creation, to collect payment against said mandate. There’s also a short section on how timings work.
Mandate setup
Payment creation
How timings work
Direct debit payments don’t process instantly, and work differently to card payments.
For the UK:
- If a Direct Debit mandate is already in place, payment is collected 2 working days after submission, can be considered 95% confirmed 3 working days after submission, and 100% confirmed after 4 working days.
- If a Direct Debit mandate needs to be created, payment is collected 4 working days after submission, can be considered 95% confirmed 5 working days after submission, and 100% confirmed after 6 working days.
There’s also a requirement to notify your customers 3 working days before payment leaves their account. See the notifications section for more detail.
For more information on UK timings, see our detailed guide.
For ACH:
- New mandates take up to 2 interbank business days before payments can be submitted under them.
- For all payment collections, you must submit the collection to the banks 2 interbank business days before the payment due date.
You will need to notify your customers at least 2 working days in advance of the payment being collected.
For more information on ACH timings, see our detailed guide.
For Autogiro:
- New mandates take up to 6 interbank business days before payments can be submitted under them.
- For all payment collections, you must submit the collection to the banks 2 interbank business days before the payment due date.
You will need to notify your customers at least 8 working days in advance of the payment being collected.
For more information on Autogiro timings, see our detailed guide.
For BECS:
- For all payment collections, you must submit the collection to the banks 1 interbank business day before the payment due date.
For more information on BECS timings, see our detailed guide.
For BECS NZ:
- For all payment collections, you must submit the collection to the banks 2 interbank business days before the payment due date.
For more information on BECS NZ timings, see our detailed guide.
For Betalingsservice:
- New mandates must be created at least one working day before payments can be created.
- For all payment collections, you must submit the collection 8 working days before the end of the month preceding the month in which you wish to take the payment
For more information on Betalingsservice timings, see our detailed guide.
For PAD:
- For all payment collections, you must submit the collection to the banks 3 interbank business days before the payment due date.
For more information on PAD timings, see our detailed guide.
For PayTo:
- There is no advance notice period and payments can be taken almost instantaneously.
For Faster Payments:
- There is no advance notice period and payments can be taken almost instantaneously.
For SEPA Core:
- For all payment collections, you must submit the collection to the banks 3 interbank business days before the payment due date.
You will need to notify your customers 3 working days in advance of the payment being collected.
For more information on SEPA timings, see our detailed guide.
In all cases, you can still test these as if they were instant - for more detail, see the section on testing your integration.
Backwards Compatibility
The following changes are considered backwards compatible:
- Adding new API endpoints
- Adding new properties to the responses from existing API endpoints
- Reordering properties returned from existing API endpoints
- Adding optional request parameters to existing API endpoints
- Altering the format or length of IDs
- These strings will never exceed 255 characters, but you should be able to handle anything up to that length
- Altering the
message
attributes returned by validation failures / other errors - The number of and duration between retries for failed webhooks
- The behaviour of Scenario Simulators
- Sending webhooks for new event types
Changelog
- 2nd December 2024
- Added ACH and PAD-specific API fields:
- Added
mandate_request[consent_type]
parameter to Billing Request creation. - Added
constraints[payment_method]
parameter to Billing Request creation. - Added
subscription_request
parameter to Billing Request creation. - Added
instalment_schedule_request
parameter to Billing Request creation.
- Added
- 8th January 2024
- Added API fields for Faster ACH:
- 18th July 2023
- Updated our public certificate policy.
- 21 June 2023
- Added the
resource_metadata
property to Events. - 16 March 2023
- Added
show_success_redirect_button
parameter to Billing Request Flow creation. - 1st March 2023
- Changed the Payout Items API to only return Payout Items created in the previous 6 months.
- 22nd February 2023
- Made the Billing Requests API and the Blocks API respond in English if the
Accept-Language
header isn’t set, like other API endpoints. These two APIs used to infer the language from the IP address of the client, which wasn’t the intended behaviour. - 8th February 2023
- Added
billing_request[purpose_code]
parameter to Billing Request creation. - 13th January 2023
- Added the
verified_at
timestamp field to the mandates API. - 23rd December 2022
- Updated our public certificate policy.
- 20th December 2022
- Added
authorisation_source
parameter to the Mandate creation API andmandate_request[authourisation_source]
parameter to the BillingRequest creation API. This field is required for offline mandates. - 13th December 2022
- Added
creditor_type
parameter to the Creditors API. This field represents the type of business of the creditor. It will now be required when creating a creditor and it will be returned when fetching creditors. - 9th December 2022
- Added
language
parameter to Billing Request Flow creation. - 11th November 2022
- Added
mandate_request[description]
andmandate_request[constraints]
parameter to Billing Request creation. Constraints restricts the kind of payment that can be taken against a mandate. - 1st November 2022
-
Payout Items are no longer ordered by
type
. The order of Payout Items for a given Payout is still consistent between requests. - 5th August 2022
- Added
payer_requested_dual_signature
parameter to Billing Request action confirm payer details. - 21st July 2022
- Added
prefilled_customer
andprefilled_bank_account
parameters to Billing Request creation. - 14th July 2022
- Added
mandate_request[reference]
parameter to Billing Request creation. - 10th May 2022
- Autogiro scheme is now available in Billing Request flow. Documentaion can be found here
- 4th May 2022
- Event creation is now an asynchronous process. This means it can take some time between an action occurring and its corresponding event being made available in API responses.
- 26th January 2022
- Added support for filtering events by instalment schedule in the events List API.
- 31st December 2021
- Added support for Sepa Credit Transfer and Sepa Instant Credit Transfer, the Instant Bank Pay schemes inside Billing Request.
- 18th November 2021
- Added block endpoints. These endpoints allow to create a block based on payers bank_account, email and email_domain, view the blocked items.
- 5th August 2021
- Fixed reason codes sent for BECS so that they are consistent with the documentation.
Eg.
direct_debit_not_enabled
events will be sent with Reason code2
instead ofRETURNS-2
, as per documentation. - 30th March 2021
- Added Scenario Simulators endpoint. These allow manual testing of certain flows in the Sandbox environment
- 26th March 2021
- Added a new resource called Billing Requests. This is our new API dedicated to building custom payment pages. It encapsulates the creation of customer, bank account and mandate under this single resource.
- 28th January 2021
- Added webhook endpoints. These allow you to view
and retry webhooks that we have sent to you. As part of this we began
including
webhook_id
inside themeta
key in the webhooks we send. - 30th October 2020
- Added a new resource called payer_authorisatons. This is our new API dedicated to building custom payment pages. It encapsulates the creation of customer, bank account and mandate under this single resource.
- 12th August 2020
- Added a new event called
payer_authorisation_completed
for an upcoming resource type calledpayer_authorisation
. - 14th July 2020
- Added support for applying tax to transaction and surcharge fees.
- Added
taxes
to payout_items. - Added
tax_currency
to payout. - Added tax_rates endpoint.
- Added a payout
tax_exchange_rates_confirmed
webhook to know when the exchange rate has been finalised for all fees in the payout.
- Added
- 9th July 2020
- Allow changing
retry_if_possible
when updating a subscription. - 27th May 2020
- Added a
not_retried_reason
field to the event details for failed payment event. - 7th May 2020
- Updated the type of
bank_account_type
fromstring
toenum
.bank_account_type
is referenced increditor_bank_accounts
,customer_bank_acount_tokens
,customer_bank_accounts
andmandate_pdfs
endpoint. - 20th April 2020
- Added
prefilled_bank_account
attribute in the redirect flow create endpoint to allow the integrator to prefill theaccount_type
field. - 20th April 2020
- Added metadata to payouts, and added new update payouts route so that integrators can use it.
- 6th April 2020
- We are updating the wording of the documentation for
prefilled_customer[region]
attribute in redirect flow create endpoint. - 26th March 2020
- We have added the ability to capture metadata attribute as part of redirect flow create endpoint.
- 17th March 2020
- We’ve added the ability to pause and resume subscriptions.
- 19th February 2020
- We’ve optimised our webhook batching to become slightly more effective. This means each webhook will have on–average–slightly more events per request than we have sent previously.
- 18th Februrary 2020
- Added new events for creditors:
updated
new_payout_currency_added
- 6th February 2020
- Added support for Success+ intelligent retries
- Added a new
retry_if_possible
field to the Payments, Subscriptions & Instalment Schedules endpoints - Added a
will_attempt_retry
field to the event details for failed payment event.
- Added a new
- 6th February 2020
- Added new disconnected webhook for partners
- 29th January 2020
- Added 3 fields to the Creditors endpoint:
mandate_imports_enabled
,merchant_responsible_for_notifications
andcustom_payment_pages_enabled
. - 28th January 2020
- Added support for instalment schedules.
- Added documentation for new Instalment Schedules endpoint.
- 27th January 2020
- Marked the
phone_number
field in Customers as optional. - 19th November 2019
- Added support for international payments.
- Added
fx
to Payments, Payouts & Refunds - Added support for surcharge fees.
- Added new
surcharge_fee
type for Payout Items. - Added payment webhooks for surcharge fee events (
surcharge_fee_credited
andsurcharge_fee_debited
)
- Added
- 23rd July 2019
- Added new customer removal API.
- 21st February 2019
- Added new
payment_autoretried
event cause for thepayment_resubmission_requested
action. - 19th December 2018
- Added the ability to handle
subscription_created
emails. - 5th December 2018
- Added support for PAD, the Direct Debit scheme in Canada, in beta.
- 16th October 2018
- Added new event for refund
failed
(refund_failed
). - 11th September 2018
- Added support for BECS NZ, the Direct Debit scheme in New Zealand, in beta.
- 30th August 2018
- Add
links[default_aud_payout_account]
as an updatable field to the creditors API - 22nd August 2018
- Removed
can_create_refunds
as an updatable field from the creditors API - 17th August 2018
- Added the ability to handle
payment_created
andmandate_created
emails. - 12th July 2018
- Added customer address fields to the mandate PDFs API.
- 27th June 2018
- Added support for Betalingsservice, the Direct Debit scheme in Denmark, in beta.
- 22nd May 2018
- Added
app_fee
field to responses from the subscriptions API. - 17th May 2018
- Took the payout items API out of beta.
- Improved the documentation of the mandate PDFs API, clarifying what languages are supported for each scheme and documenting that the default language is English.
- 15th May 2018
- Added the maximum payment and refund
reference
lengths for Becs. - 26th April 2018
- Added the mandate imports API, allowing partners to more easily migrate mandates to GoCardless.
- 20th April 2018
- Added information on our public certificate policy.
- 11th April 2018
- Added support for BECS, the Direct Debit scheme in Australia, in beta.
- 6th March 2018
- Added contact email address to responses from the OAuth introspect API and access token API.
- 13th February 2018
- Added support for multiple redirect URIs per partner app.
- 26th January 2018
- Added the new OAuth introspect API, allowing partners to check if access tokens are valid and find out more about them
- Added the new OAuth revoke API, allowing partners to disconnect users from their app, invaliding their access token
- 15th January 2018
- Added additional characters to the list of allowed characters for SEPA mandate and payment references
- 1st December 2017
- Added read-only
can_create_refunds
field to responses from the creditors API. - 30th November 2017
- Renamed
exceeded_max_amendments
error on subscriptions tonumber_of_subscription_amendments_exceeded
when updating a subscription. - 16th November 2017
- Added filtering by
reference
to the payouts API. - 14th November 2017
- Added filtering by
status
to the subscriptions API. - 13th November 2017
- Added the new payout items API, allowing you to view, on a per-payout basis, the credit and debit items that make up that payout’s amount.
- 25th October 2017
- Allow changing
amount
when updating a subscription. - 23rd October 2017
- Added new event for subscription
amended
action. - 18th September 2017
- Added
confirmation_url
to the redirect flows API. - 19th June 2017
- Added the
Origin
header to webhooks, specifying the GoCardless environment that a webhook was sent from (https://api.gocardless.com
for live,https://api-sandbox.gocardless.com
for sandbox). - 19th May 2017
- Added
verification_status
to the creditors API. - 11th May 2017
- Deprecated
end_date
in the subscriptions API. - 17th March 2017
- Added new
mandate_expired
cause for the paymentcancelled
action(#payment-cancelled). - 13th March 2017
- Added
app_fee
to the subscriptions API. - 2nd March 2017
- Added
prefilled_customer
to the redirect flows API. - 20th February 2017
- Added
scheme_identifiers
to the creditors API. - 2nd February 2017
- Added new event for mandate
replaced
action. - 2nd August 2016
- Added
deducted_fees
to the payouts API. - 7th July 2016
- Added
payments_require_approval
to the mandates API. - 11th February 2016
- Added
arrival_date
to the payouts API. - 21st January 2016
- Restricted specifying payment references on Bacs payments to only those organisations using their own Service User Number.
- 6th January 2016
- Added filtering by
created_at
to the customer bank accounts API. - 20th October 2015
- Added filtering by
created_at
to the mandates API. - 16th October 2015
- Added filtering by
created_at
to the payouts API. - 30th September 2015
- Added support for app fees to the OAuth API, in beta.
- 29th September 2015
- Added support for Autogiro, the Direct Debit scheme in Sweden, in beta.
- 16th September 2015
- Added
request_pointer
field to validation errors, in the form of JSON pointer. See validation errors for more details. - 10th September 2015
- Added
reference
to the refund API. This sets a reference which will appear with the refund on the customer’s bank statement. - 17th August 2015
- Added
language
to the customer API. This sets the language of notification emails sent by GoCardless to the customer. Defaults to the native language of the customer’s country. - 2nd August 2015
- Added support for SEPA COR1, a faster version of SEPA Direct Debit
available in Spain, Germany and Austria. COR1 will be used
automatically if possible when creating new SEPA mandates, unless
you specify the
scheme
attribute explicitly. The returnedscheme
attribute will besepa_cor1
. - 29th July 2015
- Added
customer_bank_account
andcustomer
to the complete redirect flow endpoint returned properties. - 23rd July 2015
- Removed support for API version
2014-11-03
. - 22nd July 2015
- Added
bic
to the bank details lookups endpoint returned properties. - 6th July 2015
- Released API version
2015-07-06
. See blog post for more details and upgrade guide.- Removes
Helpers
endpoint from the API - Renames
start_at
andend_at
on subscriptions tostart_date
andend_date
- Enforces date format (not datetime) for payment
charge_date
- Removes
- 2nd July 2015
- Renamed the beta modulus checks endpoint to bank details lookups and took it out of beta.
- 30th June 2015
- Added mandate PDFs endpoint, which will replace the previous mandate helper endpoint and the ability to request a PDF from the “get a single mandate” endpoint in a future version.
- 26th June 2015
- Added top level modulus checks endpoint, which will replace the previous modulus check helper endpoint in a future version.
- 15th June 2015
- Updated MIME type negotiation to 406 if a bad
Accept
header is provided. - 9th June 2015
- Added new events for payment created, subscription created, and refund paid.
- 29th April 2015
- Released API version
2015-04-29
. See blog post for more details and upgrade guide.- Removes
Roles
andUsers
from the API - Replaces
Api Keys
withAccess Tokens
- Replaces
Publishable Api Keys
withPublishable Access Tokens
- Removes explicit sort_code field from bank account creation APIs in favour of local details
- Removes
Webhook-Key-Id
header from webhooks we send
- Removes
Client Libraries
We also provide client libraries to make your integration easier.
Currently we have the following libraries available:
- GoCardless Pro Ruby
- GoCardless Pro Python
- GoCardless Pro Java
- GoCardless Pro PHP
- GoCardless .NET
- GoCardless Node.js
- GoCardless Pro Go
- GoCardless Pro Android
- GoCardless Pro iOS
If there’s a another language you’d like a library for, please get in touch to let us know.
Making Requests
Base URLs
The base URLs for the GoCardless API are
- https://api.gocardless.com/
for live
- https://api-sandbox.gocardless.com/
for sandbox
The API is only available over HTTPS. Attempting to access the API over an
unsecured HTTP connection will return a tls_required
error.
Authentication
After creating an access token in the dashboard, you must provide it in an Authorization request header (using the bearer authentication scheme) when making API requests.
Authorization: Bearer TOP_SECRET_ACCESS_TOKEN
If you’re using our JavaScript Flow, you must use a publishable access token instead.
Versions
Every request must specify a GoCardless-Version
header, with a released
API version.
GoCardless-Version: 2015-07-06
Currently available versions:
2015-07-06
- Removed helper endpoint (replaced with new individual endpoints).
Historic versions which are no longer available:
2015-04-29
- Changed auth and removed sort_code.
2014-11-03
- Changed validations on charge_customer_at.
2014-10-03
- Enforced validation of keys passed to all endpoints.
2014-09-01
- First Pro API release.
MIME Types
All requests and responses are JSON-formatted and UTF-8 encoded.
An Accept
header is required for all requests, for example:
Accept: application/json
A Content-Type
and Content-Length
header must be given when sending data to the API
(using POST
and PUT
endpoints), for example:
Content-Type: application/json
Content-Length: 3495
For the Accept
and Content-Type
headers, you may
give either the standard JSON MIME type (application/json
), or the JSON-API
variant (application/vnd.api+json
).
You will receive an invalid_content_type
error if you attempt to make a POST
/PUT
request without one of these MIME types.
In the case of a missing Content-Length
header,
you will receive an Error 411 (Length Required)
error message. Although, the majority
of HTTP clients should send the header by default.
PUT, PATCH and DELETE
If your HTTP client or proxy doesn’t support PUT
or DELETE
, you
can instead make a POST
request with the header X-HTTP-Method-Override: PUT
or X-HTTP-Method-Override: DELETE
.
The HTTP PATCH
verb is not allowed by the API, and will result in a
method_not_allowed
error. Please use PUT
to alter an existing resource.
Rate Limiting
We apply a rate limit to all API requests, to prevent excessive numbers of simultaneous requests from an individual integrator degrading the API experience for others.
Currently, this limit stands at 1000 requests per minute. If you are making requests from
a partner integration (on behalf of a merchant), the rate limit is 1000 requests per
minute per merchant. The limit can always be found in the response header
ratelimit-limit
.
If your API call returns a 429
status code with a rate_limit_exceeded
error, you have
exceeded this limit. These requests can be safely retried. We supply information in the
ratelimit-remaining
and ratelimit-reset
headers, which indicate how many requests are
allowed in the current time window, and the time after which the rate limit will reset,
respectively.
For example, reading response headers like these, your integration is permitted to make a
further 163
requests until Thu, 03 May 2018 16:00:00 GMT
, after which the limit will
reset back to 1000
for the next time window:
ratelimit-limit: 1000
ratelimit-remaining: 163
ratelimit-reset: Thu, 03 May 2018 16:00:00 GMT
If you are planning to make a large number of requests to our API, our rate limit should be regarded as a performance target: if you can successfully hit 1000 requests/minute, your task will be completed in the shortest possible time.
Timeouts
Some timeouts affect HTTP requests and connections to the API.
- Request Timeout - we have a request timeout of 29 seconds. A single request cannot last more than this amount of time.
- Keepalive Timeout - we have a keepalive timeout (also known as an idle timeout) of 10 minutes on persistent HTTP connections. If a connection has been open with no request for that time period, the connection will be closed.
Idempotency Keys
Some requests are dangerous to make twice. In a situation like submitting payments, retrying a request that appeared to fail (for example due to a network timeout) could lead to a payment being taken twice. This is clearly undesirable.
When creating resources, our API supports idempotent creation. If you make a request
with an Idempotency-Key
header, we only allow that key to be used for a single
successful request. Any requests to create a resource with a key that has previously been
used will not succeed, and will respond with a 409
idempotent_creation_conflict
error, with the error including a links.conflicting_resource_id
attribute pointing
to the already-existing resource.
Our API libraries will automatically generate idempotency keys when you try to create a resource. However, you might want to generate and supply your own - for example, using an ID from your database to identify a record (for example a payment you’re going to collect) will protect against not only network errors, but also accidentally doing the same thing twice from your side.
Idempotency keys may be no longer than 128 characters.
Idempotency keys are intended to prevent conflicts over short periods of time, and will not be persisted indefinitely. We guarantee that we will honour idempotency keys for at least 30 days. After this point we reserve the right to respect the keys for any further length of time and this behaviour must not be relied upon. We strongly encourage generating idempotency keys using UUIDv4 but any non-repeating unique identifier is sufficient.
Optional properties
When making requests, optional properties should be completely omitted from the JSON when not being used. This is automatically handled in our API libraries and is only relevant if you create your own.
Dates and Times
All timestamps are formatted as ISO8601 with timezone information. For API calls
that allow for a timestamp to be specified, we use that exact timestamp. These
timestamps look something like 2014-02-27T15:05:06.123Z
.
For endpoints that require dates, we expect a date string of the format YYYY-MM-DD
,
where an example would look like 2014-02-27
.
Cursor Pagination
All list/index endpoints are ordered and paginated reverse chronologically by default.
Options
The following options are available on all cursor-paginated endpoints:
before
- ID of the object immediately following the array of objects to be returned.
after
- ID of the object immediately preceding the array of objects to be returned.
limit
- Upper bound for the number of objects to be returned. Defaults to 50. Maximum of 500. Minimum of 1.
Response
Paginated results are always returned in an array, and include the following meta data:
before
- The ID of the first resource that has been returned.
after
- The ID of the last resource that has been returned.
limit
- The upper bound placed on the number of objects returned. If there were not enough remaining objects in the list of data then fewer than this number will have been returned.
GET https://api.gocardless.com/resources?after=ID789 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"meta": {
"cursors": {
"after": "ID456",
"before": "ID123"
},
"limit": 50
},
"resources": [{
...
}]
}
Response Codes
You may encounter the following response codes. Any unsuccessful response codes will contain more information to help you identify the cause of the problem.
200
- OK. The request has succeeded.
201
- Created. The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a
Location
header field. 204
- No Content. The request was successful but no body was returned.
400
- Bad Request. The request could not be understood by the server, usually due to malformed syntax. The response body will contain more details in the form of an array.
401
- Unauthorized. The client has not provided a valid
Authentication
HTTP header or the user making the request has been disabled. 403
- Forbidden. The client has provided a valid
Authentication
header, but does not have permission to access this resource. 404
- Not Found. The requested resource was not found or the authenticated user cannot access the resource. The response body will explain which resource was not found.
405
- Method Not Allowed. The HTTP verb used, or resource requested is not allowed. Note that we do not allow the
PATCH
verb to be used, andPUT
should be used instead. 406
- Not Acceptable. The content type specified in the
Accept
header was not acceptable to this endpoint. 409
- Conflict. The resource to be created by your request already exists.
410
- Gone. The authenticated user can access the requested resource, but it has been removed. The response body will explain which resource has been removed.
415
- Unsupported Media Type. The response error will explain what types are accepted.
422
- Unprocessable Entity. Could not process a
POST
orPUT
request because the request is invalid. The response body will contain more details. 426
- Upgrade Required. An unsecured connection was refused. Upgrade to TLS/SSL.
429
- Too Many Requests. A rate limit has been reached. The headers will explain the details of the rate limit.
500
- Internal Server Error. The server encountered an error while processing your request and failed. Please retry the request. If the problem persists, please report this to the GoCardless support team and quote the
request_id
. 504
- Gateway Timeout. The request timed out and should be retried. If the problem persists, please report this to the GoCardless support team and quote the
request_id
.
Scenario Simulators
When you’re building an integration with the API, there are some common paths you should make sure your integration handles successfully.
In the sandbox environment, we provide scenario simulators which allow you to manually trigger certain cases (like a customer cancelling their mandate or a payment failing due to lack of funds) from the Dashboard so you can test how your integration responds.
To find out more, see our scenario simulators guide.
Errors
Every error includes a type
, the HTTP status code
, a short message
, a
documentation_url
, linking to the relevant section of this document, and a
unique request_id
which can be used to help the GoCardless support team
find your error quickly.
There is also an errors
key which is an array listing any errors that have
been raised in one of two formats.
When the type
is validation_failed
, each error will be composed of a field
and a message
describing what is wrong with that field.
For all other errors, the structure will contain a reason
and a message
describing what the problem encountered.
There are 4 types of errors, depending on the root cause. These are:
Error types
gocardless
- This is an error that has occured within GoCardless while processing your requests. In some cases, depending on the specific issue highlighted in
errors
, the request should be retried. If the problem persists, it should be reported to our support team with therequest_id
, so we can resolve the issue. invalid_
api_ usage - This is an error with the request you made. It could be an invalid URL, the authentication header could be missing, invalid, or grant insufficient permissions, you may have reached your rate limit, or the syntax of your request could be incorrect. The
errors
will give more detail of the specific issue. invalid_
state - The action you are trying to perform is invalid due to the state of the resource you are requesting it on. For example, a payment you are trying to cancel might already have been submitted. The
errors
will give more details.
validation_
failed - The parameters submitted with your request were invalid. Details of which fields were invalid and why are included in the response. The
request_pointer
parameter indicates the exact field of the request that triggered the validation error.
These four types should be handled very differently: gocardless
errors should send an alert to your dev team, or directly to GoCardless support; invalid_api_usage
should send an alert to your dev team; invalid_state
should alert the end user and not allow them to retry; validation_failed
should alert the end user and prompt them to correct their input.
GoCardless errors
internal_
server_ error - An internal error occurred while processing your request. This should be reported to our support team with the
request_id
, so we can resolve the issue.
request_
timed_ out - The request did not complete within a reasonable time. In this case, the request should be retried (possibly with different parameters). If the problem persists, it should be reported to our support team with the
request_id
, so we can resolve the issue.
query_
timed_ out - The query for this request did not complete within a reasonable time, potentially due to being too complex. In this case, the request should be retried (possibly with different parameters). If the problem persists, it should be reported to our support team with the
request_id
, so we can resolve the issue.
Invalid API usage errors
invalid_
type - The
errors
key may also hold an array of type errors if the JSON you sent was incorrectly typed. These are in the same format as validation errors (with amessage
andfield
per error). A type error will also be returned if you include any additional, unknown parameters.
path_
not_ found - The path was not recognised. Check that you spelled the resource name correctly, and that the URL is formatted correctly.
resource_
not_ found - The ID in the request was not found in our database.
link_
not_ found - One of the
link[resource]
IDs in the request was not found. Your integration should ensure that end users can only use existing resources.
unauthorized
- Your username/password was not recognised.
forbidden
- You were authenticated, but you do not have permission to access that resource.
feature_
disabled - You are trying to use a feature which hasn’t been enabled on your account. Please contact support if you would like to enable it.
not_
acceptable - The content type specified in your
Accept
header was not acceptable to this endpoint.
request_
entity_ too_ large - The body of your request is too large.
unsupported_
media_ type - The API communicates using JSON only. Make sure that your
Accept
header permits JSON, and yourContent-Type
header is supported, if you are sending JSON data (e.g. with aPOST
orPUT
request).
rate_
limit_ exceeded - You have exceeded the rate limit. See the included headers for when your rate limit will be reset.
access_
token_ not_ found - No access token with the ID specified was found.
access_
token_ not_ active - The access token you are using has been disabled.
access_
token_ revoked - The access token you are using has been revoked by the user.
missing_
authorization_ header - No
Authorization
header was included in your request. See making requests for details on how to structure your authorisation header.
invalid_
authorization_ header - The
Authorization
header sent was not valid. Make sure it was constructed as described in making requests.
insufficient_
permissions - The access token you are using does not have the right scope to perform the requested action.
method_
not_ allowed - The HTTP verb used is not permitted. Note that we do not allow
PATCH
requests, andPUT
must be used to update resources.
bad_
request - The request syntax was incorrect.
idempotency_
key_ too_ long - An idempotency key was supplied for this request but exceeded the max length of this key. See idempotency keys for details on how to work with idempotency.
invalid_
document_ structure - The JSON sent to the server was not in the correct structure. Note that JSON parameters may not be sent at the top level, but must be sent under the name of the resource. See the examples for details on how this is done for each endpoint.
invalid_
content_ type - When including a JSON body with a request you must also include a
Content-Type
header, set toapplication/json
orapplication/vnd.api+json
.
tls_
required - The GoCardless API can only be accessed over TLS/SSL. Make sure you are sending requests to urls starting with
https://
, nothttp://
.
missing_
version_ header - No
GoCardless-Version
header was included in your request. See making requests for details on how to set your version header.
version_
not_ found - The
GoCardless-Version
specified was not found. The version must be one of those listed in the changelog.
invalid_
filters - The combination of filters specified in the query string of your request are not allowed. Only certain combinations of filters may be applied to each list endpoint, as documented on each endpoint.
request_
body_ not_ allowed - Sending a request body is not supported for the HTTP method you have used. Use query string parameters in the URL instead.
customer_
data_ removed - The customer has been removed and they can no longer be returned by our API. You should remove any GoCardless references to these objects in your systems.
payout_
items_ data_ archived - Payout items for payouts created more than 6 months ago have been archived. Please contact support if you require access to this data.
Invalid state errors
cancellation_
failed - The mandate, payment or subscription was not in a cancellable state. It might have already been cancelled, failed, or it might be too late in the submission process to cancel. For example, payments cannot be cancelled once they are submitted to the banks.
retry_
failed - The payment could not be retried.
disable_
failed - The customer or creditor bank account could not be disabled, as it is already disabled.
mandate_
is_ inactive - The payment could not be created, because the mandate linked is cancelled, failed, or expired.
mandate_
replaced - The resource could not be created, because the mandate it links to has been replaced (for example, because the creditor has moved to a new Service User Number). The new mandate can be found through the reference to
links[new_mandate]
in the error response, or by retrieving the original mandate and checkinglinks[new_mandate]
.
bank_
account_ disabled - The mandate could not be created because the customer bank account linked is disabled.
mandate_
not_ inactive - The mandate could not be reinstated, because it is already being submitted, or is active.
refund_
is_ unreachable - The refund could not be created, because it would not reach the target bank account.
refund_
payment_ invalid_ state - The refund could not be created, because the payment specified is not
confirmed
orpaid_out
.
total_
amount_ confirmation_ invalid - The refund could not be created because the total amount refunded does not match.
number_
of_ refunds_ exceeded - The refund could not be created because five refunds have already been created for the given payment.
idempotent_
creation_ conflict - The resource has not been created as a resource has already been created with the supplied idempotency key. See idempotency keys for details.
customer_
bank_ account_ token_ used - The customer bank account could not be created because the token given has already been used.
billing_
request_ must_ be_ ready_ to_ fulfil -
The billing request must have no outstanding required actions. To check the actions please view the actions array in the billing request get response.
Validation errors
The errors
key may also hold an array of individual validation failures in
this case, or one of the following errors.
bank_
account_ exists - The customer or creditor bank account you are trying to create already exists. These resources must be unique.
You should use the corresponding update endpoints to update the details on the existing bank account instead, which will be referenced aslinks[customer_bank_account]
orlinks[creditor_bank_account]
(as appropriate) in the error response.
available_
refund_ amount_ insufficient - The refund requested by the creditor could not be created for the given currency, because the creditor does not have a sufficient balance available to cover the cost of the refund.
The amount available for refunds will fluctuate over time, as it is calculated in real time using several indicators. Examples of such indicators are in-flight payments, pending refunds, and any applicable ‘buffer allowance’ provided by GoCardless for the creditor in the given currency. The amount available for refunds will be returned in themetadata
of the error response, under theavailable_refund_amount
key, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
Content-Type: application/json
{
"customer_bank_accounts": {
"account_number": "55779911",
"branch_code": "I'm not a sort code",
"account_holder_name": "Frank Osborne",
"country_code": "GB",
"links": {
"customer": "CU123"
}
}
}
HTTP/1.1 422 (Unprocessable Entity)
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/#validation_failed",
"message": "Validation failed",
"type": "validation_failed",
"code": 422,
"request_id": "dd50eaaf-8213-48fe-90d6-5466872efbc4",
"errors": [
{
"message": "must be a number",
"field": "branch_code",
"request_pointer": "/customer_bank_accounts/branch_code"
}, {
"message": "is the wrong length (should be 8 characters)",
"field": "branch_code",
"request_pointer": "/customer_bank_accounts/branch_code"
}
]
}
}
POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
Content-Type: application/json
{
"customer_bank_accounts": {
"account_number": "55779911",
"branch_code": "200000",
"account_holder_name": "Frank Osborne",
"country_code": "GB",
"links": {
"customer": "CU123"
}
}
}
HTTP/1.1 400 (Bad Request)
Content-Type: application/json
{
"error": {
"message": "Invalid document structure",
"documentation_url": "https://developer.gocardless.com/#invalid_document_structure",
"type": "invalid_api_usage",
"request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
"code": 400,
"errors": [
{
"reason": "invalid_document_structure",
"message": "Invalid document structure"
}
]
}
}
POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
Content-Type: application/json
{
"creditor_bank_accounts": {
"account_number": "55779911",
"branch_code": "200000",
"country_code": "GB",
"set_as_default_payout_account": true,
"account_holder_name": "Nude Wines",
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 409 (Conflict)
Content-Type: application/json
{
"error": {
"message": "Bank account already exists",
"documentation_url": "https://developer.gocardless.com/#bank_account_exists",
"type": "validation_failed",
"request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
"code": 409,
"errors": [
{
"reason": "bank_account_exists",
"message": "Bank account already exists",
"links": {
"creditor_bank_account": "BA123"
}
}
]
}
}
Billing Requests
This section contains API endpoints that are used to power Billing Requests.
Billing Requests help create resources that require input or action from a customer. An example of required input might be additional customer billing details, while an action would be asking a customer to authorise a payment using their mobile banking app.
Billing Requests go through a simple lifecycle, with the state exposed as the
status
field:
-
pending
, actions need completing before we can fulfil -
ready_to_fulfil
, all required actions are complete and the integrator may fulfil this request -
fulfilled
, the request is fulfilled and an resource has been created -
cancelled
, request was cancelled before it can be completed (no resource will ever be created)
Integrators have a choice between building their own user experience flows to complete the required actions, or creating a Billing Request Flow against the Billing Request. Billing Request Flows are a GoCardless managed flow that knows how to process outstanding actions on the Request, helping the customer provide their required details and fulfil the request.
We advise most integrators make use of Billing Request Flows to benefit from the efforts GoCardless put into optimising conversion, adapting to a changing regulatory environment, and to reduce integration effort.
Even for integrators who want a whitelabel experience, we might advise completing some actions through a customer integration and leveraging the Billing Request Flow to complete the more complex actions.
Bank Authorisations
Bank Authorisations can be used to authorise Billing Requests. Authorisations are created against a specific bank, usually the bank that provides the payer’s account.
Creation of Bank Authorisations is only permitted from GoCardless hosted UIs (see Billing Request Flows) to ensure we meet regulatory requirements for checkout flows.
Properties
id
- Unique identifier, beginning with “BAU”.
authorisation_
type - Type of authorisation, can be either ‘mandate’ or ‘payment’.
authorised_
at - Fixed timestamp, recording when the user has been authorised.
created_
at - Timestamp when the flow was created
expires_
at - Timestamp when the url will expire. Each authorisation url currently lasts for 15 minutes, but this can vary by bank.
last_
visited_ at - Fixed timestamp, recording when the authorisation URL has been visited.
qr_
code_ url - URL to a QR code PNG image of the bank authorisation url.
This QR code can be used as an alternative to providing the
url
to the payer to allow them to authorise with their mobile devices. redirect_
uri - URL that the payer can be redirected to after authorising the payment.
On completion of bank authorisation, the query parameter of either
outcome=success
oroutcome=failure
will be appended to theredirect_uri
to indicate the result of the bank authorisation. If the bank authorisation is expired, the query parameteroutcome=timeout
will be appended to theredirect_uri
, in which case you should prompt the user to try the bank authorisation step again.The
redirect_uri
you provide should handle theoutcome
query parameter for displaying the result of the bank authorisation as outlined above.The BillingRequestFlow ID will also be appended to the
redirect_uri
as query parameterid=BRF123
.Defaults to
https://pay.gocardless.com/billing/static/thankyou
. url
- URL for an oauth flow that will allow the user to authorise the payment
links
[billing_ request] - ID of the billing request against which this authorisation was created.
links
[institution] - ID of the institution against which this authorisation was created.
Create a Bank Authorisation
Create a Bank Authorisation.
Relative endpoint: POST /bank_authorisations
Restricted: this endpoint is restricted as the authorisation must be used within a
checkout flow that meets regulatory requirements for each payment
scheme. Integrators should use a Billing Request Flow to do this.
If you would like to enable bank authorisations, you will need to go through a separate compliance process.
For more details please get in touch.
Parameters
redirect_
uri - URL that the payer can be redirected to after authorising the payment.
On completion of bank authorisation, the query parameter of either
outcome=success
oroutcome=failure
will be appended to theredirect_uri
to indicate the result of the bank authorisation. If the bank authorisation is expired, the query parameteroutcome=timeout
will be appended to theredirect_uri
, in which case you should prompt the user to try the bank authorisation step again.The
redirect_uri
you provide should handle theoutcome
query parameter for displaying the result of the bank authorisation as outlined above.The BillingRequestFlow ID will also be appended to the
redirect_uri
as query parameterid=BRF123
.Defaults to
https://pay.gocardless.com/billing/static/thankyou
. links
[billing_ request] - ID of the billing request against which this authorisation was created.
POST https://api.gocardless.com/bank_authorisations HTTP/1.1
Content-Type: application/json
{
"bank_authorisations": {
"redirect_uri": "https://my-company.com/landing",
"links": {
"billing_request": "BRQ123"
}
}
}
HTTP/1.1 201 Created
Location: /bank_authorisations/BAU123
Content-Type: application/json
{
"bank_authorisations": {
"id": "BAU123",
"url": "https://pay-staging.gocardless.com/obauth/BAU123",
"qr_code_url": "https://pay-staging.gocardless.com/obauth/BAU123/qr_code",
"created_at": "2021-03-25T17:26:28.305Z",
"authorisation_type": "payment",
"last_visited_at": null,
"authorised_at": null,
"expires_at": "2021-03-25T17:41:28.000Z",
"redirect_uri": "https://my-company.com/landing",
"links": {
"billing_request": "BRQ123",
"institution": "monzo"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->bankAuthorisations()->create([
"params" => [
"redirect_uri" => "https://my-company.com/landing",
"links" => [
"billing_request" => "BRQ123"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.bank_authorisations.create(params={
"redirect_uri": "https://my-company.com/landing",
"links": {
"billing_request": "BRQ123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.bank_authorisations.create(
params: {
redirect_uri: "https://my-company.com/landing",
links: {
billing_request: "BRQ123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
BankAuthorisation bankAuthorisation = client.bankAuthorisations().create()
.withRedirectUri("https://my-company.com/landing")
.withLinksBillingRequest("BRQ123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const bankAuthorisation = await client.bankAuthorisations.create({
redirect_uri: "https://my-company.com/landing",
links: {
billing_request: "BRQ123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var authorisationLinks = new gocardless.BankAuthorisationCreateRequest.BankAuthorisationLinks
{
BillingRequest = "BRQ123"
};
var resp = await gocardless.BankAuthorisations.CreateAsync(
new GoCardless.Services.BankAuthorisationCreateRequest()
{
RedirectUri = "https://my-company.com/landing",
links = authorisationLinks,
}
);
GoCardless.Resources.BankAuthorisation bankAuthorisation = resp.BankAuthorisation;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
bankAuthorisationCreateParams := gocardless.BankAuthorisationCreateParams{
RedirectUri: "https://my-company.com/landing",
Links: gocardless.BankAuthorisationCreateParamsLinks{
BillingRequest: "BR123",
},
}
bankAuthorisation, err := client.BankAuthorisations.Create(context, bankAuthorisationCreateParams)
}
Get a Bank Authorisation
Get a single bank authorisation.
Relative endpoint: GET /bank_authorisations/BAU123
GET https://api.gocardless.com/bank_authorisations/BAU123 HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"bank_authorisations": {
"id": "BAU123",
"url": "https://pay-staging.gocardless.com/obauth/BAU123",
"qr_code_url": "https://pay-staging.gocardless.com/obauth/BAU123/qr_code",
"created_at": "2021-03-25T17:26:28.305Z",
"authorisation_type": "payment",
"last_visited_at": null,
"authorised_at": null,
"expires_at": "2021-03-25T17:41:28.000Z",
"redirect_uri": "https://my-company.com/landing",
"links": {
"billing_request": "BRQ123",
"institution": "monzo"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->bankAuthorisations()->get("BAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.bank_authorisations.get("BAU123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.bank_authorisations.get("BAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.bankAuthorisations().get("BAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.bankAuthorisations.find("BAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BankAuthorisations.GetAsync("BAU123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
bankAuthorisation, err := client.BankAuthorisations.Get(context, "BAU123")
}
Billing Requests
Billing Requests help create resources that require input or action from a customer. An example of required input might be additional customer billing details, while an action would be asking a customer to authorise a payment using their mobile banking app.
See Billing Requests: Overview for how-to’s, explanations and tutorials. Important: All properties associated with subscription_request
and instalment_schedule_request
are only supported for ACH and PAD schemes.
Properties
id
- Unique identifier, beginning with “BRQ”.
actions
- List of actions that can be performed before this billing request can be fulfilled.
Each instance will contain these properties:
-
available_currencies
: List of currencies the current mandate supports -
bank_authorisation
: Describes the behaviour of bank authorisations, for the bank_authorisation action -
collect_customer_details
: Additional parameters to help complete the collect_customer_details action -
completes_actions
: Which other action types this action can complete. -
institution_guess_status
: Describes whether we inferred the institution from the provided bank account details. One of:-
not_needed
: we won’t attempt to infer the institution as it is not needed. Either because it was manually selected or the billing request does not support this feature -
pending
: we are waiting on the bank details in order to infer the institution -
failed
: we weren’t able to infer the institution -
success
: we inferred the institution and added it to the resources of a Billing Request
-
-
required
: Informs you whether the action is required to fulfil the billing request or not. -
requires_actions
: Requires completing these actions before this action can be completed. -
status
: Status of the action -
type
: Unique identifier for the action.
-
created_
at - Fixed timestamp, recording when this resource was created.
fallback_
enabled - (Optional) If true, this billing request can fallback from instant payment to direct debit.
Should not be set if GoCardless payment intelligence feature is used.
See Billing Requests: Retain customers with Fallbacks for more information.
fallback_
occurred - True if the billing request was completed with direct debit.
instalment_
schedule_ request [app_ fee] - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
instalment_
schedule_ request [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
instalment_
schedule_ request [instalments] - instalments to be created. See create (with dates) and create (with schedule) for more information on how to specify instalments.
links
[instalment_ schedule] - (Optional) ID of the instalment_schedule that was created from this instalment schedule request.
instalment_
schedule_ request [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.
instalment_
schedule_ request [name] - Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
instalment_
schedule_ request [payment_ reference] - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
instalment_
schedule_ request [retry_ if_ possible] - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. instalment_
schedule_ request [total_ amount] - The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
mandate_
request [authorisation_ source] - This field is ACH specific, sometimes referred to as SEC code.
This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)
mandate_
request [consent_ type] - This attribute represents the authorisation type between the payer and merchant. It can be set to
one_off
,recurring
orstanding
for ACH scheme. Andsingle
,recurring
andsporadic
for PAD scheme. Note: This is only supported for ACH and PAD schemes. constraints
[end_ date] - The latest date at which payments can be taken, must occur after start_date if present
This is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.
constraints
[max_ amount_ per_ payment] - The maximum amount that can be charged for a single payment. Required for VRP.
constraints
[payment_ method] - A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes.
periodic_
limits - List of periodic limits and constraints which apply to them
Each instance will contain these properties:
-
alignment
: The alignment of the period.calendar
- this will finish on the end of the current period. For example this will expire on the Monday for the current week or the January for the next year.creation_date
- this will finish on the next instance of the current period. For example Monthly it will expire on the same day of the next month, or yearly the same day of the next year. -
max_payments
: (Optional) The maximum number of payments that can be collected in this periodic limit. -
max_total_amount
: The maximum total amount that can be charged for all payments in this periodic limit. Required for VRP. -
period
: The repeating period for this mandate
-
constraints
[start_ date] - The date from which payments can be taken.
This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.
mandate_
request [currency] - ISO 4217 currency code.
mandate_
request [description] - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
links
[mandate] - (Optional) ID of the mandate that was created from this mandate request. this mandate request.
mandate_
request [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.
mandate_
request [payer_ requested_ dual_ signature] - This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.
mandate_
request [scheme] - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_
request [verify] - Verification preference for the mandate. One of:
-
minimum
: only verify if absolutely required, such as when part of scheme rules -
recommended
: in addition tominimum
, use the GoCardless payment intelligence solution to decide if a payer should be verified -
when_available
: if verification mechanisms are available, use them -
always
: aswhen_available
, but fail to create the Billing Request if a mechanism isn’t available
-
By default, all Billing Requests use the recommended
verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended
behaves like minimum
.
If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum
verification preference.
See Billing Requests: Creating Verified Mandates for more information.
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.
payment_
request [amount] - Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_
request [app_ fee] - The amount to be deducted from the payment as an app fee, to be paid to the partner integration which created the billing request, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
payment_
request [currency] -
ISO 4217 currency code.
GBP
andEUR
supported;GBP
with your customers in the UK and forEUR
with your customers in supported Eurozone countries only. payment_
request [description] - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_
request [funds_ settlement] - This field will decide how GoCardless handles settlement of funds from the customer.
-
managed
will be moved through GoCardless’ account, batched, and payed out. -
direct
will be a direct transfer from the payer’s account to the merchant where invoicing will be handled separately.
-
links
[payment] - (Optional) ID of the payment that was created from this payment request.
payment_
request [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.
payment_
request [reference] - A custom payment reference defined by the merchant. It is only available for payments using the Direct Funds settlement model on the Faster Payments scheme.
payment_
request [scheme] - (Optional) A scheme used for Open Banking payments. Currently
faster_payments
is supported in the UK (GBP) andsepa_credit_transfer
andsepa_instant_credit_transfer
are supported in supported Eurozone countries (EUR). For Eurozone countries,sepa_credit_transfer
is used as the default. Please be aware thatsepa_instant_credit_transfer
may incur an additional fee for your customer. purpose_
code - Specifies the high-level purpose of a mandate and/or payment using a set of pre-defined categories. Required for the PayTo scheme, optional for all others. Currently
mortgage
,utility
,loan
,dependant_support
,gambling
,retail
,salary
,personal
,government
,pension
,tax
andother
are supported. customer
[company_ name] - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). customer
[created_ at] - Fixed timestamp, recording when this resource was created.
customer
[email] - Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer
[family_ name] - Customer’s surname. Required unless a
company_name
is provided. customer
[given_ name] - Customer’s first name. Required unless a
company_name
is provided. customer
[id] - Unique identifier, beginning with “CU”.
customer
[language] -
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the
country_code
(if supplied) or default to “en”. customer
[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.
customer
[phone_ number] - ITU E.123 formatted phone number, including country code.
customer_
bank_ account [account_ holder_ name] - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
customer_
bank_ account [account_ number_ ending] - The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
customer_
bank_ account [account_ type] - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
customer_
bank_ account [bank_ account_ token] - A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.
customer_
bank_ account [bank_ name] - Name of bank, taken from the bank details.
customer_
bank_ account [country_ code] -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. customer_
bank_ account [created_ at] - Fixed timestamp, recording when this resource was created.
customer_
bank_ account [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
customer_
bank_ account [enabled] - Boolean value showing whether the bank account is enabled or disabled.
customer_
bank_ account [id] - Unique identifier, beginning with “BA”.
links
[customer] - ID of the customer that owns this bank account.
customer_
bank_ account [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.
customer_
billing_ detail [address_ line1] - The first line of the customer’s address.
customer_
billing_ detail [address_ line2] - The second line of the customer’s address.
customer_
billing_ detail [address_ line3] - The third line of the customer’s address.
customer_
billing_ detail [city] - The city of the customer’s address.
customer_
billing_ detail [country_ code] - ISO 3166-1 alpha-2 code.
customer_
billing_ detail [created_ at] - Fixed timestamp, recording when this resource was created.
customer_
billing_ detail [danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer_
billing_ detail [id] - Unique identifier, beginning with “CU”.
customer_
billing_ detail [ip_ address] - For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
Not required for creating offline mandates where
authorisation_source
is set to telephone or paper. customer_
billing_ detail [postal_ code] - The customer’s postal code.
customer_
billing_ detail [region] - The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). schemes
- The schemes associated with this customer billing detail
customer_
billing_ detail [swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
status
- One of:
-
pending
: the billing request is pending and can be used -
ready_to_fulfil
: the billing request is ready to fulfil -
fulfilling
: the billing request is currently undergoing fulfilment -
fulfilled
: the billing request has been fulfilled and a payment created -
cancelled
: the billing request has been cancelled and cannot be used
-
subscription_
request [amount] - Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
subscription_
request [app_ fee] - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
subscription_
request [count] - The total number of payments that should be taken by this subscription.
subscription_
request [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
subscription_
request [day_ of_ month] - As per RFC 2445. The day of the month to charge customers on.
1
-28
or-1
to indicate the last day of the month. subscription_
request [interval] - Number of
interval_units
between customer charge dates. Must be greater than or equal to1
. Must result in at least one charge date per year. Defaults to1
. subscription_
request [interval_ unit] - The unit of time between customer charge dates. One of
weekly
,monthly
oryearly
. links
[subscription] - (Optional) ID of the subscription that was created from this subscription request.
subscription_
request [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.
subscription_
request [month] - Name of the month on which to charge a customer. Must be lowercase. Only applies
when the interval_unit is
yearly
. subscription_
request [name] - Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
subscription_
request [payment_ reference] - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
subscription_
request [retry_ if_ possible] - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. subscription_
request [start_ date] - The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate’s
next_possible_charge_date
. When left blank andmonth
orday_of_month
are provided, this will be set to the date of the first payment. If created withoutmonth
orday_of_month
this will be set as the mandate’snext_possible_charge_date
. links
[bank_ authorisation] - (Optional) ID of the bank authorisation that was used to verify this request.
links
[creditor] - ID of the associated creditor.
links
[customer] - ID of the customer that will be used for this request
links
[customer_ bank_ account] - (Optional) ID of the customer_bank_account that will be used for this request
links
[customer_ billing_ detail] - ID of the customer billing detail that will be used for this request
links
[instalment_ schedule_ request] - (Optional) ID of the associated instalment schedule request
links
[instalment_ schedule_ request_ instalment_ schedule] - (Optional) ID of the instalment_schedule that was created from this instalment schedule request.
links
[mandate_ request] - (Optional) ID of the associated mandate request
links
[mandate_ request_ mandate] - (Optional) ID of the mandate that was created from this mandate request. this mandate request.
links
[organisation] - ID of the associated organisation.
links
[payment_ provider] - (Optional) ID of the associated payment provider
links
[payment_ request] - (Optional) ID of the associated payment request
links
[payment_ request_ payment] - (Optional) ID of the payment that was created from this payment request.
links
[subscription_ request] - (Optional) ID of the associated subscription request
links
[subscription_ request_ subscription] - (Optional) ID of the subscription that was created from this subscription request.
Create a Billing Request
Important: All properties associated with subscription_request
and instalment_schedule_request
are only supported for ACH and PAD schemes.
Relative endpoint: POST /billing_requests
Note: Instant Bank Pay is only available for transactions in GBP with your customers in the UK and for EUR with your customers in supported Eurozone countries. We will be adding other countries soon.
Warning: by default, the ability to provide a custom mandate reference is switched off. The banking system rules for valid references are quite complex, and we recommend allowing GoCardless to generate it. If you would like to provide custom references, please contact support.
Parameters
fallback_
enabled - (Optional) If true, this billing request can fallback from instant payment to direct debit.
Should not be set if GoCardless payment intelligence feature is used.
See Billing Requests: Retain customers with Fallbacks for more information.
instalment_
schedule_ request [app_ fee] - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
instalment_
schedule_ request [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
instalment_
schedule_ request [instalments] - instalments to be created. See create (with dates) and create (with schedule) for more information on how to specify instalments.
instalment_
schedule_ request [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.
instalment_
schedule_ request [name] - Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
instalment_
schedule_ request [payment_ reference] - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
instalment_
schedule_ request [retry_ if_ possible] - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. instalment_
schedule_ request [total_ amount] - The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
mandate_
request [authorisation_ source] - This field is ACH specific, sometimes referred to as SEC code.
This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)
mandate_
request [constraints] - Constraints that will apply to the mandate_request. (Optional) Specifically for PayTo and VRP.
Properties:
-
end_date
: The latest date at which payments can be taken, must occur after start_date if presentThis is an optional field and if it is not supplied the agreement will be considered open and will not have an end date. Keep in mind the end date must take into account how long it will take the user to set up this agreement via the Billing Request.
-
max_amount_per_payment
: The maximum amount that can be charged for a single payment. Required for VRP. -
payment_method
: A constraint where you can specify info (free text string) about how payments are calculated. Note: This is only supported for ACH and PAD schemes. -
periodic_limits
: List of periodic limits and constraints which apply to them -
start_date
: The date from which payments can be taken.This is an optional field and if it is not supplied the start date will be set to the day authorisation happens.
-
mandate_
request [currency] - ISO 4217 currency code.
mandate_
request [description] - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_
request [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.
mandate_
request [reference] - Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
mandate_
request [scheme] - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_
request [verify] - Verification preference for the mandate. One of:
-
minimum
: only verify if absolutely required, such as when part of scheme rules -
recommended
: in addition tominimum
, use the GoCardless payment intelligence solution to decide if a payer should be verified -
when_available
: if verification mechanisms are available, use them -
always
: aswhen_available
, but fail to create the Billing Request if a mechanism isn’t available
-
By default, all Billing Requests use the recommended
verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended
behaves like minimum
.
If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum
verification preference.
See Billing Requests: Creating Verified Mandates for more information.
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.
payment_
request [amount] - Amount in minor unit (e.g. pence in GBP, cents in EUR).
payment_
request [app_ fee] - The amount to be deducted from the payment as an app fee, to be paid to the partner integration which created the billing request, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
payment_
request [currency] -
ISO 4217 currency code.
GBP
andEUR
supported;GBP
with your customers in the UK and forEUR
with your customers in supported Eurozone countries only. payment_
request [description] - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_
request [funds_ settlement] - This field will decide how GoCardless handles settlement of funds from the customer.
-
managed
will be moved through GoCardless’ account, batched, and payed out. -
direct
will be a direct transfer from the payer’s account to the merchant where invoicing will be handled separately.
-
payment_
request [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.
payment_
request [reference] - A custom payment reference defined by the merchant. It is only available for payments using the Direct Funds settlement model on the Faster Payments scheme.
payment_
request [retry_ if_ possible] - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. Important: This is not applicable to IBP and VRP payments. payment_
request [scheme] - (Optional) A scheme used for Open Banking payments. Currently
faster_payments
is supported in the UK (GBP) andsepa_credit_transfer
andsepa_instant_credit_transfer
are supported in supported Eurozone countries (EUR). For Eurozone countries,sepa_credit_transfer
is used as the default. Please be aware thatsepa_instant_credit_transfer
may incur an additional fee for your customer. purpose_
code - Specifies the high-level purpose of a mandate and/or payment using a set of pre-defined categories. Required for the PayTo scheme, optional for all others. Currently
mortgage
,utility
,loan
,dependant_support
,gambling
,retail
,salary
,personal
,government
,pension
,tax
andother
are supported. subscription_
request [amount] - Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
subscription_
request [app_ fee] - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
subscription_
request [count] - The total number of payments that should be taken by this subscription.
subscription_
request [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
subscription_
request [day_ of_ month] - As per RFC 2445. The day of the month to charge customers on.
1
-28
or-1
to indicate the last day of the month. subscription_
request [interval] - Number of
interval_units
between customer charge dates. Must be greater than or equal to1
. Must result in at least one charge date per year. Defaults to1
. subscription_
request [interval_ unit] - The unit of time between customer charge dates. One of
weekly
,monthly
oryearly
. subscription_
request [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.
subscription_
request [month] - Name of the month on which to charge a customer. Must be lowercase. Only applies
when the interval_unit is
yearly
. subscription_
request [name] - Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
subscription_
request [payment_ reference] - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
subscription_
request [retry_ if_ possible] - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. subscription_
request [start_ date] - The date on which the first payment should be charged. If fulfilled after this date, this will be set as the mandate’s
next_possible_charge_date
. When left blank andmonth
orday_of_month
are provided, this will be set to the date of the first payment. If created withoutmonth
orday_of_month
this will be set as the mandate’snext_possible_charge_date
. links
[creditor] - ID of the associated creditor. Only required if your account manages multiple creditors.
links
[customer] - ID of the customer against which this request should be made.
links
[customer_ bank_ account] - (Optional) ID of the customer_bank_account against which this request should be made.
POST https://api.gocardless.com/billing_requests HTTP/1.1
Content-Type: application/json
{
"billing_requests": {
"payment_request": {
"description": "First Payment",
"amount": "500",
"currency": "GBP"
},
"mandate_request": {
"scheme": "bacs"
}
}
}
HTTP/1.1 201 Created
Location: /billing_requests/BRQ123
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [
"email",
"given_name",
"family_name"
],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "pending"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
},
{
"type": "bank_authorisation",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_bank_account"
],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": null,
"family_name": null,
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.374Z",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->create([
"params" => [
"payment_request" => [
"description" => "First Payment",
"amount" => "500",
"currency" => "GBP",
],
"mandate_request" => [
"scheme" => "bacs"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.create(params={
"payment_request": {
"description": "First Payment",
"amount": "500",
"currency": "GBP",
},
"mandate_request": {
"scheme": "bacs"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.create(
params: {
payment_request: {
description: "First Payment",
amount: "500",
currency: "GBP",
},
mandate_request: {
scheme: "bacs"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
BillingRequest billingRequest = client.billingRequests().create()
.withPaymentRequestDescription("First Payment")
.withPaymentRequestAmount(500)
.withPaymentRequestCurrency(Currency.GBP)
.withMandateRequestScheme("bacs")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const billingRequest = await client.billingRequests.create({
payment_request: {
description: "First Payment",
amount: "500",
currency: "GBP",
},
mandate_request: {
scheme: "bacs"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentRequest = new gocardless.BillingRequestCreateRequest.BillingRequestPaymentRequest
{
Description = "First payment",
Amount = 500,
Currency = "GBP",
};
var mandateRequest = new gocardless.BillingRequestCreateRequest.BillingRequestMandateRequest
{
Scheme = "bacs",
};
var resp = await gocardless.BillingRequests.CreateAsync(
new GoCardless.Services.BillingRequestCreateRequest()
{
PaymentRequest = paymentRequest,
MandateRequest = mandateRequest,
}
);
GoCardless.Resources.BillingRequest billingRequest = resp.BillingRequest;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestCreateParams := gocardless.BillingRequestCreateParams{
PaymentRequest: &gocardless.BillingRequestCreateParamsPaymentRequest{
Amount: 1000,
Currency: "GBP",
Description: "First Payment",
},
MandateRequest: &gocardless.BillingRequestCreateParamsMandateRequest{
Scheme: "bacs",
},
}
billingRequest, err := client.BillingRequests.Create(context, billingRequestCreateParams)
}
Collect customer details
If the billing request has a pending collect_customer_details
action, this endpoint can be used to collect the details in order to
complete it.
The endpoint takes the same payload as Customers, but checks that the customer fields are populated correctly for the billing request scheme.
Whatever is provided to this endpoint is used to update the referenced customer, and will take effect immediately after the request is successful.
Relative endpoint: POST /billing_requests/BRQ123/actions/collect_customer_details
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.
Parameters
customer
[company_ name] - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). customer
[email] - Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer
[family_ name] - Customer’s surname. Required unless a
company_name
is provided. customer
[given_ name] - Customer’s first name. Required unless a
company_name
is provided. customer
[language] - ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided and a customer was linked during billing request creation, the linked customer language will be used. Otherwise, the language is default to “en”.
customer
[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.
customer
[phone_ number] - ITU E.123 formatted phone number, including country code.
customer_
billing_ detail [address_ line1] - The first line of the customer’s address.
customer_
billing_ detail [address_ line2] - The second line of the customer’s address.
customer_
billing_ detail [address_ line3] - The third line of the customer’s address.
customer_
billing_ detail [city] - The city of the customer’s address.
customer_
billing_ detail [country_ code] - ISO 3166-1 alpha-2 code.
customer_
billing_ detail [danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer_
billing_ detail [ip_ address] - For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
Not required for creating offline mandates where
authorisation_source
is set to telephone or paper. customer_
billing_ detail [postal_ code] - The customer’s postal code.
customer_
billing_ detail [region] - The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). customer_
billing_ detail [swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_customer_details HTTP/1.1
Content-Type: application/json
{
"data": {
"customer": {
"email": "alice@example.com",
"given_name": "Alice",
"family_name": "Smith"
},
"customer_billing_detail": {
"address_line1": "1 Somewhere Lane"
}
}
}
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"creditor": "CR123",
"mandate_request": "MRQ123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "pending"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
},
{
"type": "bank_authorisation",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_bank_account"
],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": "alice@example.com",
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->collectCustomerDetails("BR123", [
"params" => [
"customer" => [
"email" => "alice@example.com",
"given_name" => "Alice",
"family_name" => "Smith"
],
"customer_billing_detail" => [
"address_line1" => "1 Somewhere Lane"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.collect_customer_details("BR123", params={
customer: {
email: "alice@example.com",
given_name: "Alice",
family_name: "Smith",
},
customer_billing_detail: {
address_line1: "1 Somewhere Lane"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.collect_customer_details("BR123", {
params: {
customer: {
email: "alice@example.com",
given_name: "Alice",
family_name: "Smith",
},
customer_billing_detail: {
address_line1: "1 Somewhere Lane"
}
}
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().collectCustomerDetails("BR123")
.withCustomerEmail("alice@example.com")
.withCustomerGivenName("Alice")
.withCustomerFamilyName("Smith")
.withCustomerBillingDetailAddressLine1("1 Somewhere Lane")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.collectCustomerDetails("BR123", {
customer: {
email: "alice@example.com",
given_name: "Alice",
family_name: "Smith",
},
customer_billing_detail: {
address_line1: "1 Somewhere Lane"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customer = new gocardless.BillingRequests.CollectCustomerDetailsRequest.BillingRequestCustomer
{
Email = "alice@example.com",
GivenName = "Alice",
FamilyName = "Smith",
};
var customerBillingDetail = = new gocardless.BillingRequests.CollectCustomerDetailsRequest.BillingRequestCustomerBillingDetail
{
AddressLine1 = "1 Somewhere Lane",
};
var resp = await gocardless.BillingRequests.CollectCustomerDetails("BR123",
new BillingRequestCollectCustomerDetailsRequest
{
Customer = customer,
CustomerBillingDetail = customerBillingDetail,
});
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestCollectCustomerDetailsParams := gocardless.BillingRequestCollectCustomerDetailsParams{
Customer: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomer{
GivenName: "Alice",
FamilyName: "Smith",
Email: "alice@example.com",
},
CustomerBillingDetail: &gocardless.BillingRequestCollectCustomerDetailsParamsCustomerBillingDetail{
AddressLine1: "1 Somewhere Lane",
},
}
billingRequest, err := client.BillingRequests.CollectCustomerDetails(context, "BR123", billingRequestCollectCustomerDetailsParams)
}
Collect bank account details
If the billing request has a pending
collect_bank_account
action, this endpoint can be
used to collect the details in order to complete it.
The endpoint takes the same payload as Customer Bank Accounts, but check the bank account is valid for the billing request scheme before creating and attaching it.
If the scheme is PayTo and the pay_id is available, this can be included in the payload along with the country_code.
ACH scheme For compliance reasons, an extra validation step is done using a third-party provider to make sure the customer’s bank account can accept Direct Debit. If a bank account is discovered to be closed or invalid, the customer is requested to adjust the account number/routing number and succeed in this check to continue with the flow.
BACS scheme Payer Name Verification is enabled by default for UK based bank accounts, meaning we verify the account holder name and bank account number match the details held by the relevant bank.
Relative endpoint: POST /billing_requests/BRQ123/actions/collect_bank_account
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.
Parameters
account_
holder_ name - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
account_
number - Bank account number - see local details for more information. Alternatively you can provide an
iban
. account_
number_ suffix - Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
account_
type - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
code - Bank code - see local details for more information. Alternatively you can provide an
iban
. branch_
code - Branch code - see local details for more information. Alternatively you can provide an
iban
. country_
code -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
iban
- International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
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.
pay_
id - A unique record such as an email address, mobile number or company number, that can be used to make and accept payments.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/collect_bank_account HTTP/1.1
Content-Type: application/json
{
"data": {
"account_number": "55779911",
"branch_code": "200000",
"account_holder_name": "Frank Osborne",
"country_code": "GB"
}
}
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_bank_account": "BA123",
"creditor": "CR123",
"mandate_request": "MRQ123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [
"email",
"given_name",
"family_name"
],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "pending"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
},
{
"type": "bank_authorisation",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_bank_account"
],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_bank_account": {
"id": "BA123",
"created_at": "2014-05-08T17:01:06.000Z",
"account_holder_name": "Frank Osborne",
"account_number_ending": "11",
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"metadata": {},
"enabled": true,
"links": {
"customer": "CU123"
}
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->collectBankAccount("BR123", [
"params" => [
"account_number" => "55779911",
"branch_code" => "200000",
"account_holder_name" => "Frank Osborne",
"country_code" => "GB"
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.collect_bank_account("BR123", params={
account_number: "55779911",
branch_code: "200000",
account_holder_name: "Frank Osborne",
country_code: "GB",
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.collect_bank_account("BR123", {
params: {
account_number: "55779911",
branch_code: "200000",
account_holder_name: "Frank Osborne",
country_code: "GB",
}
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().collectBankAccount("BR123")
.withAccountNumber("55779911")
.withBranchCode("200000")
.withAccountHolderName("Frank Osborne")
.withCountryCode("GB")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.collectBankAccount("BR123", {
account_number: "55779911",
branch_code: "200000",
account_holder_name: "Frank Osborne",
country_code: "GB",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequests.CollectBankAccountAsync("BR123",
new BillingRequestCollectBankAccountRequest
{
AccountNumber = "55779911",
BranchCode = "200000",
AccountHolderName = "Frank Osborne",
CountryCode = "GB",
});
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestCollectBankAccountParams := gocardless.BillingRequestCollectBankAccountParams{
BranchCode: "200000",
CountryCode: "GB",
AccountNumber: "55779911",
AccountHolderName: "Frank Osborne",
}
billingRequest, err := client.BillingRequests.CollectBankAccount(context, "BR123", billingRequestCollectBankAccountParams)
}
Confirm the payer details
This is needed when you have a mandate request. As a scheme compliance rule we are required to allow the payer to crosscheck the details entered by them and confirm it.
Relative endpoint: POST /billing_requests/BRQ123/actions/confirm_payer_details
Parameters
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.
payer_
requested_ dual_ signature - This attribute can be set to true if the payer has indicated that multiple signatures are required for the mandate. As long as every other Billing Request actions have been completed, the payer will receive an email notification containing instructions on how to complete the additional signature. The dual signature flow can only be completed using GoCardless branded pages.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/confirm_payer_details HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "ready_to_fulfil",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": null
"metadata": null,
"links": {
"customer": "CU123",
"customer_bank_account": "BA123",
"creditor": "CR123",
"mandate_request": "MRQ123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "completed"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "completed"
},
{
"type": "confirm_payer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_customer_details",
"collect_bank_account"
],
"status": "completed"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_bank_account": {
"id": "BA123",
"created_at": "2022-11-01T16:30:37.969Z",
"account_number_ending": "11",
"account_holder_name": "HOME LOAN ACCOUNT",
"account_type": null,
"bank_name": "BARCLAYS BANK PLC",
"currency": "GBP",
"country_code": "GB",
"metadata": {},
"enabled": true,
"links": {
"customer": "CU123"
},
"branch_code_ending": "00"
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->confirmPayerDetails("BR123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.confirm_payer_details("BR123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.confirm_payer_details("BR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().confirmPayerDetails("BR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.confirmPayerDetails("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequests.ConfirmPayerDetailsAsync("BR123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
BillingRequestConfirmPayerDetailsParams := gocardless.BillingRequestConfirmPayerDetailsParams{}
billingRequest, err := client.BillingRequests.ConfirmPayerDetails(context, "BR123", BillingRequestConfirmPayerDetailsParams)
}
Fulfil a Billing Request
If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment.
Relative endpoint: POST /billing_requests/BRQ123/actions/fulfil
Parameters
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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/fulfil HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "fulfilled",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {
"mandate": "MD123"
}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {
"payment": "PM123"
}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.374Z",
"address_line1": "1 Somewhere Lane",
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->fulfil("BR123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.fulfil("BR123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.fulfil("BR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().fulfil("BR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.fulfil("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequests.FulfilAsync("BR123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestFulfilParams := gocardless.BillingRequestFulfilParams{}
billingRequest, err := client.BillingRequests.Fulfil(context, "BR123", billingRequestFulfilParams)
}
Cancel a Billing Request
Immediately cancels a billing request, causing all billing request flows to expire.
Relative endpoint: POST /billing_requests/BRQ123/actions/cancel
Parameters
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.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/cancel HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "cancelled",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.374Z",
"address_line1": "1 Somewhere Lane",
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->cancel("BR123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.cancel("BR123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.cancel("BR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().cancel("BR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.cancel("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequests.CancelAsync("BR123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestCancelParams := gocardless.BillingRequestCancelParams{}
billingRequest, err := client.BillingRequests.Fulfil(context, "BR123", billingRequestCancelParams)
}
List Billing Requests
Returns a cursor-paginated list of your billing requests.
Relative endpoint: GET /billing_requests
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at - Fixed timestamp, recording when this resource was created.
customer
- ID of a customer. If specified, this endpoint will return all requests for the given customer.
limit
- Number of records to return.
status
- One of:
-
pending
: the billing request is pending and can be used -
ready_to_fulfil
: the billing request is ready to fulfil -
fulfilling
: the billing request is currently undergoing fulfilment -
fulfilled
: the billing request has been fulfilled and a payment created -
cancelled
: the billing request has been cancelled and cannot be used
-
GET https://api.gocardless.com/billing_requests HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"billing_requests": [
{
"id": "BRQ123",
"created_at": "2021-03-22T16:23:48.486Z",
"status": "pending",
"mandate_request": null,
"payment_request": {
"description": "£5 Top Up",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123",
"customer_bank_account": "BA123"
}
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->list();
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.list().records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.list
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (BillingRequest billingRequest : client.billingRequests().all().execute()) {
System.out.println(billingRequest.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const billingRequests = await client.billingRequests.list();
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var billingRequestListResponse = gocardless.BillingRequests.All();
foreach (GoCardless.Resources.BillingRequest billingRequest in billingRequestListResponse)
{
Console.WriteLine(billingRequest.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestListParams := gocardless.BillingRequestListParams{}
billingRequestListResult, err := client.BillingRequests.List(context, billingRequestListParams)
for _, billingRequest := range billingRequestListResult.BillingRequests {
fmt.Println(billingRequest.Id)
}
}
Get a single Billing Request
Fetches a billing request
Relative endpoint: GET /billing_requests/BRQ123
GET https://api.gocardless.com/billing_requests/BRQ123 HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [
"email",
"given_name",
"family_name"
],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "pending"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
},
{
"type": "bank_authorisation",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_bank_account"
],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": null,
"family_name": null,
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.374Z",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->get("BR123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.get("BR123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.get("BR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().get("BR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.find("BR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequests.GetAsync("BR123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequest, err := client.BillingRequests.Get(context, "BR123")
}
Notify the customer
Notifies the customer linked to the billing request, asking them to authorise it. Currently, the customer can only be notified by email.
This endpoint is currently supported only for Instant Bank Pay Billing Requests.
Relative endpoint: POST /billing_requests/BRQ123/actions/notify
Parameters
notification_
type -
required Currently, can only be
email
. redirect_
uri - URL that the payer can be redirected to after authorising the payment.
POST https://api.gocardless.com/billing_requests/BRQ123/actions/notify HTTP/1.1
Content-Type: application/json
{
"data": {
"notification_type": "email",
"redirect_uri": "https://my-company.com"
}
}
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [
"email",
"given_name",
"family_name"
],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "pending"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
},
{
"type": "bank_authorisation",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_bank_account"
],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.374Z",
"address_line1": "1 Somewhere Lane",
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequests()->notify("BR123", [
"params" => [
"notification_type" => "email",
"redirect_uri" => "https://my-company.com"
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_requests.notify("BR123", params={
notification_type: "email",
redirect_uri: "https://my-company.com",
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_requests.notify("BR123", {
params: {
notification_type: "email",
redirect_uri: "https://my-company.com",
}
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequests().notify("BR123")
.withNotificationType("email")
.withRedirectUri("https://my-company.com")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequests.notify("BR123", {
notification_type: "email",
redirect_uri: "https://my-company.com",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequests.NotifyAsync("BR123",
new BillingRequestNotifyRequest
{
NotificationType = "email",
RedirectUri = "https://my-company.com",
});
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestNotifyParams := gocardless.BillingRequestNotifyParams{
NotificationType: "email",
RedirectUri: "https://my-company.com",
}
billingRequest, err := client.BillingRequests.Fulfil(context, "BR123", billingRequestNotifyParams)
}
Trigger fallback
Triggers a fallback from the open-banking flow to direct debit. Note, the billing request must have fallback enabled.
Relative endpoint: POST /billing_requests/BRQ123/actions/fallback
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.
Parameters
POST https://api.gocardless.com/billing_requests/BRQ123/actions/fallback HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "bacs",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [
"email",
"given_name",
"family_name"
],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.238Z",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
}
},
"fallback_enabled": true,
"fallback_occurred": true
}
}
Change currency
This will allow for the updating of the currency and subsequently the scheme if needed for a Billing Request. This will only be available for mandate only flows which do not have the lock_currency flag set to true on the Billing Request Flow. It will also not support any request which has a payments request.
Relative endpoint: POST /billing_requests/BRQ123/actions/choose_currency
Parameters
currency
- required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
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.
Select institution for a Billing Request
Creates an Institution object and attaches it to the Billing Request
Relative endpoint: POST /billing_requests/BRQ123/actions/select_institution
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.
Parameters
country_
code - required ISO 3166-1 alpha-2 code. The country code of the institution.
institution
- required The unique identifier for this institution
POST https://api.gocardless.com/billing_requests/BRQ123/actions/select_institution HTTP/1.1
Content-Type: application/json
{
"data": {
"institution": "monzo",
"country_code": "GB"
}
}
HTTP/1.1 200
Content-Type: application/json
{
"billing_requests": {
"id": "BRQ123",
"created_at": "2021-03-22T12:20:04.397Z",
"status": "pending",
"mandate_request": {
"currency": "GBP",
"scheme": "bacs",
"links": {}
},
"payment_request": {
"description": "First Payment",
"currency": "GBP",
"amount": 500,
"scheme": "faster_payments",
"links": {}
},
"metadata": null,
"links": {
"customer": "CU123",
"customer_billing_detail": "CBD123"
},
"creditor_name": "Mr Creditor",
"actions": [
{
"type": "choose_currency",
"required": true,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_customer_details",
"required": true,
"completes_actions": [],
"requires_actions": [
"choose_currency"
],
"status": "pending",
"collect_customer_details": {
"incomplete_fields": {
"customer": [
"email",
"given_name",
"family_name"
],
"customer_billing_detail": [
"address_line1",
"city",
"postal_code",
"country_code"
]
}
}
},
{
"type": "select_institution",
"required": false,
"completes_actions": [],
"requires_actions": [],
"status": "completed"
},
{
"type": "collect_bank_account",
"required": true,
"completes_actions": [
"choose_currency"
],
"requires_actions": [],
"status": "pending"
},
{
"type": "bank_authorisation",
"required": true,
"completes_actions": [],
"requires_actions": [
"collect_bank_account"
],
"status": "pending"
}
],
"resources": {
"customer": {
"id": "CU123",
"created_at": "2021-03-22T12:20:04.238Z",
"email": null,
"given_name": "Alice",
"family_name": "Smith",
"company_name": null,
"language": "en",
"phone_number": null,
"metadata": {}
},
"customer_billing_detail": {
"id": "CBD123",
"created_at": "2021-03-22T12:20:04.374Z",
"address_line1": "1 Somewhere Lane",
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"swedish_identity_number": null,
"danish_identity_number": null
},
"institution": {
"id": "monzo",
"name": "Monzo",
"icon_url": "https://images.example.com/image/332bb781-3cc2-4f3e-ae79-1aba09fac991?size",
"roles": ["institutions_list", "heartbeat", "read_refund_account", "read_debtor_account"],
"country_code": "GB"
}
}
}
}
Billing Request Flows
Billing Request Flows can be created to enable a payer to authorise a payment created for a scheme with strong payer authorisation (such as open banking single payments).
Properties
id
- Unique identifier, beginning with “BRF”.
authorisation_
url - URL for a GC-controlled flow which will allow the payer to fulfil the billing request
auto_
fulfil - (Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.
created_
at - Timestamp when the flow was created
customer_
details_ captured - Identifies whether a Billing Request belongs to a specific customer
exit_
uri - URL that the payer can be taken to if there isn’t a way to progress ahead in flow.
expires_
at - Timestamp when the flow will expire. Each flow currently lasts for 7 days.
language
- Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.
lock_
bank_ account - If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.
You can only lock bank account if these have already been completed as a part of the billing request.
lock_
currency - If true, the payer will not be able to change their currency/scheme manually within the flow. Note that this only applies to the mandate only flows - currency/scheme can never be changed when there is a specified subscription or payment.
lock_
customer_ details - If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.
You can only lock customer details if these have already been completed as a part of the billing request.
prefilled_
bank_ account [account_ type] - Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
prefilled_
customer [address_ line1] - The first line of the customer’s address.
prefilled_
customer [address_ line2] - The second line of the customer’s address.
prefilled_
customer [address_ line3] - The third line of the customer’s address.
prefilled_
customer [city] - The city of the customer’s address.
prefilled_
customer [company_ name] - Customer’s company name. Company name should only be provided if
given_name
andfamily_name
are null. prefilled_
customer [country_ code] - ISO 3166-1 alpha-2 code.
prefilled_
customer [danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer.
prefilled_
customer [email] - Customer’s email address.
prefilled_
customer [family_ name] - Customer’s surname.
prefilled_
customer [given_ name] - Customer’s first name.
prefilled_
customer [postal_ code] - The customer’s postal code.
prefilled_
customer [region] - The customer’s address region, county or department.
prefilled_
customer [swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.
redirect_
uri - URL that the payer can be redirected to after completing the request flow.
session_
token - Session token populated when responding to the initialise action
show_
redirect_ buttons - If true, the payer will be able to see redirect action buttons on Thank You page. These action buttons will provide a way to connect back to the billing request flow app if opened within a mobile app. For successful flow, the button will take the payer back the billing request flow where they will see the success screen. For failure, button will take the payer to url being provided against exit_uri field.
show_
success_ redirect_ button - If true, the payer will be able to see a redirect action button on the Success page. This action button will provide a way to redirect the payer to the given redirect_uri. This functionality is helpful when merchants do not want payers to be automatically redirected or on Android devices, where automatic redirections are not possible.
skip_
success_ screen - If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.
links
[billing_ request] - ID of the billing request against which this flow was created.
Create a Billing Request Flow
Creates a new billing request flow.
Relative endpoint: POST /billing_request_flows
Parameters
auto_
fulfil - (Experimental feature) Fulfil the Billing Request on completion of the flow (true by default). Disabling the auto_fulfil is not allowed currently.
customer_
details_ captured - Identifies whether a Billing Request belongs to a specific customer
exit_
uri - URL that the payer can be taken to if there isn’t a way to progress ahead in flow.
language
- Sets the default language of the Billing Request Flow and the customer. ISO 639-1 code.
lock_
bank_ account - If true, the payer will not be able to change their bank account within the flow. If the bank_account details are collected as part of bank_authorisation then GC will set this value to true mid flow.
You can only lock bank account if these have already been completed as a part of the billing request.
lock_
currency - If true, the payer will not be able to change their currency/scheme manually within the flow. Note that this only applies to the mandate only flows - currency/scheme can never be changed when there is a specified subscription or payment.
lock_
customer_ details - If true, the payer will not be able to edit their customer details within the flow. If the customer details are collected as part of bank_authorisation then GC will set this value to true mid flow.
You can only lock customer details if these have already been completed as a part of the billing request.
prefilled_
bank_ account [account_ type] - Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
prefilled_
customer [address_ line1] - The first line of the customer’s address.
prefilled_
customer [address_ line2] - The second line of the customer’s address.
prefilled_
customer [address_ line3] - The third line of the customer’s address.
prefilled_
customer [city] - The city of the customer’s address.
prefilled_
customer [company_ name] - Customer’s company name. Company name should only be provided if
given_name
andfamily_name
are null. prefilled_
customer [country_ code] - ISO 3166-1 alpha-2 code.
prefilled_
customer [danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer.
prefilled_
customer [email] - Customer’s email address.
prefilled_
customer [family_ name] - Customer’s surname.
prefilled_
customer [given_ name] - Customer’s first name.
prefilled_
customer [postal_ code] - The customer’s postal code.
prefilled_
customer [region] - The customer’s address region, county or department.
prefilled_
customer [swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.
redirect_
uri - URL that the payer can be redirected to after completing the request flow.
show_
redirect_ buttons - If true, the payer will be able to see redirect action buttons on Thank You page. These action buttons will provide a way to connect back to the billing request flow app if opened within a mobile app. For successful flow, the button will take the payer back the billing request flow where they will see the success screen. For failure, button will take the payer to url being provided against exit_uri field.
show_
success_ redirect_ button - If true, the payer will be able to see a redirect action button on the Success page. This action button will provide a way to redirect the payer to the given redirect_uri. This functionality is helpful when merchants do not want payers to be automatically redirected or on Android devices, where automatic redirections are not possible.
skip_
success_ screen - If true, the payer will not be redirected to the success screen after completing the flow. A redirect_uri needs to be provided for this parameter to be taken into account.
links
[billing_ request] - required ID of the billing request against which this flow was created.
POST https://api.gocardless.com/billing_request_flows HTTP/1.1
Content-Type: application/json
{
"billing_request_flows": {
"redirect_uri": "https://my-company.com/landing",
"exit_uri": "https://my-company.com/exit",
"prefilled_customer": {
"given_name": "Frank",
"family_name": "Osborne",
"email": "frank.osborne@acmeplc.com"
},
"links": {
"billing_request": "BRQ123"
}
}
}
HTTP/1.1 201 Created
Location: /billing_request_flows/BRF123456
Content-Type: application/json
{
"billing_request_flows": {
"id": "BRF123456",
"auto_fulfil": true,
"redirect_uri": "https://my-company.com/landing",
"exit_uri": "https://my-company.com/exit",
"authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=BRF123456",
"lock_customer_details": false,
"lock_currency": false,
"lock_bank_account": false,
"skip_success_screen": false,
"session_token": null,
"expires_at": "2021-07-30T16:25:16.982Z",
"created_at": "2021-07-23T16:25:16.983Z",
"links": {
"billing_request": "BRQ123"
},
"show_redirect_buttons": false,
"show_success_redirect_button": false,
"customer_details_captured": false,
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequestFlows()->create([
"params" => [
"redirect_uri" => "https://my-company.com/landing",
"exit_uri" => "https://my-company.com/exit",
"prefilled_customer" => [
"given_name" => "Frank",
"family_name" => "Osborne",
"email" => "frank.osborne@acmeplc.com"
],
"links" => [
"billing_request" => "BRQ123"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_request_flows.create(params={
"redirect_uri": "https://my-company.com/landing",
"exit_uri": "https://my-company.com/exit",
"prefilled_customer": {
"given_name": "Frank",
"family_name": "Osborne",
"email": "frank.osborne@acmeplc.com"
},
"links": {
"billing_request": "BRQ123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_request_flows.create(
params: {
redirect_uri: "https://my-company.com/landing",
exit_uri: "https://my-company.com/exit",
prefilled_customer: {
given_name: "Frank",
family_name: "Osborne",
email: "frank.osborne@acmeplc.com"
},
links: {
billing_request: "BRQ123",
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
BillingRequestFlow billingRequestFlow = client.billingRequestFlows().create()
.withRedirectUri("https://my-company.com/landing")
.withExitUri("https://my-company.com/exit")
.withPrefilledCustomerGivenName("Frank")
.withPrefilledCustomerFamilyName("Osborne")
.withPrefilledCustomerEmail("frank.osborne@acmeplc.com")
.withLinksBillingRequest("BRQ123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const billingRequestFlow = await client.billingRequestFlows.create({
redirect_uri: "https://my-company.com/landing",
exit_uri: "https://my-company.com/exit",
prefilled_customer: {
given_name: "Frank",
family_name: "Osborne",
email: "frank.osborne@acmeplc.com"
},
links: {
billing_request: "BRQ123",
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var prefilledCustomer = new GoCardless.Services.RedirectFlowCreateRequest.RedirectFlowPrefilledCustomer()
{
AddressLine1 = "338 Goswell Road",
Email = "api@gocardless.com",
GivenName = "Bobby",
FamilyName = "Tables"
};
var resp = await gocardless.BillingRequestFlows.CreateAsync(
new GoCardless.Services.BillingRequestFlowCreateRequest()
{
RedirectUri = "https://my-company.com/landing",
ExitUri = "https://my-company.com/exit",
PrefilledCustomer = prefilledCustomer,
Links = new gocardless.BillingRequestFlowCreateRequest.BillingRequestFlowLinks
{
BillingRequest = "BRQ123",
},
}
);
GoCardless.Resources.BillingRequestFlow billingRequestFlow = resp.BillingRequestFlow;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestFlowCreateParams := gocardless.BillingRequestFlowCreateParams{
RedirectUri: "https://my-company.com/landing",
ExitUri: "https://my-company.com/exit",
PrefilledCustomer: &gocardless.RedirectFlowCreateParamsPrefilledCustomer{
AddressLine1: "338-346 Goswell Road",
City: "London",
GivenName: "Tim",
FamilyName: "Rogers",
Email: "tim@gocardless.com",
PostalCode: "EC1V 7LQ",
},
Links: gocardless.BillingRequestFlowCreateParamsLinks{
BillingRequest: "BR123",
},
}
billingRequestFlow, err := client.BillingRequestFlows.Create(context, billingRequestFlowCreateParams)
}
Initialise a Billing Request Flow
Returns the flow having generated a fresh session token which can be used to power integrations that manipulate the flow.
Relative endpoint: POST /billing_request_flows/BRF123/actions/initialise
Parameters
POST https://api.gocardless.com/billing_request_flows/BRF123/actions/initialise HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_request_flows":{
"id":"BRF123",
"auto_fulfil":true,
"redirect_uri":null,
"exit_uri":null,
"authorisation_url":"https://pay-sandbox.gocardless.com/billing/static/flow?id=BRF123",
"lock_customer_details":false,
"lock_bank_account":false,
"lock_currency": false,
"skip_success_screen": false,
"session_token":"sesh_sandbox_DHTMvJAUajbd9KTCoXNFcTv4RSoWdMbauhnalxiqwbdsb",
"expires_at":"2021-09-01T08:45:38.016Z",
"created_at":"2021-08-25T08:45:38.017Z",
"links":{
"billing_request":"BRQ123"
},
"show_redirect_buttons": false,
"show_success_redirect_button": false,
"customer_details_captured": false,
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequestFlows()->initialise("BRF123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_request_flows.initialise("BRF123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_request_flows.initialise("BRF123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequestFlows().initialise("BRF123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequestFlows.initialise("BRF123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequestFlows.InitialiseAsync("BRF123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestFlowInitialiseParams := gocardless.BillingRequestFlowInitialiseParams{}
billingRequestFlow, err := client.BillingRequestFlows.Initialise(context, "BRF123", billingRequestFlowInitialiseParams)
}
Billing Request Templates
Billing Request Templates are reusable templates that result in numerous Billing Requests with similar attributes. They provide a no-code solution for generating various types of multi-user payment links.
Each template includes a reusable URL that can be embedded in a website or shared with customers via email. Every time the URL is opened, it generates a new Billing Request.
Billing Request Templates overcome the key limitation of the Billing Request: a Billing Request cannot be shared among multiple users because it is intended for single-use and is designed to cater to the unique needs of individual customers.
Properties
id
- Unique identifier, beginning with “BRT”.
authorisation_
url - Permanent URL that customers can visit to allow them to complete a flow based on this template, before being returned to the
redirect_uri
. created_
at - Fixed timestamp, recording when this resource was created.
mandate_
request_ currency - ISO 4217 currency code.
mandate_
request_ description - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_
request_ metadata - Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
mandate_
request_ scheme - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_
request_ verify - Verification preference for the mandate. One of:
-
minimum
: only verify if absolutely required, such as when part of scheme rules -
recommended
: in addition tominimum
, use the GoCardless payment intelligence solution to decide if a payer should be verified -
when_available
: if verification mechanisms are available, use them -
always
: aswhen_available
, but fail to create the Billing Request if a mechanism isn’t available
-
By default, all Billing Requests use the recommended
verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended
behaves like minimum
.
If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum
verification preference.
See Billing Requests: Creating Verified Mandates for more information.
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.
name
- Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.
payment_
request_ amount - Amount in full.
payment_
request_ currency -
ISO 4217 currency code.
GBP
andEUR
supported;GBP
with your customers in the UK and forEUR
with your customers in supported Eurozone countries only. payment_
request_ description - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_
request_ metadata - Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
payment_
request_ scheme - (Optional) A scheme used for Open Banking payments. Currently
faster_payments
is supported in the UK (GBP) andsepa_credit_transfer
andsepa_instant_credit_transfer
are supported in supported Eurozone countries (EUR). For Eurozone countries,sepa_credit_transfer
is used as the default. Please be aware thatsepa_instant_credit_transfer
may incur an additional fee for your customer. redirect_
uri - URL that the payer can be redirected to after completing the request flow.
updated_
at - Dynamic timestamp recording when this resource was last updated.
List Billing Request Templates
Returns a cursor-paginated list of your Billing Request Templates.
Relative endpoint: GET /billing_request_templates
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
limit
- Number of records to return.
GET https://api.gocardless.com/billing_request_templates HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"billing_request_templates": [
{
"id": "BRT123",
"name": "12 Month Gold Plan",
"mandate_request_currency": "GBP",
"mandate_request_scheme": null,
"mandate_request_verify": null,
"mandate_request_metadata": null,
"payment_request_description": "One-time joining fee",
"mandate_request_description": "Recurring fee",
"payment_request_amount": "69.99",
"payment_request_currency": "GBP",
"payment_request_scheme": null,
"payment_request_metadata": null,
"redirect_uri": "https://my-company.com/landing",
"authorisation_url": "https://pay.gocardless.com/BRT123",
"metadata": {
"checkout-flow": "primary"
},
"created_at": "2021-07-27T17:10:33.784Z",
"updated_at": "2021-07-27T17:10:33.784Z"
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequestTemplates()->list();
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_request_templates.list().records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_request_templates.list
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (BillingRequestTemplate billingRequestTemplate : client.billingRequestTemplates().all().execute()) {
System.out.println(billingRequestTemplate.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const billingRequestTemplates = await client.billingRequestTemplates.list();
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var billingRequestTemplateListResponse = gocardless.BillingRequestTemplates.All();
foreach (GoCardless.Resources.BillingRequestTemplate billingRequestTemplate in billingRequestTemplateListResponse)
{
Console.WriteLine(billingRequestTemplate.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestTemplateListParams := gocardless.BillingRequestTemplateListParams{}
billingRequestTemplateListResult, err := client.BillingRequestTemplates.List(context, billingRequestTemplateListParams)
for _, billingRequestTemplate := range billingRequestTemplateListResult.BillingRequestTemplates {
fmt.Println(billingRequestTemplate.Id)
}
}
Get a single Billing Request Template
Fetches a Billing Request Template
Relative endpoint: GET /billing_request_templates/BRT123
GET https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"billing_request_templates": {
"id": "BRT123",
"name": "12 Month Gold Plan",
"mandate_request_currency": "GBP",
"mandate_request_scheme": null,
"mandate_request_verify": null,
"mandate_request_metadata": null,
"payment_request_description": "One-time joining fee",
"mandate_request_description": "Recurring fee",
"payment_request_amount": "69.99",
"payment_request_currency": "GBP",
"payment_request_scheme": null,
"payment_request_metadata": null,
"redirect_uri": "https://my-company.com/landing",
"authorisation_url": "https://pay.gocardless.com/BRT123",
"metadata": {
"checkout-flow": "primary"
},
"created_at": "2021-07-27T17:10:33.784Z",
"updated_at": "2021-07-27T17:10:33.784Z"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequestTemplates()->get("BRT123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_request_templates.get("BRT123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_request_templates.get("BRT123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.billingRequestTemplates().get("BRT123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const resp = await client.billingRequestTemplates.find("BRT123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequestTemplates.GetAsync("BRT123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestTemplate, err := client.BillingRequestTemplates.Get(context, "BRT123")
}
Create a Billing Request Template
Relative endpoint: POST /billing_request_templates
Parameters
mandate_
request_ currency - ISO 4217 currency code.
mandate_
request_ description - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_
request_ metadata - Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
mandate_
request_ scheme - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_
request_ verify - Verification preference for the mandate. One of:
-
minimum
: only verify if absolutely required, such as when part of scheme rules -
recommended
: in addition tominimum
, use the GoCardless payment intelligence solution to decide if a payer should be verified -
when_available
: if verification mechanisms are available, use them -
always
: aswhen_available
, but fail to create the Billing Request if a mechanism isn’t available
-
By default, all Billing Requests use the recommended
verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended
behaves like minimum
.
If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum
verification preference.
See Billing Requests: Creating Verified Mandates for more information.
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.
name
- Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.
payment_
request_ amount - Amount in full.
payment_
request_ currency -
ISO 4217 currency code.
GBP
andEUR
supported;GBP
with your customers in the UK and forEUR
with your customers in supported Eurozone countries only. payment_
request_ description - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_
request_ metadata - Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
payment_
request_ scheme - (Optional) A scheme used for Open Banking payments. Currently
faster_payments
is supported in the UK (GBP) andsepa_credit_transfer
andsepa_instant_credit_transfer
are supported in supported Eurozone countries (EUR). For Eurozone countries,sepa_credit_transfer
is used as the default. Please be aware thatsepa_instant_credit_transfer
may incur an additional fee for your customer. redirect_
uri - URL that the payer can be redirected to after completing the request flow.
links
[creditor] - ID of the associated creditor. Only required if your account manages multiple creditors.
POST https://api.gocardless.com/billing_request_templates HTTP/1.1
Content-Type: application/json
{
"billing_request_templates": {
"name": "12 Month Gold Plan",
"payment_request_description": "One-time joining fee",
"mandate_request_description": "Recurring fee",
"payment_request_currency": "GBP",
"payment_request_amount": "69.99",
"mandate_request_currency": "GBP",
"redirect_uri": "https://my-company.com/landing",
"metadata": {
"checkout-flow": "primary"
}
}
}
HTTP/1.1 201 Created
Location: /billing_request_templates/BRT123
Content-Type: application/json
{
"billing_request_templates": {
"id": "BRT123",
"name": "12 Month Gold Plan",
"mandate_request_currency": "GBP",
"mandate_request_scheme": null,
"mandate_request_verify": null,
"mandate_request_metadata": null,
"payment_request_description": "One-time joining fee",
"mandate_request_description": "Recurring fee",
"payment_request_amount": "69.99",
"payment_request_currency": "GBP",
"payment_request_scheme": null,
"payment_request_metadata": null,
"redirect_uri": "https://my-company.com/landing",
"authorisation_url": "https://pay.gocardless.com/BRT123",
"metadata": {
"checkout-flow": "primary"
},
"created_at": "2021-07-27T17:10:33.784Z",
"updated_at": "2021-07-27T17:10:33.784Z"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequestTemplates()->create([
"params" => [
"name" => "12 Month Gold Plan",
"payment_request_description" => "One-time joining fee",
"mandate_request_description" => "Recurring fee",
"payment_request_currency" => "GBP",
"payment_request_amount" => "69.99",
"mandate_request_currency" => "GBP",
"redirect_uri" => "https://my-company.com/landing",
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_request_templates.create(params={
"name": "12 Month Gold Plan",
"payment_request_description": "One-time joining fee",
"mandate_request_description": "Recurring fee",
"payment_request_currency": "GBP",
"payment_request_amount": "69.99",
"mandate_request_currency": "GBP",
"redirect_uri": "https://my-company.com/landing",
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_request_templates.create(
params: {
name: "12 Month Gold Plan",
payment_request_description: "One-time joining fee",
mandate_request_description: "Recurring fee",
payment_request_currency: "GBP",
payment_request_amount: "69.99",
mandate_request_currency: "GBP",
redirect_uri: "https://my-company.com/landing",
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().create()
.withPaymentRequestDescription("One-time joining fee")
.withPaymentRequestCurrency("GBP")
.withPaymentRequestAmount("69.99")
.withMandateRequestCurrency("GBP")
.withRedirectUri("https://my-company.com/landing")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const billingRequestTemplate = await client.billingRequestTemplates.create({
name: "12 Month Gold Plan",
payment_request_description: "One-time joining fee",
mandate_request_description: "Recurring fee",
payment_request_currency: "GBP",
payment_request_amount: "69.99",
mandate_request_currency: "GBP",
redirect_uri: "https://my-company.com/landing",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequestTemplates.CreateAsync(
new GoCardless.Services.BillingRequestTemplateCreateRequest()
{
PaymentRequestDescription = "One-time joining fee",
PaymentRequestCurrency = "GBP",
PaymentRequestAmount = 6999,
MandateRequestCurrency = "GBP",
RedirectUri = "https://my-company.com/landing",
}
);
GoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestTemplateCreateParams := gocardless.BillingRequestTemplateCreateParams{
Name: "12 Month Gold Plan",
PaymentRequestDescription: "One-time joining fee",
PaymentRequestCurrency: "GBP",
PaymentRequestAmount: 6999,
MandateRequestCurrency: "GBP",
RedirectUri: "https://my-company.com/landing",
}
billingRequestTemplate, err := client.BillingRequestTemplates.Create(context, billingRequestTemplateCreateParams)
}
Update a Billing Request Template
Updates a Billing Request Template, which will affect all future Billing Requests created by this template.
Relative endpoint: PUT /billing_request_templates/BRQ123
Parameters
mandate_
request_ currency - ISO 4217 currency code.
mandate_
request_ description - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
mandate_
request_ metadata - Key-value store of custom data that will be applied to the mandate created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
mandate_
request_ scheme - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported. Optional for mandate only requests - if left blank, the payer will be able to select the currency/scheme to pay with from a list of your available schemes.
mandate_
request_ verify - Verification preference for the mandate. One of:
-
minimum
: only verify if absolutely required, such as when part of scheme rules -
recommended
: in addition tominimum
, use the GoCardless payment intelligence solution to decide if a payer should be verified -
when_available
: if verification mechanisms are available, use them -
always
: aswhen_available
, but fail to create the Billing Request if a mechanism isn’t available
-
By default, all Billing Requests use the recommended
verification preference. It uses GoCardless payment intelligence solution to determine if a payer is fraudulent or not. The verification mechanism is based on the response and the payer may be asked to verify themselves. If the feature is not available, recommended
behaves like minimum
.
If you never wish to take advantage of our reduced risk products and Verified Mandates as they are released in new schemes, please use the minimum
verification preference.
See Billing Requests: Creating Verified Mandates for more information.
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.
name
- Name for the template. Provides a friendly human name for the template, as it is shown in the dashboard. Must not exceed 255 characters.
payment_
request_ amount - Amount in full.
payment_
request_ currency -
ISO 4217 currency code.
GBP
andEUR
supported;GBP
with your customers in the UK and forEUR
with your customers in supported Eurozone countries only. payment_
request_ description - A human-readable description of the payment and/or mandate. This will be displayed to the payer when authorising the billing request.
payment_
request_ metadata - Key-value store of custom data that will be applied to the payment created when this request is fulfilled. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
payment_
request_ scheme - (Optional) A scheme used for Open Banking payments. Currently
faster_payments
is supported in the UK (GBP) andsepa_credit_transfer
andsepa_instant_credit_transfer
are supported in supported Eurozone countries (EUR). For Eurozone countries,sepa_credit_transfer
is used as the default. Please be aware thatsepa_instant_credit_transfer
may incur an additional fee for your customer. redirect_
uri - URL that the payer can be redirected to after completing the request flow.
PUT https://api.gocardless.com/billing_request_templates/BRT123 HTTP/1.1
Content-Type: application/json
{
"billing_request_templates": {
"name": "12 Month Silver Plan",
"payment_request_amount": "49.99"
}
}
HTTP/1.1 200 OK
Location: /billing_request_templates/BRT123
Content-Type: application/json
{
"billing_request_templates": {
"id": "BRT123",
"name": "12 Month Silver Plan",
"mandate_request_currency": "GBP",
"mandate_request_scheme": null,
"mandate_request_verify": null,
"mandate_request_metadata": null,
"payment_request_description": "One-time joining fee",
"mandate_request_description": "Recurring fee",
"payment_request_amount": "49.99",
"payment_request_currency": "GBP",
"payment_request_scheme": null,
"payment_request_metadata": null,
"redirect_uri": "https://my-company.com/landing",
"authorisation_url": "https://pay.gocardless.com/BRT123",
"metadata": {
"checkout-flow": "primary"
},
"created_at": "2021-07-27T17:10:33.784Z",
"updated_at": "2021-07-30T11:28:11.123Z"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->billingRequestTemplates()->update("BRT123", [
"params" => [
"name" => "12 Month Silver Plan",
"payment_request_amount" => "49.99"
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.billing_request_templates.update("BRT123", params={
"name": "12 Month Silver Plan",
"payment_request_amount": "49.99",
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.billing_request_templates.update("BRT123", params: {
name: "12 Month Silver Plan",
payment_request_amount: "49.99",
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
BillingRequestTemplate billingRequestTemplate = client.billingRequestTemplates().update("BRT123")
.withName("12 Month Silver Plan")
.withPaymentRequestAmount("49.99")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const billingRequestTemplate = await client.billingRequestTemplates.update({
name: "12 Month Silver Plan",
payment_request_amount: "49.99",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.BillingRequestTemplates.UpdateAsync(
"BRT123",
new GoCardless.Services.BillingRequestTemplateUpdateRequest()
{
Name = "12 Month Silver Plan",
PaymentRequestAmount = 4999,
}
);
GoCardless.Resources.BillingRequestTemplate billingRequestTemplate = resp.BillingRequestTemplate;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
billingRequestTemplateUpdateParams := gocardless.BillingRequestTemplateUpdateParams{
Name: "12 Month Silver Plan",
PaymentRequestAmount: 4999,
}
billingRequestTemplate, err := client.BillingRequestTemplates.Update(context, "BRT123", billingRequestTemplateUpdateParams)
}
Institutions
Institutions that are supported when creating Bank Authorisations for a particular country or purpose.
Not all institutions support both Payment Initiation (PIS) and Account Information (AIS) services.
Properties
id
- The unique identifier for this institution
autocompletes_
collect_ bank_ account - Flag to show if selecting this institution in the select_institution action can auto-complete the collect_bank_account action. The bank can return the payer’s bank account details to GoCardless.
country_
code - ISO 3166-1 alpha-2 code. The country code of the institution.
icon_
url - A URL pointing to the icon for this institution
logo_
url - A URL pointing to the logo for this institution
name
- A human readable name for this institution
List Institutions
Returns a list of supported institutions.
Relative endpoint: GET /institutions
Deprecated: This list institutions endpoint is no longer supported. We strongly recommend using the List Institutions For Billing Request instead.
Parameters
country_
code - ISO 3166-1 alpha-2 code. The country code of the institution.
GET https://api.gocardless.com/institutions?country_code=GB HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"institutions": [
{
"id": "monzo",
"name": "Monzo",
"logo_url": "https://assets.gocardless.com/icon",
"icon_url": "https://assets.gocardless.com/icon",
"country_code": "GB"
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->institutions()->list([
"params" => ["country_code" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
@client.institutions.list(params={"country_code": "GB" }).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.institutions.list(params: { country_code: "GB" })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Institution institution = client.institutions().all().withCountryCode("GB").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
// List of all institutions.
const institutions = await client.institutions.list();
// List of institutions for a country code.
const institutions = await client.institutions.list({ countryCode: 'GB'});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
// List of institutions for a country code.
var request = new GoCardless.Services.InstitutionListRequest()
{
CountryCode = "GB",
};
var institutionListResponse = gocardless.Institutions.All(request);
// List of all institutions.
var institutionListResponse = gocardless.Institutions.All();
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
institutionListParams := gocardless.InstitutionListParams{}
institutionListResult, err := client.Institutions().List(context, institutionListParams)
for _, institution := range institutionListResult.Institutions {
fmt.Println(institution.Id)
}
}
List institutions for Billing Request
Returns all institutions valid for a Billing Request.
This endpoint is currently supported only for FasterPayments.
Relative endpoint: GET /billing_requests/BRQ123/institutions
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with the custom payment pages upgrade.
Parameters
country_
code - required ISO 3166-1 alpha-2 code. The country code of the institution.
ids
- ID(s) of the institution(s) to retrieve. More than one ID can be specified using a comma-separated string.
search
- A search substring for retrieving institution(s), based on the institution’s name.
GET https://api.gocardless.com/billing_requests/BRQ123/institutions?country_code=GB HTTP/1.1
HTTP/1.1 200
Content-Type: application/json
{
"institutions": [
{
"id": "BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1",
"name": "Bank of Scotland Business",
"logo_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
"icon_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
"country_code": "GB",
"autocompletes_collect_bank_account": true
},
{
"id": "BANK_OF_SCOTLAND_BOFSGBS1",
"name": "Bank of Scotland Personal",
"logo_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
"icon_url": "https://cdn-logos.gocardless.com/ais/BANK_OF_SCOTLAND_BUSINESS_BOFSGBS1.png",
"country_code": "GB",
"autocompletes_collect_bank_account": true
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->institutions()->listForBillingRequest("BR123", [
"params" => ["country_code" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
@client.institutions.listForBillingRequest("BR123", params={
"country_code": "GB"
}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.institutions.listForBillingRequest("BR123", {
params: { country_code: "GB" }
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.institutions().listForBillingRequest("BR123").withCountryCode("GB").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const institutions = await client.institutions.list_for_billing_request("BR123", { countryCode: 'GB'});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.InstitutionListForBillingRequestRequest()
{
CountryCode = "GB",
};
var institutionListResponse = await gocardless.Institutions.ListForBillingRequestAsync("BR123", request);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
institutionListForBillingRequestParams := gocardless.InstitutionListForBillingRequestParams{
CountryCode: "GB",
}
institutionListForBillingRequestResult, err := client.Institutions().ListForBillingRequest(context, "BR123", institutionListForBillingRequestParams)
for _, institution := range institutionListForBillingRequestResult.Institutions {
fmt.Println(institution.Id)
}
}
Blocks
Blocks are created to prevent certain customer details from being used when creating mandates.
The details used to create blocks can be exact matches, like a bank account or an email, or a more generic match such as an email domain or bank name. Please be careful when creating blocks for more generic matches as this may block legitimate payers from using your service.
New block types may be added over time.
A block is in essence a simple rule that is used to match against details in a newly created mandate. If there is a successful match then the mandate is transitioned to a “blocked” state.
Please note:
- Payments and subscriptions cannot be created against a mandate in blocked state.
- A mandate can never be transitioned out of the blocked state.
The one exception to this is when blocking a ‘bank_name’. This block will prevent bank accounts from being created for banks that match the given name. To ensure we match bank names correctly an existing bank account must be used when creating this block. Please be aware that we cannot always match a bank account to a given bank name.
This API is currently only available for GoCardless Protect+ integrators - please get in touch if you would like to use this API.
Properties
id
- Unique identifier, beginning with “BLC”.
active
- Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
block_
type - Type of entity we will seek to match against when blocking the mandate. This can currently be one of ‘email’, ‘email_domain’, ‘bank_account’, or ‘bank_name’.
created_
at - Fixed timestamp, recording when this resource was created.
reason_
description - This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
reason_
type - The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
resource_
reference - This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.
updated_
at - Fixed timestamp, recording when this resource was updated.
Create a block
Creates a new Block of a given type. By default it will be active.
Relative endpoint: POST /blocks
Note: Block will be enabled if you try to create a block that already exists and is disabled.
Parameters
active
- Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
block_
type - Type of entity we will seek to match against when blocking the mandate. This can currently be one of ‘email’, ‘email_domain’, ‘bank_account’, or ‘bank_name’.
reason_
description - This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
reason_
type - The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
resource_
reference - This field is a reference to the value you wish to block. This may be the raw value (in the case of emails or email domains) or the ID of the resource (in the case of bank accounts and bank names). This means in order to block a specific bank account (even if you wish to block generically by name) it must already have been created as a resource.
POST https://api.gocardless.com/blocks HTTP/1.1
Content-Type: application/json
{
"blocks": {
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com"
}
}
HTTP/1.1 201 Created
Location: /block/BLC123
Content-Type: application/json
{
"blocks": {
"id": "BLC123",
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
}
}
POST https://api.gocardless.com/blocks HTTP/1.1
Content-Type: application/json
{
"blocks": {
"block_type": "bank_account",
"reason_type": "no_intent_to_pay",
"resource_reference": "BA123"
}
}
HTTP/1.1 201 Created
Location: /block/BLC456
Content-Type: application/json
{
"blocks": {
"id": "BLC456",
"block_type": "bank_account",
"reason_type": "no_intent_to_pay",
"resource_reference": "BA123",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$block = $client->blocks()->create([
"params" => [
"block_type" => "email",
"reason_type" => "no_intent_to_pay",
"resource_reference" => "example@example.com",
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
block = client.blocks.create(
params={
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com"
}
)
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
block = @client.blocks.create(
params: {
block_type: "email",
reason_type: "no_intent_to_pay",
resource_reference: "example@example.com"
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Block block = client.blocks().create()
.withBlockType(Block.BlockType.EMAIL)
.withReasonType(Block.ReasonType.NO_INTENT_TO_PAY)
.withResourceReference("example@example.com")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const block = await client.blocks.create({
block_type: Types.BlockBlockType.Email,
resource_reference: 'CU123',
reason_type: Types.BlockReasonType.NoIntentToPay,
})
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.Blocks.CreateAsync(
new GoCardless.Services.BlockCreateRequest()
{
BlockType = GoCardless.Services.BlockCreateRequest.BlockBlockType.Email,
ReasonType = GoCardless.Services.BlockCreateRequest.BlockReasonType.NoIntentToPay,
ResourceReference = "example@example.com"
}
);
GoCardless.Resources.Block block = resp.Block;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
blockCreateParams := gocardless.BlockCreateParams{
BlockType: "email",
ReasonType: "no_intent_to_pay",
ResourceReference: "example@example.com",
}
block, err := client.Blocks.Create(context, blockCreateParams)
}
Get a single block
Retrieves the details of an existing block.
Relative endpoint: GET /blocks/BLC123
GET https://api.gocardless.com/blocks/BLC456 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"blocks": {
"id": "BLC456",
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$block = $client->blocks()->get("BLC456");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
block = client.blocks.get("BLC456")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
block = @client.blocks.get("BLC456")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Block block = client.blocks().get("BLC456").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const block = await client.blocks.find("BLC456");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.Blocks.GetAsync("BLC456");
GoCardless.Resources.Block block = resp.Block;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
block, err := client.Blocks.Get(context, "BLC456")
}
List multiple blocks
Returns a cursor-paginated list of your blocks.
Relative endpoint: GET /blocks
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
block
- ID of a Block.
block_
type - Type of entity we will seek to match against when blocking the mandate. This can currently be one of ‘email’, ‘email_domain’, ‘bank_account’, or ‘bank_name’.
created_
at - Fixed timestamp, recording when this resource was created.
limit
- Number of records to return.
reason_
type - The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
updated_
at - Fixed timestamp, recording when this resource was updated.
GET https://api.gocardless.com/blocks HTTP/1.1
HTTP/1.1 200 OK
Location: /blocks
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"blocks": [
{
"id": "BLC123",
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
},
{
"id": "BLC456",
"block_type": "email_domain",
"reason_type": "identity_fraud",
"resource_reference": "example.com",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
foreach ($client->blocks()->all() as $record) {
echo $record->id;
echo $record->block_type;
}
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
for block in client.blocks.all():
print(block.id)
print(block.block_type)
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.blocks.all.each do |block|
puts block.id
puts block.block_type
end
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Block block : client.blocks().all().execute()) {
System.out.println(block.getId());
System.out.println(block.getBlockType());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
for await (const block of client.blocks.all({})) {
console.log(block.id);
console.log(block.block_type);
}
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
foreach (GoCardless.Resources.Block block in gocardless.Blocks.All())
{
Console.WriteLine(block.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
blockListParams := gocardless.BlockListParams{}
blockListResult, err := client.Blocks.List(context, blockListParams)
for _, block := range blockListResult.Blocks {
fmt.Println(block.Id)
}
Disable a block
Disables a block so that it no longer will prevent mandate creation.
Relative endpoint: POST /blocks/BLC123/actions/disable
POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"blocks": {
"id": "BLC123",
"block_type": "bank_account",
"reason_type": "no_intent_to_pay",
"resource_reference": "BA123",
"active": "false",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T19:26:28.305Z"
}
}
POST https://api.gocardless.com/blocks/BLC123/actions/disable HTTP/1.1
HTTP/1.1 409 Conflict
POST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/disable HTTP/1.1
HTTP/1.1 404 NotFound
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$block = $client->blocks()->disable("BLC123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
block = client.blocks.disable("BLC123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
block = @client.blocks.disable("BLC123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Block block = client.blocks().disable("BLC123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const block = await client.blocks.disable("BLC456");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.Blocks.DisableAsync("BLC123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
block, err := client.Blocks.Disable(context, "BLC123")
}
Enable a block
Enables a previously disabled block so that it will prevent mandate creation
Relative endpoint: POST /blocks/BLC123/actions/enable
POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"blocks": {
"id": "BLC123",
"block_type": "bank_account",
"reason_type": "no_intent_to_pay",
"resource_reference": "BA123",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T19:26:28.305Z"
}
}
POST https://api.gocardless.com/blocks/BLC123/actions/enable HTTP/1.1
HTTP/1.1 409 Conflict
POST https://api.gocardless.com/blocks/MISSING_BLOCK_ID/actions/enable HTTP/1.1
HTTP/1.1 404 NotFound
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$block = $client->blocks()->enable("BLC123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
block = client.blocks.enable("BLC123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
block = @client.blocks.enable("BLC123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Block block = client.blocks().enable("BLC123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const block = await client.blocks.enable("BLC456");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await gocardless.Blocks.EnableAsync("BLC123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
block, err := client.Blocks.Enable(context, "BLC123")
}
Create blocks by reference
Creates new blocks for a given reference. By default blocks will be active. Returns 201 if at least one block was created. Returns 200 if there were no new blocks created.
Relative endpoint: POST /blocks/block_by_ref
Parameters
active
- Shows if the block is active or disabled. Only active blocks will be used when deciding if a mandate should be blocked.
reason_
description - This field is required if the reason_type is other. It should be a description of the reason for why you wish to block this payer and why it does not align with the given reason_types. This is intended to help us improve our knowledge of types of fraud.
reason_
type - The reason you wish to block this payer, can currently be one of ‘identity_fraud’, ‘no_intent_to_pay’, ‘unfair_chargeback’. If the reason isn’t captured by one of the above then ‘other’ can be selected but you must provide a reason description.
reference_
type - Type of entity we will seek to get the associated emails and bank accounts to create blocks from. This can currently be one of ‘customer’ or ‘mandate’.
reference_
value - This field is a reference to the entity you wish to block based on its emails and bank accounts. This may be the ID of a customer or a mandate. This means in order to block by reference the entity must have already been created as a resource.
POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1
Content-Type: application/json
{
"blocks": {
"reference_type": "customer",
"reference_value": "CU123",
"reason_type": "no_intent_to_pay"
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"blocks": [
{
"id": "BLC123",
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
},
{
"id": "BLC456",
"block_type": "bank_account",
"reason_type": "no_intent_to_pay",
"resource_reference": "BA123",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
}
]
}
POST https://api.gocardless.com/blocks/block_by_ref HTTP/1.1
Content-Type: application/json
{
"blocks": {
"reference_type": "customer",
"reference_value": "CU123",
"reason_type": "no_intent_to_pay"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"blocks": [
{
"id": "BLC123",
"block_type": "email",
"reason_type": "no_intent_to_pay",
"resource_reference": "example@example.com",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
},
{
"id": "BLC456",
"block_type": "bank_account",
"reason_type": "no_intent_to_pay",
"resource_reference": "BA123",
"active": "true",
"created_at": "2021-03-25T17:26:28.305Z",
"updated_at": "2021-03-25T17:26:28.305Z"
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$block = $client->blocks()->blockByRef([
"params" => [
"reference_type" => "customer",
"reference_value" => "CU123",
"reason_type" => "no_intent_to_pay",
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
response = client.blocks.block_by_ref(
params={
"reference_type": "customer",
"reference_value": "CU123",
"reason_type": "no_intent_to_pay"
}
)
blocks = response.records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
resp = @client.blocks.block_by_ref(
params: {
reference_type: "customer",
reference_value: "CU123"
reason_type: "no_intent_to_pay",
}
)
blocks = resp.records
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Iterable<Block> iterable = client.blocks().blockByRef()
.withReferenceType("customer")
.withReferenceValue("CU123")
.withReasonType("no_intent_to_pay")
.execute();
List<Block> blocks = Lists.newArrayList(iterable);
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const response = await client.blocks.block_by_ref(
{
reference_type: Types.BlockReferenceType.Customer,
reference_value: 'CU123',
reason_type: Types.BlockReasonType.NoIntentToPay
}
);
const blocks = response.blocks;
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var resp = await client.Blocks.BlockByRefAsync(new BlockBlockByRefRequest() {
ReferenceType = "customer",
ReferenceValue = "CU123",
ReasonType = "no_intent_to_pay",
});
IReadOnlyList < GoCardless.Resources.Block > blocks = resp.Blocks;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
blockBlockByRefParams := gocardless.BlockBlockByRefParams{
ReferenceType: "customer",
ReferenceValue: "CU123",
ReasonType: "no_intent_to_pay",
}
blockBlockByRefResult, err := client.Blocks.BlockByRef(context, blockBlockByRefParams)
for _, block := range blockBlockByRefResult.Blocks {
fmt.Println(block.Id)
}
}
Creditors
Each payment taken through the API is linked to a “creditor”, to whom the payment is then paid out. In most cases your organisation will have a single “creditor”, but the API also supports collecting payments on behalf of others.
Currently, for Anti Money Laundering reasons, any creditors you add must be directly related to your organisation.
Properties
id
- Unique identifier, beginning with “CR”.
address_
line1 - The first line of the creditor’s address.
address_
line2 - The second line of the creditor’s address.
address_
line3 - The third line of the creditor’s address.
bank_
reference_ prefix - Prefix for the bank reference of payouts sent to this creditor. For instance, if
the creditor’s
bank_reference_prefix
wasACME
, the bank reference of a payout sent to that creditor could beACME-8G7Q8
.This prefix is also used for refunds in EUR and GBP.
can_
create_ refunds - Boolean indicating whether the creditor is permitted to create refunds.
city
- The city of the creditor’s address.
country_
code - ISO 3166-1 alpha-2 code.
created_
at - Fixed timestamp, recording when this resource was created.
creditor_
type - The type of business of the creditor. Currently,
individual
,company
,charity
,partnership
, andtrust
are supported. custom_
payment_ pages_ enabled - Boolean value indicating whether creditor has the Custom Payment Pages functionality enabled.
fx_
payout_ currency - ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
logo_
url - URL for the creditor’s logo, which may be shown on their payment pages.
mandate_
imports_ enabled - Boolean value indicating whether creditor has the Mandate Imports functionality enabled.
merchant_
responsible_ for_ notifications - Boolean value indicating whether the organisation is responsible for sending all customer notifications (note this is separate from the functionality described here). If you are a partner app, and this value is true, you should not send notifications on behalf of this organisation.
name
- The creditor’s trading name.
postal_
code - The creditor’s postal code.
region
- The creditor’s address region, county or department.
scheme_
identifiers - An array of the scheme identifiers this creditor can create mandates against.
The support address,
phone_number
andemail
fields are for customers to contact the merchant for support purposes. They must be displayed on the payment page, please see our compliance requirements for more details.Each instance will contain these properties:
-
address_line1
: The first line of the scheme identifier’s support address. -
address_line2
: The second line of the scheme identifier’s support address. -
address_line3
: The third line of the scheme identifier’s support address. -
can_specify_mandate_reference
: Whether a custom reference can be submitted for mandates using this scheme identifier. -
city
: The city of the scheme identifier’s support address. -
country_code
: ISO 3166-1 alpha-2 code. -
created_at
: Fixed timestamp, recording when this resource was created. -
currency
: The currency of the scheme identifier. -
email
: Scheme identifier’s support email address. -
id
: Unique identifier, usually beginning with “SU”. -
minimum_advance_notice
: The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.
-
name
: The name which appears on customers’ bank statements. This should usually be the merchant’s trading name. -
phone_number
: Scheme identifier’s support phone number. -
postal_code
: The scheme identifier’s support postal code. -
reference
: The scheme-unique identifier against which payments are submitted. -
region
: The scheme identifier’s support address region, county or department. -
scheme
: The scheme which this scheme identifier applies to. -
status
: The status of the scheme identifier. Onlyactive
scheme identifiers will be applied to a creditor and used against payments.
-
verification_
status - The creditor’s verification status, indicating whether they can yet receive payouts. For more details on handling verification as a partner, see our “Helping your users get verified” guide. One of:
-
successful
: The creditor’s account is fully verified, and they can receive payouts. Once a creditor has been successfully verified, they may in the future require further verification - for example, if they change their payout bank account, we will have to check that they own the new bank account before they can receive payouts again. -
in_review
: The creditor has provided all of the information currently requested, and it is awaiting review by GoCardless before they can be verified and receive payouts. -
action_required
: The creditor needs to provide further information to verify their account so they can receive payouts, and should visit the verification flow.
-
links
[default_ aud_ payout_ account] - ID of the bank account which is set up to receive payouts in AUD.
links
[default_ cad_ payout_ account] - ID of the bank account which is set up to receive payouts in CAD.
links
[default_ dkk_ payout_ account] - ID of the bank account which is set up to receive payouts in DKK.
links
[default_ eur_ payout_ account] - ID of the bank account which is set up to receive payouts in EUR.
links
[default_ gbp_ payout_ account] - ID of the bank account which is set up to receive payouts in GBP.
links
[default_ nzd_ payout_ account] - ID of the bank account which is set up to receive payouts in NZD.
links
[default_ sek_ payout_ account] - ID of the bank account which is set up to receive payouts in SEK.
links
[default_ usd_ payout_ account] - ID of the bank account which is set up to receive payouts in USD.
Create a creditor
Creates a new creditor.
Relative endpoint: POST /creditors
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product. Partners should instead manage multiple merchant accounts by building a partner integration.
Parameters
country_
code - required ISO 3166-1 alpha-2 code.
creditor_
type -
required The type of business of the creditor. Currently,
individual
,company
,charity
,partnership
, andtrust
are supported. name
- required The creditor’s trading name.
bank_
reference_ prefix - Prefix for the bank reference of payouts sent to this creditor. For instance, if
the creditor’s
bank_reference_prefix
wasACME
, the bank reference of a payout sent to that creditor could beACME-8G7Q8
.This prefix is also used for refunds in EUR and GBP.
POST https://api.gocardless.com/creditors HTTP/1.1
Content-Type: application/json
{
"creditors": {
"name": "Acme",
"country_code": "GB",
"creditor_type": "company",
"bank_reference_prefix": "ACME"
}
}
HTTP/1.1 201 Created
Location: /creditors/CR123
Content-Type: application/json
{
"creditors": {
"id": "CR123",
"created_at": "2017-02-16T12:34:56.000Z",
"name": "Acme",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": "GB",
"creditor_type": "company",
"logo_url": null,
"scheme_identifiers": [],
"verification_status": "successful",
"can_create_refunds": false,
"fx_payout_currency": null,
"mandate_imports_enabled": false,
"custom_payment_pages_enabled": true,
"merchant_responsible_for_notifications": true,
"bank_reference_prefix": "ACME",
"links": {}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditors()->create([
'params' => ['name' => 'Acme',
'country_code' => 'GB',
'bank_reference_prefix' => 'ACME',
'creditor_type' => 'company']
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditors.create(params={
"name": "Acme",
"country_code": "GB",
"creditor_type": "company",
"bank_reference_prefix": "ACME",
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditors.create(
params: {
name: "Acme",
country_code: "GB",
creditor_type: "company",
bank_reference_prefix: "ACME",
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Creditor creditor = client.creditors().create()
.withName("Acme")
.withCountryCode("GB")
.withCreditorType("company")
.withBankReferencePrefix("ACME")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditor = await client.creditors.create({
name: "Acme",
country_code: "GB",
creditor_type: "company",
bank_reference_prefix: "ACME",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorRequest = new GoCardless.Services.CreditorCreateRequest()
{
Name = "Acme",
CountryCode = "GB",
CreditorType = "company",
BankReferencePrefix = "ACME",
};
var creditorResponse = await gocardless.Creditors.CreateAsync(creditorRequest);
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorCreateParams := gocardless.CreditorCreateParams{
Name: "Acme",
CountryCode: "GB",
CreditorType: "company",
BankReferencePrefix: "ACME",
}
creditor, err := client.Creditors.Create(context, creditorCreateParams)
}
List creditors
Returns a cursor-paginated list of your creditors.
Relative endpoint: GET /creditors
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
limit
- Number of records to return.
GET https://api.gocardless.com/creditors HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null,
},
"limit": 50
},
"creditors":[{
"id": "CR123",
"created_at": "2017-02-16T12:34:56.000Z",
"name": "Acme",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": "GB",
"creditor_type": "company",
"logo_url": null,
"scheme_identifiers": [],
"verification_status": "successful",
"can_create_refunds": false,
"fx_payout_currency": null,
"mandate_imports_enabled": false,
"custom_payment_pages_enabled": true,
"merchant_responsible_for_notifications": true,
"bank_reference_prefix": "ACME",
"links": {}
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditors()->list();
$client->creditors()->list([
'params' => ['created_at[gt]' => '2014-05-08T17:01:06.000Z']
])
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditors.list().records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditors.list
@client.creditors.list(params: { limit: 2 })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Creditor creditor : client.creditors().all().execute()) {
System.out.println(creditor.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditors = await client.creditors.list();
// List the first three creditors.
const creditors = await client.creditors.list({ limit: 3 });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorListResponse = gocardless.Creditors.All();
foreach (GoCardless.Resources.Creditor creditor in creditorListResponse)
{
Console.WriteLine(creditor.Name);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorListParams := gocardless.CreditorListParams{
Limit: 3,
}
// List the first three creditors.
creditorListResult, err := client.Creditors.List(context, creditorListParams)
for _, creditor := creditorListResult.Creditors {
fmt.Println(creditor.Name)
}
}
Get a single creditor
Retrieves the details of an existing creditor.
Relative endpoint: GET /creditors/CR123
Parameters
GET https://api.gocardless.com/creditors/CR123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"creditors": {
"id": "CR123",
"created_at": "2017-02-16T12:34:56.000Z",
"name": "Acme",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": "GB",
"creditor_type": "company",
"logo_url": null,
"scheme_identifiers": [],
"verification_status": "successful",
"can_create_refunds": false,
"fx_payout_currency": null,
"mandate_imports_enabled": false,
"custom_payment_pages_enabled": true,
"merchant_responsible_for_notifications": true,
"bank_reference_prefix": "ACME",
"links": {}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditors()->get('CR123');
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditors.get("CR123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditors.get("CR123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Creditor creditor = client.creditors().get("CR123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditor = await client.creditor.find("CR123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorResponse = await gocardless.Creditors.GetAsync("CR0123");
GoCardless.Resources.Creditor creditor = creditorResponse.Creditor;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditor, err := client.Creditors.Get(context, "CR123")
}
Update a creditor
Updates a creditor object. Supports all of the fields supported when creating a creditor.
Relative endpoint: PUT /creditors/CR123
Parameters
address_
line1 - The first line of the creditor’s address.
address_
line2 - The second line of the creditor’s address.
address_
line3 - The third line of the creditor’s address.
bank_
reference_ prefix - Prefix for the bank reference of payouts sent to this creditor. For instance, if
the creditor’s
bank_reference_prefix
wasACME
, the bank reference of a payout sent to that creditor could beACME-8G7Q8
.This prefix is also used for refunds in EUR and GBP.
city
- The city of the creditor’s address.
country_
code - ISO 3166-1 alpha-2 code.
name
- The creditor’s trading name.
postal_
code - The creditor’s postal code.
region
- The creditor’s address region, county or department.
links
[default_ aud_ payout_ account] - ID of the bank account which is set up to receive payouts in AUD.
links
[default_ cad_ payout_ account] - ID of the bank account which is set up to receive payouts in CAD.
links
[default_ dkk_ payout_ account] - ID of the bank account which is set up to receive payouts in DKK.
links
[default_ eur_ payout_ account] - ID of the bank account which is set up to receive payouts in EUR.
links
[default_ gbp_ payout_ account] - ID of the bank account which is set up to receive payouts in GBP.
links
[default_ nzd_ payout_ account] - ID of the bank account which is set up to receive payouts in NZD.
links
[default_ sek_ payout_ account] - ID of the bank account which is set up to receive payouts in SEK.
links
[default_ usd_ payout_ account] - ID of the bank account which is set up to receive payouts in USD.
PUT https://api.gocardless.com/creditors/CR123 HTTP/1.1
Content-Type: application/json
{
"creditors": {
"links": {
"default_gbp_payout_account": "BA789"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"creditors": {
"id": "CR123",
"created_at": "2017-02-16T12:34:56.000Z",
"name": "Acme",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": "GB",
"creditor_type": "company",
"logo_url": null,
"scheme_identifiers": [],
"verification_status": "successful",
"can_create_refunds": false,
"fx_payout_currency": null,
"mandate_imports_enabled": false,
"custom_payment_pages_enabled": true,
"merchant_responsible_for_notifications": true,
"bank_reference_prefix": "ACME",
"links": {
"default_gbp_payout_account": "BA789",
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditors()->update('CR123', [
'params' => ['links' => ['default_gbp_payout_account' => 'BA789']]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditors.update("CR123", params={
"links": {
"default_gbp_payout_account": "BA789"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditors.update(
"CR123",
params: {
links: { default_gbp_payout_account: "BA789" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.creditors().update("CR123")
.withLinksDefaultGbpPayoutAccount("BA789")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditor = await client.creditors.update(
"CR123",
{
links: {
default_gbp_payout_account: "BA789"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorRequest = new GoCardless.Services.CreditorUpdateRequest()
{
Links = new GoCardless.Services.CreditorUpdateRequest.CreditorLinks()
{
DefaultGbpPayoutAccount = "BA789"
}
};
var creditorResponse = await gocardless.Creditors.UpdateAsync("CR0123", creditorRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorUpdateParams := gocardless.CreditorUpdateParams{
Links: &gocardless.CreditorUpdateParamsLinks{
DefaultGbpPayoutAccount: "BA789",
},
}
creditor, err := client.Creditors.Update(context, "CR123", creditorUpdateParams)
}
Creditor Bank Accounts
Creditor Bank Accounts hold the bank details of a creditor. These are the bank accounts which your payouts will be sent to.
Note that creditor bank accounts must be unique, and so you will encounter a bank_account_exists
error if you try to create a duplicate bank account. You may wish to handle this by updating the existing record instead, the ID of which will be provided as links[creditor_bank_account]
in the error response.
Restricted: This API is not available for partner integrations.
Properties
id
- Unique identifier, beginning with “BA”.
account_
holder_ name - Name of the account holder, as known by the bank. Usually this is the same as the name stored with the linked creditor. This field will be transliterated, upcased and truncated to 18 characters.
account_
number_ ending - The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
account_
type - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
name - Name of bank, taken from the bank details.
country_
code -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
enabled
- Boolean value showing whether the bank account is enabled or disabled.
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.
verification_
status - Verification status of the Bank Account. Can be one of
pending
,in_review
orsuccessful
links
[creditor] - ID of the creditor that owns this bank account.
Create a creditor bank account
Creates a new creditor bank account object.
Relative endpoint: POST /creditor_bank_accounts
Parameters
account_
holder_ name - required Name of the account holder, as known by the bank. Usually this is the same as the name stored with the linked creditor. This field will be transliterated, upcased and truncated to 18 characters.
account_
number - Bank account number - see local details for more information. Alternatively you can provide an
iban
. account_
type - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
code - Bank code - see local details for more information. Alternatively you can provide an
iban
. branch_
code - Branch code - see local details for more information. Alternatively you can provide an
iban
. country_
code -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
iban
- International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
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.
set_
as_ default_ payout_ account - Defaults to
true
. When this is set totrue
, it will cause this bank account to be set as the account that GoCardless will pay out to. links
[creditor] - required ID of the creditor that owns this bank account.
POST https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
Content-Type: application/json
{
"creditor_bank_accounts": {
"account_number": "55779911",
"branch_code": "200000",
"country_code": "GB",
"account_holder_name": "Acme",
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 201 Created
Location: /creditor_bank_accounts/BA123
Content-Type: application/json
{
"creditor_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-27T12:43:17.000Z",
"account_holder_name": "Acme",
"account_number_ending": "11",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"enabled": true,
"links": {
"creditor": "CR123"
},
"verification_status": "pending"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditorBankAccounts()->create([
"params" => ["account_number" => "55779911",
"branch_code" => "200000",
"country_code" => "GB",
"account_holder_name" => "Acme",
"links" => ["creditor" => "CR123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditor_bank_accounts.create(params={
"account_number": "55779911",
"branch_code": "200000",
"country_code": "GB",
"account_holder_name": "Acme",
"links": {
"creditor": "CR123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditor_bank_accounts.create(
params: {
account_holder_name: "Example Ltd",
account_number: "55779911",
branch_code: "200000",
country_code: "GB",
links: {
creditor: "CR123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().create()
.withAccountNumber("55779911")
.withBranchCode("200000")
.withCountryCode("GB")
.withAccountHolderName("Acme")
.withLinksCreditor("CR123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditorBankAccount = await client.creditorBankAccounts.create({
account_number: "55779911",
branch_code: "200000",
country_code: "GB",
account_holder_name: "Acme",
links: {
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorBankAccountRequest = new GoCardless.Services.CreditorBankAccountCreateRequest()
{
AccountHolderName = "Example Ltd",
AccountNumber = "55779911",
BranchCode = "200000",
CountryCode = "GB",
Links = new GoCardless.Services.CreditorBankAccountCreateRequest.CreditorBankAccountLinks()
{
Creditor = "CR0123"
}
};
var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.CreateAsync(creditorBankAccountRequest);
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorBankAccountCreateParams := gocardless.CreditorBankAccountCreateParams{
AccountNumber: "55779911",
BranchCode: "200000",
CountryCode: "GB",
AccountHolderName: "Acme",
}
creditorBankAccount, err := client.CreditorBankAccounts.Create(context, creditorBankAccountCreateParams)
}
List creditor bank accounts
Returns a cursor-paginated list of your creditor bank accounts.
Relative endpoint: GET /creditor_bank_accounts
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
creditor
- Unique identifier, beginning with “CR”.
enabled
- If
true
, only return enabled bank accounts. Iffalse
, only return disabled bank accounts. limit
- Number of records to return.
GET https://api.gocardless.com/creditor_bank_accounts HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": "BA123",
},
"limit": 50
},
"creditor_bank_accounts":[{
"id": "BA123",
"created_at": "2014-05-27T12:43:17.000Z",
"account_holder_name": "Acme",
"account_number_ending": "11",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"enabled": true,
"links": {
"creditor": "CR123"
},
"verification_status": "pending"
}, {
...
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditorBankAccounts()->list();
$client->creditorBankAccounts()->list([
"params" => ["enabled" => true]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditor_bank_accounts.list().records
client.creditor_bank_accounts.list(params={"creditor": "CR123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditor_bank_accounts.list
@client.creditor_bank_accounts.list(params: { enabled: true })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (CreditorBankAccount creditorBankAccount : client.creditorBankAccounts().all().withCreditor("CR123").execute()) {
System.out.println(creditorBankAccount.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditorBankAccounts = await client.creditorBankAccounts.list();
// List all 'enabled' creditor bank accounts.
const creditorBankAccounts = await client.creditorBankAccounts.list({ enabled: true });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorBankAccountRequest = new GoCardless.Services.CreditorBankAccountListRequest()
{
Creditor = "CR000123"
};
var creditorBankAccountListResponse = gocardless.CreditorBankAccounts.All(creditorBankAccountRequest);
foreach (GoCardless.Resources.CreditorBankAccount creditorBankAccount in creditorBankAccountListResponse)
{
Console.WriteLine(creditorBank.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorBankAccountListParams := gocardless.CreditorBankAccountListParams{}
creditorBankAccountListResult, err := client.CreditorBankAccounts.List(context, creditorBankAccountListParams)
for _, creditorBankAccount := range creditorBankAccountListResult.CreditorBankAccounts {
fmt.Println(creditorBankAccount.Id)
}
}
Get a single creditor bank account
Retrieves the details of an existing creditor bank account.
Relative endpoint: GET /creditor_bank_accounts/BA123
GET https://api.gocardless.com/creditor_bank_accounts/BA123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"creditor_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-27T12:43:17.000Z",
"account_holder_name": "Acme",
"account_number_ending": "11",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"enabled": true,
"links": {
"creditor": "CR123"
},
"verification_status": "pending"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditorBankAccounts()->get("BA123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditor_bank_accounts.get("BA123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditor_bank_accounts.get("BA123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
CreditorBankAccount creditorBankAccount = client.creditorBankAccounts().get("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditorBankAccount = await client.creditorBankAccounts.find('BA123');
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.GetAsync("BA0123");
GoCardless.Resources.CreditorBankAccount creditorBankAccount = creditorBankAccountResponse.CreditorBankAccount;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorBankAccount, err := client.CreditorBankAccounts.Get(context, "BA123")
}
Disable a creditor bank account
Immediately disables the bank account, no money can be paid out to a disabled account.
This will return a disable_failed
error if the bank account has already been disabled.
A disabled bank account can be re-enabled by creating a new bank account resource with the same details.
Relative endpoint: POST /creditor_bank_accounts/BA123/actions/disable
POST https://api.gocardless.com/creditor_bank_accounts/BA123/actions/disable HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"creditor_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-27T12:43:17.000Z",
"account_holder_name": "Acme",
"account_number_ending": "11",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"enabled": false,
"links": {
"creditor": "CR123"
},
"verification_status": "pending"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->creditorBankAccounts()->disable("BA123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.creditor_bank_accounts.disable("BA123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.creditor_bank_accounts.disable("BA123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.creditorBankAccounts().disable("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const creditorBankAccountResponse = await client.creditorBankAccounts.disable("BA123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var creditorBankAccountResponse = await gocardless.CreditorBankAccounts.DisableAsync("BA0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
creditorBankAccount, err := client.CreditorBankAccounts.Disable(context, "BA123")
}
Currency Exchange Rates
Currency exchange rates from our foreign exchange provider.
Properties
rate
- The exchange rate from the source to target currencies provided with up to 10 decimal places.
source
- Source currency
target
- Target currency
time
- Time at which the rate was retrieved from the provider.
List exchange rates
Returns a cursor-paginated list of all exchange rates.
Relative endpoint: GET /currency_exchange_rates
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
limit
- Number of records to return.
source
- Source currency
target
- Target currency
GET https://api.gocardless.com/currency_exchange_rates?source=GBP&target=EUR HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"currency_exchange_rates": [
{
"rate": "1.19111",
"source": "GBP",
"target": "EUR",
"time": "2020-02-24T23:50:04.000Z"
}
],
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->currencyExchangeRates()->list([
"params" => ["source" => "EUR", "target" => "GBP"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.currency_exchange_rates.list(params={"source": "EUR", "target": "GBP"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.currency_exchange_rates.list(params: { source: "EUR", target: "GBP" })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.currencyExchangeRates().all().withSource("EUR").withTarget("GBP").execute()
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const currencyExchangeRates = await client.currencyExchangeRates.list();
// List the currency exchange rate for a source and target currency.
const currencyExchangeRates = await client.currencyExchangeRates.list({ source: 'EUR', target: 'GBP' });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.CurrencyExchangeRateListRequest()
{
Source = "EUR",
Target = "GBP"
};
var response = gocardless.CurrencyExchangeRates.All(request);
foreach (GoCardless.Resources.CurrencyExchangeRate rate in response)
{
Console.WriteLine(rate.Rate);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
currencyExchangeRateListParams := gocardless.CurrencyExchangeRateListParams{
Source: "EUR",
Target: "GBP",
}
currencyExchangeRateListResult, err := client.CurrencyExchangeRates.List(context, currencyExchangeRateListParams)
for _, currencyExchangeRate := range currencyExchangeRateListResult.CurrencyExchangeRates {
fmt.Println(currencyExchangeRate.Id)
}
}
Customers
Customer objects hold the contact details for a customer. A customer can have several customer bank accounts, which in turn can have several Direct Debit mandates.
Properties
id
- Unique identifier, beginning with “CU”.
address_
line1 - The first line of the customer’s address.
address_
line2 - The second line of the customer’s address.
address_
line3 - The third line of the customer’s address.
city
- The city of the customer’s address.
company_
name - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). country_
code - ISO 3166-1 alpha-2 code.
created_
at - Fixed timestamp, recording when this resource was created.
danish_
identity_ number - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
email
- Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
family_
name - Customer’s surname. Required unless a
company_name
is provided. given_
name - Customer’s first name. Required unless a
company_name
is provided. language
-
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the
country_code
(if supplied) or default to “en”. 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.
phone_
number - ITU E.123 formatted phone number, including country code.
postal_
code - The customer’s postal code.
region
- The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). swedish_
identity_ number - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
Create a customer
Creates a new customer object.
Relative endpoint: POST /customers
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.
Warning: this endpoint is a legacy API endpoint and does not support GoCardless’ newest features. We recommend using the Billing Requests API instead.
Parameters
address_
line1 - The first line of the customer’s address.
address_
line2 - The second line of the customer’s address.
address_
line3 - The third line of the customer’s address.
city
- The city of the customer’s address.
company_
name - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). country_
code - ISO 3166-1 alpha-2 code.
danish_
identity_ number - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
email
- Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
family_
name - Customer’s surname. Required unless a
company_name
is provided. given_
name - Customer’s first name. Required unless a
company_name
is provided. language
-
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the
country_code
(if supplied) or default to “en”. 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.
phone_
number - ITU E.123 formatted phone number, including country code.
postal_
code - The customer’s postal code.
region
- The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). swedish_
identity_ number - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
POST https://api.gocardless.com/customers HTTP/1.1
Content-Type: application/json
{
"customers": {
"email": "user@example.com",
"given_name": "Frank",
"family_name": "Osborne",
"address_line1": "27 Acer Road",
"address_line2": "Apt 2",
"city": "London",
"postal_code": "E8 3GX",
"country_code": "GB",
"metadata": {
"salesforce_id": "ABCD1234"
}
}
}
HTTP/1.1 201 Created
Location: /customers/CU123
Content-Type: application/json
{
"customers": {
"id": "CU123",
"created_at": "2014-05-08T17:01:06.000Z",
"email": "user@example.com",
"given_name": "Frank",
"family_name": "Osborne",
"address_line1": "27 Acer Road",
"address_line2": "Apt 2",
"address_line3": null,
"city": "London",
"region": null,
"postal_code": "E8 3GX",
"country_code": "GB",
"language": "en",
"phone_number": null,
"swedish_identity_number": null,
"danish_identity_number": null,
"metadata": {
"salesforce_id": "ABCD1234"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customers()->create([
"params" => ["email" => "tim@gocardless.com",
"given_name" => "Tim",
"family_name" => "Rogers",
"country_code" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customers.create(params={
"email": "user@example.com",
"given_name": "Frank",
"family_name": "Osborne",
"address_line1": "27 Acer Road",
"address_line2": "Apt 2",
"city": "London",
"postal_code": "E8 3GX",
"country_code": "GB",
"metadata": {
"salesforce_id": "ABCD1234"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customers.create(
params: {
email: "user@example.com",
given_name: "Jacob",
family_name: "Pargin",
country_code: "GB"
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Customer customer = client.customers().create()
.withEmail("user@example.com")
.withGivenName("Frank")
.withFamilyName("Osborne")
.withAddressLine1("27 Acer Road")
.withAddressLine2("Apt 2")
.withCity("London")
.withPostalCode("E8 3GX")
.withCountryCode("GB")
.withMetadata("salesforce_id", "ABCD1234")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customer = await client.customers.create({
email: "user@example.com",
given_name: "Frank",
family_name: "Osborne",
address_line1: "27 Acer Road",
address_line2: "Apt 2",
city: "London",
postal_code: "E8 3GX",
country_code: "GB",
metadata: {
salesforce_id: "ABCD1234"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerRequest = new GoCardless.Services.CustomerCreateRequest()
{
Email = "user@example.com",
GivenName = "Frank",
FamilyName = "Osborne",
AddressLine1 = "27 Acer Road",
AddressLine2 = "Apt 2",
City = "London",
PostalCode = "E8 3GX",
CountryCode = "GB",
Metadata = new Dictionary<string, string>()
{
{"salesforce_id", "ABCD1234"}
}
};
var customerResponse = await gocardless.Customers.CreateAsync(customerRequest);
GoCardless.Resources.Customer customer = customerResponse.Customer;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerCreateParams := gocardless.CustomerCreateParams{
AddressLine1: "27 Acer Road",
AddressLine2: "Apt 2",
City: "London",
PostalCode: "E8 3GX",
CountryCode: "GB",
Email: "user@example.com",
GivenName: "Frank",
FamilyName: "Osborne",
}
customer, err := client.Customers.Create(context, customerCreateParams)
}
List customers
Returns a cursor-paginated list of your customers.
Relative endpoint: GET /customers
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
limit
- Number of records to return.
sort_
direction - The direction to sort in.
One of:
-
asc
-
desc
-
sort_
field - Field by which to sort records.
One of:
-
name
-
company_name
-
created_at
-
GET https://api.gocardless.com/customers?after=CU123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": "CU000",
"after": "CU456",
},
"limit": 50
},
"customers": [{
"id": "CU123",
"created_at": "2014-05-08T17:01:06.000Z",
"email": "user@example.com",
"given_name": "Frank",
"family_name": "Osborne",
"address_line1": "27 Acer Road",
"address_line2": "Apt 2",
"address_line3": null,
"city": "London",
"region": null,
"postal_code": "E8 3GX",
"country_code": "GB",
"language": "en",
"metadata": {
"salesforce_id": "ABCD1234"
}
}, {
...
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customers()->list();
$client->customers()->list([
"params" => ["created_at[gt]" => "2015-11-03T09:30:00Z"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customers.list().records
client.customers.list(params={"after": "CU123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customers.list
@client.customers.list(
params: {
"created_at[gt]" => "2016-08-06T09:30:00Z"
}
)
@client.customers.list.records.each { |customer| puts customer.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Customer customer : client.customers().all().execute()) {
System.out.println(customer.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customer = await client.customers.list();
// List customers with a given currency.
await client.customers.list({ currency: "GBP" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerListResponse = gocardless.Customers.All();
foreach (GoCardless.Resources.Customer customer in customerListResponse)
{
Console.WriteLine(customer.GivenName);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerListParams := gocardless.CustomerListParams{
Currency: "GBP",
}
customerListResult, err := client.Customers.List(context, customerListParams)
for _, customer GivenName range customerListResult.Customers {
fmt.Println(customer.GivenName)
}
}
Get a single customer
Retrieves the details of an existing customer.
Relative endpoint: GET /customers/CU123
GET https://api.gocardless.com/customers/CU123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"customers": {
"id": "CU123",
"created_at": "2014-05-08T17:01:06.000Z",
"email": "user@example.com",
"given_name": "Frank",
"family_name": "Osborne",
"address_line1": "27 Acer Road",
"address_line2": "Apt 2",
"address_line3": null,
"city": "London",
"region": null,
"postal_code": "E8 3GX",
"country_code": "GB",
"language": "en",
"phone_number": null,
"swedish_identity_number": null,
"danish_identity_number": null,
"metadata": {
"salesforce_id": "ABCD1234"
}
}
}
GET https://api.gocardless.com/customers/CU123 HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
"message": "This customer data has been removed",
"type": "invalid_api_usage",
"errors": [
{
"reason": "customer_removed",
"message": "This customer data has been removed"
}
],
"code": 410,
"request_id": "deadbeef-0000-4000-0000-444400004444"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customers()->get("CU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customers.get("CU123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customers.get("CU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Customer customer = client.customers().get("CU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customer = await client.customers.find("CU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerResponse = await gocardless.Customers.GetAsync("CU0123");
GoCardless.Resources.Customer customer = customerResponse.Customer;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customer, err := client.Customers.Get(context, "CU123")
}
Update a customer
Updates a customer object. Supports all of the fields supported when creating a customer.
Relative endpoint: PUT /customers/CU123
Parameters
address_
line1 - The first line of the customer’s address.
address_
line2 - The second line of the customer’s address.
address_
line3 - The third line of the customer’s address.
city
- The city of the customer’s address.
company_
name - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). country_
code - ISO 3166-1 alpha-2 code.
danish_
identity_ number - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
email
- Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
family_
name - Customer’s surname. Required unless a
company_name
is provided. given_
name - Customer’s first name. Required unless a
company_name
is provided. language
-
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the
country_code
(if supplied) or default to “en”. 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.
phone_
number - ITU E.123 formatted phone number, including country code.
postal_
code - The customer’s postal code.
region
- The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). swedish_
identity_ number - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
PUT https://api.gocardless.com/customers/CU123 HTTP/1.1
Content-Type: application/json
{
"customers": {
"email": "updated_user@example.com",
"given_name": "Jenny",
"family_name": "Osborne",
"metadata": {
"salesforce_id": "EFGH5678"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"customers": {
"id": "CU123",
"created_at": "2014-05-08T17:01:06.000Z",
"email": "updated_user@example.com",
"given_name": "Frank",
"family_name": "Osborne",
"address_line1": "29 Acer Road",
"address_line2": "Apt 3",
"address_line3": "Block 4",
"city": "London",
"region": null,
"postal_code": "E8 3GX",
"country_code": "GB",
"language": "en",
"phone_number": null,
"swedish_identity_number": null,
"danish_identity_number": null,
"metadata": {
"salesforce_id": "EFGH5678"
}
}
}
PUT https://api.gocardless.com/customers/CU123 HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
"message": "This customer data has been removed",
"type": "invalid_api_usage",
"errors": [
{
"reason": "customer_removed",
"message": "This customer data has been removed"
}
],
"code": 410,
"request_id": "deadbeef-0000-4000-0000-444400004444"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customers()->update("CU123", [
"params" => ["email" => "tim@gocardless.com"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customers.update("CU123", params={
"email": "updated_user@example.com"
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customers.update(
"CU123",
params: {
metadata: { custom_reference: "EXAMPLELTD01" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.customers().update("CU123")
.withEmail("updated_user@example.com")
.withGivenName("Jenny")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customer = await client.customers.update(
"CU123",
{
email: "updated_user@example.com",
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"custom_reference", "NEWREFERENCE001"}
}
};
var customerResponse = await gocardless.Customers.UpdateAsync("CU0123", customerRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerUpdateParams := gocardless.CustomerUpdateParams{
Email: "updated_user@example.com",
}
customer, err := client.Customers.Update(context, "CU123", customerUpdateParams)
}
Remove a customer
Removed customers will not appear in search results or lists of customers (in our API or exports), and it will not be possible to load an individually removed customer by ID.
The action of removing a customer cannot be reversed, so please use with care.
Relative endpoint: DELETE /customers/CU123
Parameters
DELETE https://api.gocardless.com/customers/CU123 HTTP/1.1
HTTP/1.1 204 No Content
DELETE https://api.gocardless.com/customers/CU123 HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
"message": "This customer data has been removed",
"type": "invalid_api_usage",
"errors": [
{
"reason": "customer_removed",
"message": "This customer data has been removed"
}
],
"code": 410,
"request_id": "deadbeef-0000-4000-0000-444400004444"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customers()->remove("CU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customers.remove("CU123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customers.remove("CU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.customers().remove("CU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customer = await client.customers.remove("CU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
await gocardless.Customers.RemoveAsync("CU0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customer, err := client.Customers.Remove(context, "CU123")
}
Customer Bank Accounts
Customer Bank Accounts hold the bank details of a customer. They always belong to a customer, and may be linked to several Direct Debit mandates.
Note that customer bank accounts must be unique, and so you will encounter a bank_account_exists
error if you try to create a duplicate bank account. You may wish to handle this by updating the existing record instead, the ID of which will be provided as links[customer_bank_account]
in the error response.
Note: To ensure the customer’s bank accounts are valid, verify them first using bank_details_lookups, before proceeding with creating the accounts
Properties
id
- Unique identifier, beginning with “BA”.
account_
holder_ name - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
account_
number_ ending - The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
account_
type - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
account_ token - A token to uniquely refer to a set of bank account details. This feature is still in early access and is only available for certain organisations.
bank_
name - Name of bank, taken from the bank details.
country_
code -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
enabled
- Boolean value showing whether the bank account is enabled or disabled.
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.
links
[customer] - ID of the customer that owns this bank account.
Create a customer bank account
Creates a new customer bank account object.
There are three different ways to supply bank account details:
For more information on the different fields required in each country, see local bank details.
Relative endpoint: POST /customer_bank_accounts
Note: this endpoint is a legacy API endpoint and does not support GoCardless’ newest features. We recommend using the Billing Requests API instead.
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.
Parameters
account_
holder_ name - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
account_
number - Bank account number - see local details for more information. Alternatively you can provide an
iban
. account_
type - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
code - Bank code - see local details for more information. Alternatively you can provide an
iban
. branch_
code - Branch code - see local details for more information. Alternatively you can provide an
iban
. country_
code -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
iban
- International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
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.
links
[customer] - required ID of the customer that owns this bank account.
links
[customer_ bank_ account_ token] - ID of a customer bank account token to use in place of bank account parameters.
POST https://api.gocardless.com/customer_bank_accounts HTTP/1.1
Content-Type: application/json
{
"customer_bank_accounts": {
"account_number": "55779911",
"branch_code": "200000",
"account_holder_name": "Frank Osborne",
"country_code": "GB",
"links": {
"customer": "CU123"
}
}
}
HTTP/1.1 201 Created
Location: /customer_bank_accounts/BA123
Content-Type: application/json
{
"customer_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-08T17:01:06.000Z",
"account_holder_name": "Frank Osborne",
"account_number_ending": "11",
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"metadata": {},
"enabled": true,
"links": {
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customerBankAccounts()->create([
"params" => ["account_number" => "55779911",
"branch_code" => "200000",
"account_holder_name" => "Frank Osborne",
"country_code" => "GB",
"links" => ["customer" => "CU123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customer_bank_accounts.create(params={
"account_number": "55779911",
"branch_code": "200000",
"account_holder_name": "Frank Osborne",
"country_code": "GB",
"links": {
"customer": "CU123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customer_bank_accounts.create(
params: {
account_holder_name: "Fran Cosborne",
account_number: "55779911",
branch_code: "200000",
country_code: "GB",
links: {
customer: "CU123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
CustomerBankAccount customerBankAccount = client.customerBankAccounts().create()
.withAccountNumber("55779911")
.withBranchCode("200000")
.withAccountHolderName("Frank Osborne")
.withCountryCode("GB")
.withLinksCustomer("CU123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customerBankAccount = await client.customerBankAccounts.create({
account_number: "55779911",
branch_code: "200000",
account_holder_name: "Frank Osborne",
country_code: "GB",
links: {
customer: "CU123"
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountCreateRequest()
{
AccountHolderName = "Example Ltd",
AccountNumber = "55779911",
BranchCode = "200000",
CountryCode = "GB",
Links = new GoCardless.Services.CustomerBankAccountCreateRequest.CustomerBankAccountLinks()
{
Customer = "CU0123"
}
};
var customerBankAccountResponse = await gocardless.CustomerBankAccounts.CreateAsync(customerBankAccountRequest);
GoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerBankAccountCreateParams := gocardless.CustomerBankAccountCreateParams{
AccountNumber: "55779911",
BranchCode: "200000",
AccountHolderName: "Frank Osborne",
CountryCode: "GB",
Links: gocardless.CustomerBankAccountCreateParamsLinks{
Customer: "CU123",
},
}
customerBankAccount, err := client.CustomerBankAccounts.Create(context, customerBankAccountCreateParams)
}
List customer bank accounts
Returns a cursor-paginated list of your bank accounts.
Relative endpoint: GET /customer_bank_accounts
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
customer
- Unique identifier, beginning with “CU”.
enabled
- Get enabled or disabled customer bank accounts.
limit
- Number of records to return.
GET https://api.gocardless.com/customer_bank_accounts HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"customer_bank_accounts": [{
"id": "BA123",
"created_at": "2014-05-08T17:01:06.000Z",
"account_holder_name": "Frank Osborne",
"account_number_ending": "11",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"metadata": {},
"enabled": true,
"links": {
"customer": "CU123"
}
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customerBankAccounts()->list();
$client->customerBankAccounts()->list([
"params" => ["customer" => "CU123",
"enabled" => true]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customer_bank_accounts.list(params={"customer": "CU123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customer_bank_accounts.list
@client.customer_bank_accounts.list(
params: {
customer: "CU123",
enabled: true
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (CustomerBankAccount customerBankAccount : client.customerBankAccounts().all().withCustomer("CU123").withEnabled(true).execute()) {
System.out.println(customerBankAccount.getAccountHolderName());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customerBankAccount = await client.customerBankAccounts.list();
// List all 'enabled' customer bank accounts.
await client.customerBankAccounts.list({ enabled: true });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountListRequest()
{
Customer = "CU000123"
};
var customerBankAccountListResponse = gocardless.CustomerBankAccounts.All(customerBankAccountRequest);
foreach (GoCardless.Resources.CustomerBankAccount customerBankAccount in customerBankAccountListResponse)
{
Console.WriteLine(customerBank.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerBankAccountListParams := gocardless.CustomerBankAccountListParams{
Enabled: true,
}
customerBankAccountListResult, err := client.CustomerBankAccounts.List(context, customerBankAccountListParams)
for _, customerBankAccount := range customerBankAccountListResult.CustomerBankAccounts {
fmt.Println(customerBankAccount.Id)
}
}
Get a single customer bank account
Retrieves the details of an existing bank account.
Relative endpoint: GET /customer_bank_accounts/BA123
GET https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"customer_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-08T17:01:06.000Z",
"account_number_ending": "11",
"account_holder_name": "Frank Osborne",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"metadata": {},
"enabled": true,
"links": {
"customer": "CU123"
}
}
}
GET https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
"message": "This customer data has been removed",
"type": "invalid_api_usage",
"errors": [
{
"reason": "customer_removed",
"message": "This customer data has been removed"
}
],
"code": 410,
"request_id": "deadbeef-0000-4000-0000-444400004444"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customerBankAccounts()->get("BA123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customer_bank_accounts.get("BA123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customer_bank_accounts.get("BA123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
CustomerBankAccount customerBankAccount = client.customerBankAccounts.get("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customerBankAccount = await client.customerBankAccounts.find("BA123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerBankAccountResponse = await gocardless.CustomerBankAccounts.GetAsync("BA0123");
GoCardless.Resources.CustomerBankAccount customerBankAccount = customerBankAccountResponse.CustomerBankAccount;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerBankAccount, err := client.CustomerBankAccounts.Get(context, "BA123")
}
Update a customer bank account
Updates a customer bank account object. Only the metadata parameter is allowed.
Relative endpoint: PUT /customer_bank_accounts/BA123
Parameters
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.
PUT https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
Content-Type: application/json
{
"customer_bank_accounts": {
"metadata": {
"key": "value"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"customer_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-08T17:01:06.000Z",
"account_number_ending": "11",
"account_holder_name": "Frank Osborne",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"metadata": {
"key": "value"
},
"enabled": true,
"links": {
"customer": "CU123"
}
}
}
PUT https://api.gocardless.com/customer_bank_accounts/BA123 HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/api-reference#customer_data_removed",
"message": "This customer data has been removed",
"type": "invalid_api_usage",
"errors": [
{
"reason": "customer_removed",
"message": "This customer data has been removed"
}
],
"code": 410,
"request_id": "deadbeef-0000-4000-0000-444400004444"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customerBankAccounts()->update("BA123", [
"params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customer_bank_accounts.update("BA123", params={
"metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customer_bank_accounts.update(
"BA123",
params: {
metadata: { description: "Business account" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.customerBankAccounts().update("BA123")
.withMetadata("description", "Business account")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customerBankAccount = await client.customerBankAccounts.update(
"BA123",
{
metadata: {
key: "value"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerBankAccountRequest = new GoCardless.Services.CustomerBankAccountUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"description", "Business account"}
}
};
var customerBankAccountResponse = await gocardless.CustomerBankAccounts.UpdateAsync("BA0123", customerBankAccountRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerBankAccountUpdateParams := gocardless.CustomerBankAccountUpdateParams{
Metadata: map[string]interface{}{"key": "value"},
}
customerBankAccount, err := client.CustomerBankAccounts.Update(context, customerBankAccountUpdateParams)
}
Disable a customer bank account
Immediately cancels all associated mandates and cancellable payments.
This will return a disable_failed
error if the bank account has already been disabled.
A disabled bank account can be re-enabled by creating a new bank account resource with the same details.
Relative endpoint: POST /customer_bank_accounts/BA123/actions/disable
POST https://api.gocardless.com/customer_bank_accounts/BA123/actions/disable HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"customer_bank_accounts": {
"id": "BA123",
"created_at": "2014-05-08T17:01:06.000Z",
"account_number_ending": "11",
"account_holder_name": "Frank Osborne",
"account_type": null,
"country_code": "GB",
"currency": "GBP",
"bank_name": "BARCLAYS BANK PLC",
"metadata": {},
"enabled": false,
"links": {
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customerBankAccounts()->disable("BA123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customer_bank_accounts.disable("BA123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customer_bank_accounts.disable("BA123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.customerBankAccounts.disable("BA123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customerBankAccount = await client.customerBankAccounts.disable("BA123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerBankAccountResponse = await gocardless.CustomerBankAccounts.DisableAsync("BA0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerBankAccount, err := client.CustomerBankAccounts.Disable(context, "BA123")
}
Customer Notifications
Customer Notifications represent the notification which is due to be sent to a customer
after an event has happened. The event, the resource and the customer to be notified
are all identified in the links
property.
Note that these are ephemeral records - once the notification has been actioned in some way, it is no longer visible using this API.
Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.
Properties
id
- The id of the notification.
action_
taken - The action that was taken on the notification. Currently this can only be
handled
, which means the integrator sent the notification themselves. action_
taken_ at - Fixed timestamp, recording when this action was taken.
action_
taken_ by - A string identifying the integrator who was able to handle this notification.
type
- The type of notification the customer shall receive.
One of:
-
payment_created
-
payment_cancelled
-
mandate_created
-
mandate_blocked
-
subscription_created
-
subscription_cancelled
-
instalment_schedule_created
-
instalment_schedule_cancelled
-
links
[customer] - The customer who should be contacted with this notification.
links
[event] - The event that triggered the notification to be scheduled.
links
[mandate] - The identifier of the related mandate.
links
[payment] - The identifier of the related payment.
links
[refund] - The identifier of the related refund.
links
[subscription] - The identifier of the related subscription.
Handle a notification
“Handling” a notification means that you have sent the notification yourself (and
don’t want GoCardless to send it).
If the notification has already been actioned, or the deadline to notify has passed,
this endpoint will return an already_actioned
error and you should not take
further action. This endpoint takes no additional parameters.
Relative endpoint: POST /customer_notifications/PCN123/actions/handle
Parameters
POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1
HTTP/1.1 201 Created
Content-Type: application/json
{
"customer_notifications": {
"id": "PCN123",
"type": "payment_created",
"action_taken": "handled",
"action_taken_at": "2018-08-01T13:42:56.000Z",
"action_taken_by": "Partner name",
"links": {
"customer": "CU123",
"event": "EV123",
"payment": "PM123"
}
}
}
POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": {
"message": "You are not authorised to handle notifications of this type.",
"documentation_url": "https://developer.gocardless.com/api-reference#notification_type_forbidden",
"type": "gocardless",
"code": 403,
"request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
"errors": [
{
"reason": "notification_type_forbidden",
"message": "You are not authorised to handle notifications of this type."
}
]
}
}
POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": {
"message": "You are not the notification owner for this resource.",
"documentation_url": "https://developer.gocardless.com/api-reference#not_notification_owner",
"type": "gocardless",
"code": 403,
"request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
"errors": [
{
"reason": "not_notification_owner",
"message": "You are not the notification owner for this resource."
}
]
}
}
POST https://api.gocardless.com/customer_notifications/PCN123/actions/handle HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"message": "This notification can no longer be handled.",
"documentation_url": "https://developer.gocardless.com/api-reference#already_actioned",
"type": "gocardless",
"code": 410,
"request_id": "900ceabb-c55d-4006-80b7-a7a40c171e31",
"errors": [
{
"reason": "already_actioned",
"message": "This notification can no longer be handled."
}
]
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->customerNotifications()->handle("PCN123")
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.customer_notifications.handle("PCN123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.customer_notifications.handle("PCN123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
CustomerNotification customerNotification = client.customerNotifications().handle("PCN123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const customerNotification = await client.customerNotifications.handle("PCN123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customerNotificationResponse = await gocardless.CustomerNotifications.HandleAsync("PCN123");
GoCardless.Resources.CustomerNotification customerNotification = customerNotificationResponse.CustomerNotification;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
customerNotificationHandleParams := map[string]interface{}{}
customerNotification, err := client.CustomerNotifications.Handle(context, "PCN123", customerNotificationHandleParams)
}
Events
Events are stored for all webhooks. An event refers to a resource which has been updated, for example a payment which has been collected, or a mandate which has been transferred. Event creation is an asynchronous process, so it can take some time between an action occurring and its corresponding event getting included in API responses. See here for a complete list of event types.
Properties
id
- Unique identifier, beginning with “EV”.
action
- What has happened to the resource. See Event Actions for the possible actions.
created_
at - Fixed timestamp, recording when this resource was created.
customer_
notifications - Present only in webhooks when an integrator is authorised to send their own
notifications. See here
for further information.
Each instance will contain these properties:
-
deadline
: Time after which GoCardless will send the notification by email. -
id
: The id of the notification. -
mandatory
: Whether or not the notification must be sent. -
type
: See here for a complete list of customer notification types.
-
details
[bank_ account_ id] - When we send a creditor
new_payout_currency_added
webhook, we also send the bank account id of the new account details
[cause] - What triggered the event. Note:
cause
is our simplified and predictable key indicating what triggered the event. details
[currency] - When we send a creditor
new_payout_currency_added
webhook, we also send the currency of the new account details
[description] - Human readable description of the cause. Note: Changes to event descriptions are not considered breaking.
details
[item_ count] - Count of rows in the csv. This is sent for export events
details
[not_ retried_ reason] - When will_attempt_retry is set to false, this field will contain
the reason the payment was not retried. This can be one of:
-
failure_filter_applied
: The payment won’t be intelligently retried as there is a high likelihood of failure on retry. -
other
: The payment won’t be intelligently retried due to any other reason.
-
details
[origin] - Who initiated the event. One of:
-
bank
: this event was triggered by a report from the banks -
gocardless
: this event was performed by GoCardless automatically -
api
: this event was triggered by an API endpoint -
customer
: this event was triggered by a Customer -
payer
: this event was triggered by a Payer
-
details
[property] - When we send a creditor
creditor_updated
webhook, this tells you which property on the creditor has been updated details
[reason_ code] - Set when a
bank
is the origin of the event. This is the reason code received in the report from the customer’s bank. See the GoCardless Direct Debit guide for information on the meanings of different reason codes. Note:reason_code
is payment scheme-specific and can be inconsistent between banks. details
[scheme] - A bank payment scheme. Set when a bank is the origin of the event.
details
[will_ attempt_ retry] - Whether the payment will be retried automatically. Set on a payment failed event.
metadata
- The metadata that was passed when making the API request that triggered the event
(for instance, cancelling a mandate).
This field will only be populated if the
details[origin]
field isapi
otherwise it will be an empty object. resource_
metadata - The metadata of the resource that the event is for. For example, this field will have the same
value of the
mandate[metadata]
field on the response you would receive from performing a GET request on a mandate. resource_
type - The resource type for this event. One of:
-
billing_requests
-
creditors
-
exports
-
instalment_schedules
-
mandates
-
payer_authorisations
-
payments
-
payouts
-
refunds
-
scheme_identifiers
-
subscriptions
-
links
[bank_ authorisation] - ID of a bank authorisation.
links
[billing_ request] - ID of a billing request.
links
[billing_ request_ flow] - ID of a billing request flow.
links
[creditor] - If
resource_type
iscreditor
, this is the ID of the creditor which has been updated. links
[customer] - ID of a customer.
links
[customer_ bank_ account] - ID of a customer bank account.
links
[instalment_ schedule] - If
resource_type
isinstalment_schedule
, this is the ID of the instalment schedule which has been updated. links
[mandate] - If
resource_type
ismandates
, this is the ID of the mandate which has been updated. links
[mandate_ request_ mandate] - If
resource_type
isbilling_requests
, this is the ID of the mandate which has been created. links
[new_ customer_ bank_ account] - This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred to.
links
[new_ mandate] - This is only included for mandate replaced events, when it is the ID of the new mandate that replaces the existing mandate.
links
[organisation] - If the event is included in a webhook to an OAuth app, this is the ID of the account to which it belongs.
links
[parent_ event] - If this event was caused by another, this is the ID of the cause. For example, if a mandate is cancelled it automatically cancels all pending payments associated with it; in this case, the payment cancellation events would have the ID of the mandate cancellation event in this field.
links
[payer_ authorisation] - ID of a payer authorisation.
links
[payment] - If
resource_type
ispayments
, this is the ID of the payment which has been updated. links
[payment_ request_ payment] - If
resource_type
isbilling_requests
, this is the ID of the payment which has been created for Instant Bank Payment. links
[payout] - If
resource_type
ispayouts
, this is the ID of the payout which has been updated. links
[previous_ customer_ bank_ account] - This is only included for mandate transfer events, when it is the ID of the customer bank account which the mandate is being transferred from.
links
[refund] - If
resource_type
isrefunds
, this is the ID of the refund which has been updated. links
[scheme_ identifier] - If
resource_type
isscheme_identifiers
, this is the ID of the scheme_identifier which has been updated. links
[subscription] - If
resource_type
issubscription
, this is the ID of the subscription which has been updated.
List events
Returns a cursor-paginated list of your events.
Relative endpoint: GET /events
Parameters
action
- Limit to events with a given
action
. after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
billing_
request - ID of a billing request. If specified, this endpoint will return all events for the given billing request.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
creditor
- ID of an creditor. If specified, this endpoint will return all events for the given creditor.
export
- ID of an export. If specified, this endpoint will return all events for the given export.
include
- Includes linked resources in the response. Must be used with the
resource_type
parameter specified. The include should be one of:-
billing_request
-
creditor
-
instalment_schedule
-
mandate
-
payer_authorisation
-
payment
-
payout
-
refund
-
scheme_identifier
-
subscription
-
instalment_
schedule - ID of an instalment schedule. If specified, this endpoint will return all events for the given instalment schedule.
limit
- Number of records to return.
mandate
- ID of a mandate. If specified, this endpoint will return all events for the given mandate.
parent_
event - ID of an event. If specified, this endpoint will return all events whose parent_event is the given event ID.
payer_
authorisation - ID of a payer authorisation.
payment
- ID of a payment. If specified, this endpoint will return all events for the given payment.
payout
- ID of a payout. If specified, this endpoint will return all events for the given payout.
refund
- ID of a refund. If specified, this endpoint will return all events for the given refund.
resource_
type - Type of resource that you’d like to get all events for.
Cannot be used together with the
billing_request
,creditor
,export
,instalment_schedule
,mandate
,payer_authorisation
,payment
,payout
,refund
,scheme_identifier
orsubscription
parameters. The type can be one of:-
billing_requests
-
creditors
-
exports
-
instalment_schedules
-
mandates
-
payer_authorisations
-
payments
-
payouts
-
refunds
-
scheme_identifiers
-
subscriptions
-
scheme_
identifier - ID of a scheme identifier. If specified, this endpoint will return all events for the given scheme identifier.
subscription
- ID of a subscription. If specified, this endpoint will return all events for the given subscription.
GET https://api.gocardless.com/events HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
},
"events":[
{
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "mandates",
"action": "cancelled",
"details": {
"origin": "bank",
"cause": "bank_account_disabled",
"description": "Customer's bank account closed",
"scheme": "bacs",
"reason_code": "ADDACS-B"
},
"metadata": {},
"resource_metadata": { "order_id": "123" },
"links": {
"mandate": "MD123"
}
},
{
"id": "EV456",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "cancelled",
"details": {
"origin": "bank",
"cause": "mandate_cancelled",
"description": "The mandate for this payment was cancelled at a bank branch.",
"scheme": "bacs",
"reason_code": "ADDACS-B"
},
"metadata": {},
"resource_metadata": { "order_dispatch_date": "2014-05-22" },
"links": {
"payment": "PM123",
"parent_event": "EV123"
}
}
]
}
GET https://api.gocardless.com/events?resource_type=payments&include=payment HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
},
"events":[
{
"id": "EV456",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "cancelled",
"details": {
"origin": "bank",
"cause": "mandate_cancelled",
"description": "The mandate for this payment was cancelled at a bank branch.",
"scheme": "bacs",
"reason_code": "ADDACS-B"
},
"metadata": {},
"resource_metadata": { "order_dispatch_date": "2014-05-22" },
"links": {
"payment": "PM123",
"parent_event": "EV123"
}
}
],
"linked": {
"payments": [
{
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-15",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "paid_out",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"amount_refunded": 0,
"links": {
"mandate": "MD123",
"creditor": "CR123"
}
}
]
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->events()->list();
$client->events()->list([
"params" => ["resource_type" => "payments"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.events.list().records
client.events.list(params={"resource_type": "payments"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.events.list
@client.events.list(params: { resource_type: "payments" })
@client.events.list.records.each { |event| puts event.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Event event : client.events().all().withResourceType("payments").execute()) {
System.out.println(event.getAction());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const events = await client.events.list();
// List all events of a given resource type.
const events = await client.events.list({ resource_type: "payments" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var eventRequest = new GoCardless.Services.EventListRequest()
{
ResourceType = GoCardless.Services.EventListRequest.EventResourceType.Payments
};
var eventListResponse = gocardless.Events.All(eventRequest);
foreach (GoCardless.Resources.Event eventResource in eventListResponse)
{
Console.WriteLine(eventResource.Action);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
eventListParams := gocardless.EventListParams{
ResourceType: "payments",
}
eventListResult, err := client.Events.List(context, eventListParams)
for _, event := range eventListResult.Events {
fmt.Println(event.Action)
}
}
Get a single event
Retrieves the details of a single event.
Relative endpoint: GET /events/EV123
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "confirmed",
"details": {
"origin": "gocardless",
"cause": "payment_confirmed",
"description": "Payment confirmed"
},
"metadata": {},
"resource_metadata": { "order_dispatch_date": "2014-05-22" },
"links": {
"payment": "PM123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->events()->get("EV123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.events.get("EV123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.events.get("EV123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Event event = client.events().get("EV123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const event = await client.events.find("EV123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var eventResponse = await gocardless.Events.GetAsync("EV0123");
GoCardless.Resources.Event eventResource = eventResponse.Event;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
event, err := client.Events.Get(context, "EV123")
}
Reconciling Payouts with Events
When a payout is created not only does it have an event created for it, but all payments and refunds within that payout have events created for them too. If you know the payout’s ID, you can fetch all of these events using two API requests.
The first step is to find the “paid” event for the Payout you’re interested in. You can do this by filtering events based on the ID of the payout and the action, which is “paid”:
GET https://api.gocardless.com/events?payout=PY123&action=paid
To find child events for a payout, filter for events with a parent_event
equal to the Payout’s paid event:
GET https://api.gocardless.com/events?parent_event=EV123
This will return a paginated list of all child events for payments and refunds associated with the payout.
If you’d also like to return the associated payments or refunds, you can scope the request to a resource_type and include those resources:
GET https://api.gocardless.com/events?parent_event=EV123&resource_type=payments&include=payment
GET https://api.gocardless.com/events?parent_event=EV123&resource_type=refunds&include=refund
GET https://api.gocardless.com/events?payout=PY123&action=paid HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
},
"events": [
{
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payouts",
"action": "paid",
"details": {
"origin": "gocardless",
"cause": "payout_paid",
"description": "Payout sent"
},
"metadata": {},
"links": {
"payout": "PO123"
}
}
]
}
GET https://api.gocardless.com/events?parent_event=EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
},
"events": [
{
"id": "EV456",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "paid_out",
"details": {
"origin": "gocardless",
"cause": "payment_paid_out",
"description": "The payment has been paid out by GoCardless."
},
"metadata": {},
"links": {
"payment": "PM123"
}
}
]
}
Exports
File-based exports of data
Properties
id
- Unique identifier, beginning with “EX”.
created_
at - Fixed timestamp, recording when this resource was created.
currency
- The currency of the export (if applicable)
download_
url - Download url for the export file. Subject to expiry.
export_
type - The type of the export
Get a single export
Returns a single export.
Relative endpoint: GET /exports/EX123
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
GET https://api.gocardless.com/exports/EX123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"exports": {
"id": "EX123",
"created_at": "2014-01-01T12:00:00.000Z",
"export_type": "payout_transactions_reconciliation",
"download_url": "https://downloads.gocardless.com/EX123/example.csv",
"currency": "GBP"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->exports()->get('EX123');
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.exports.get("EX123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.exports.get("EX123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Export export = client.exports().get("EX123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const exportData = await client.exports.find("EX123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var exportResponse = await gocardless.Exports.GetAsync("EX123");
GoCardless.Resources.Export export = exportResponse.Export;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
export, err := client.Exports.Get(context, "EX123")
}
List exports
Returns a list of exports which are available for download.
Relative endpoint: GET /exports
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
limit
- Number of records to return.
GET https://api.gocardless.com/exports HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"exports": [
{
"id": "EX123",
"created_at": "2014-01-01T12:00:00.000Z",
"export_type": "payout_transactions_reconciliation",
"currency": "GBP"
},
{
"id": "EX456",
"created_at": "2014-01-01T12:00:00.000Z",
"export_type": "payout_transactions_reconciliation",
"currency": "EUR"
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->exports()->list();
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.exports.list().records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.exports.list
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Export export : client.exports().all().execute()) {
System.out.println(export.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const exports = await client.exports.list();
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var exportListResponse = gocardless.Exports.All();
foreach (GoCardless.Resources.Export export in exportListResponse)
{
Console.WriteLine(export.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
exportListParams := gocardless.ExportListParams{}
exportListResult, err := client.Exports.List(context, exportListParams)
for _, export := range exportListResult.Exports {
fmt.Println(export.Id)
}
}
Instalment Schedules
Instalment schedules are objects which represent a collection of related payments, with the
intention to collect the total_amount
specified. The API supports both schedule-based
creation (similar to subscriptions) as well as explicit selection of differing payment
amounts and charge dates.
Unlike subscriptions, the payments are created immediately, so the instalment schedule cannot be modified once submitted and instead can only be cancelled (which will cancel any of the payments which have not yet been submitted).
Customers will receive a single notification about the complete schedule of collection.
Properties
id
- Unique identifier, beginning with “IS”.
created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
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.
name
- Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
payment_
errors - If the status is
creation_failed
, this property will be populated with validation failures from the individual payments, arranged by the index of the payment that failed. status
- One of:
-
pending
: we’re waiting for GC to create the payments -
active
: the payments have been created, and the schedule is active -
creation_failed
: payment creation failed -
completed
: we have passed the date of the final payment and all payments have been collected -
cancelled
: the schedule has been cancelled -
errored
: one or more payments have failed
-
total_
amount - The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
links
[customer] - ID of the associated customer.
links
[mandate] - ID of the associated mandate which the instalment schedule will create payments against.
payments
- Array of IDs of the associated payments
Create (with dates)
Creates a new instalment schedule object, along with the associated payments. This API is recommended if you know the specific dates you wish to charge. Otherwise, please check out the scheduling version.
The instalments
property is an array of payment properties (amount
and
charge_date
).
It can take quite a while to create the associated payments, so the API will return
the status as pending
initially. When processing has completed, a subsequent GET
request for the instalment schedule will either have the status success
and link
to the created payments, or the status error
and detailed information about the
failures.
Relative endpoint: POST /instalment_schedules
Parameters
currency
- required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
instalments
-
required An explicit array of instalment payments, each specifying at least an
amount
andcharge_date
. See create (with dates) name
- required Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
total_
amount - required The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
app_
fee - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.
payment_
reference - An optional reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. 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, Pro or Enterprise packages. Restricted: You can not specify a payment reference for Faster Payments. retry_
if_ possible - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. links
[mandate] - required ID of the associated mandate which the instalment schedule will create payments against.
POST https://api.gocardless.com/instalment_schedules HTTP/1.1
Content-Type: application/json
{
"instalment_schedules": {
"name": "Bike Invoice 271",
"currency": "GBP",
"total_amount": "2500",
"instalments": [
{
"amount": "1500",
"charge_date": "2019-12-14"
},
{
"amount": "1000",
"charge_date": "2020-05-01"
}
],
"metadata": {},
"links": {
"mandate": "MD123"
}
}
}
HTTP/1.1 201 (Created)
Location: /instalment_schedules/IS123
Content-Type: application/json
{
"instalment_schedules": {
"id": "IS123",
"status": "pending",
"total_amount": "2500",
"metadata": {},
"payment_errors": {},
"links": {
"mandate": "MD123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'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'
],
"metadata" => []
],
"headers" => [
'Idempotency-Key' => 'random_instalment_schedule_specific_string'
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
instalment_schedule = client.instalment_schedules.create_with_dates(
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'
},
"metadata": {}
}, headers={
'Idempotency-Key': 'random_instalment_schedule_specific_string'
}
)
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
instalment_schedule = @client.instalment_schedules.create_with_dates(
params: {
name: "ACME Invoice 103",
total_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'
},
metadata: {}
},
headers: {
'Idempotency-Key': 'random_instalment_schedule_specific_string'
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
int[] amountsArray = {3400, 3400, 3200};
String[] datesArray = {"2019-08-20", "2019-09-03", "2019-09-17"};
InstalmentSchedule instalmentSchedule = client.instalmentSchedules().createWithDates()
.withTotalAmount(10000) // 100 GBP in Pence, collected from the end customer.
.withAppFee(10) // Your 10 pence fee, applied to each instalment, to be
// paid out to you
.withCurrency("GBP")
.withAmounts(amountsArray)
.withDates(datesArray)
.withLinksMandate("MD0000YTKZKY4J")
.withMetadata("invoiceId", "001")
.withIdempotencyKey("random_instalment_schedule_specific_string")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const instalmentSchedule = await client.instalmentSchedules.createWithDates(
{
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'
},
metadata: {}
},
"instalment_schedule_idempotency_key"
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var createResponse = await gocardless.InstalmentSchedules.CreateWithDatesAsync(
new InstalmentScheduleCreateWithDatesRequest
{
TotalAmount = 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 = GoCardless.Services.InstalmentScheduleCreateWithDatesRequest.InstalmentScheduleCurrency.GBP,
Name = "ACME Invoice 103",
Instalments = new InstalmentScheduleInstalments[]
{
new InstalmentScheduleInstalments
{
ChargeDate = "2019-08-20",
Amount = 3400,
},
new InstalmentScheduleInstalments
{
ChargeDate = "2019-09-03",
Amount = 3400
},
new InstalmentScheduleInstalments
{
ChargeDate = "2019-09-17",
Amount = 3200
},
},
Links = new GoCardless
.Services
.InstalmentScheduleCreateWithDatesRequest
.InstalmentScheduleLinks
{
Mandate = "MD0000XH9A3T4C"
},
Metadata = new Dictionary<string, string>
{
{"Invoice ID", "001"}
},
IdempotencyKey = "random_instalment_schedule_specific_string"
}
);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
instalmentScheduleCreateWithDatesParams := gocardless.InstalmentScheduleCreateWithDatesParams{
TotalAmount: 10000,
AppFee: 10,
Currency: "GBP",
Instalments: []gocardless.InstalmentScheduleCreateWithDatesParamsInstalments{
{
Amount: 3400,
ChargeDate: "2019-08-20",
},
{
Amount: 3400,
ChargeDate: "2019-09-03",
},
{
Amount: 3400,
ChargeDate: "2019-09-17",
},
},
Links: gocardless.InstalmentScheduleCreateWithDatesParamsLinks{
Mandate: "MD123",
},
Metadata: map[string]interface{}{"invoiceId": "001"},
}
requestOption := gocardless.WithIdempotencyKey("random_instalment_schedule_specific_string")
instalmentSchedule, err := client.InstalmentSchedules().CreateWithDates(context, instalmentScheduleCreateWithDatesParams, requestOption)
}
Create (with schedule)
Creates a new instalment schedule object, along with the associated payments. This API is recommended if you wish to use the GoCardless scheduling logic. For finer control over the individual dates, please check out the alternative version.
It can take quite a while to create the associated payments, so the API will return
the status as pending
initially. When processing has completed, a subsequent
GET request for the instalment schedule will either have the status success
and link to
the created payments, or the status error
and detailed information about the
failures.
Relative endpoint: POST /instalment_schedules
Parameters
currency
- required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
instalments
[amounts] - required List of amounts of each instalment, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
instalments
[interval] -
required Number of
interval_units
between charge dates. Must be greater than or equal to1
. instalments
[interval_ unit] -
required The unit of time between customer charge dates. One of
weekly
,monthly
oryearly
. instalments
[start_ date] - The date on which the first payment should be charged. Must be on or after the mandate’s
next_possible_charge_date
. When left blank andmonth
orday_of_month
are provided, this will be set to the date of the first payment. If created withoutmonth
orday_of_month
this will be set as the mandate’snext_possible_charge_date
name
- required Name of the instalment schedule, up to 100 chars. This name will also be copied to the payments of the instalment schedule if you use schedule-based creation.
total_
amount - required The total amount of the instalment schedule, defined as the sum of all individual payments, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). If the requested payment amounts do not sum up correctly, a validation error will be returned.
app_
fee - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.
payment_
reference - An optional reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. 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, Pro or Enterprise packages. Restricted: You can not specify a payment reference for Faster Payments. retry_
if_ possible - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. links
[mandate] - required ID of the associated mandate which the instalment schedule will create payments against.
POST https://api.gocardless.com/instalment_schedules HTTP/1.1
Content-Type: application/json
{
"instalment_schedules": {
"name": "Bike Invoice 271",
"currency": "GBP",
"total_amount": "2500",
"instalments": {
"start_date": "2019-12-14",
"interval_unit": "monthly",
"interval": 1,
"amounts": [
"1500",
"1000"
]
},
"metadata": {},
"links": {
"mandate": "MD123"
}
}
}
HTTP/1.1 201 Created
Location: /instalment_schedules/IS123
Content-Type: application/json
{
"instalment_schedules": {
"id": "IS123",
"status": "pending",
"total_amount": "2500",
"metadata": {},
"payment_errors": {},
"links": {
"mandate": "MD123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'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",
"instalments" => [
"start_date" => "2019-08-20",
"interval_unit" => "weekly",
"interval" => 2,
"amounts" => [
3400,
3400,
3200
]
],
"links" => [
"mandate" => "MD0000XH9A3T4C"
],
"metadata" => []
],
"headers" => [
"Idempotency-Key" => "random_instalment_schedule_specific_string"
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
instalment_schedule = client.instalment_schedules.create_with_schedule(
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": {
"start_date": "2019-08-20",
"interval_unit": "weekly",
"interval": 2,
"amounts": [
3400,
3400,
3200
]
}
"links": {
"mandate": "MD0000XH9A3T4C"
},
"metadata": {}
}, headers={
"Idempotency-Key": "random_instalment_schedule_specific_string"
}
)
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
instalment_schedule = @client.instalment_schedules.create_with_schedule(
params: {
name: 'ACME Invoice 103',
total_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: {
start_date: '2019-08-20',
interval_unit: 'weekly',
interval: 2,
amounts: [
3_400,
3_400,
3_200
]
}
links: {
mandate: 'MD0000XH9A3T4C'
},
metadata: {}
},
headers: {
'Idempotency-Key': 'random_instalment_schedule_specific_string'
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
int[] amountsArray = {3400, 3400, 3200};
InstalmentSchedule instalmentSchedule = client.instalmentSchedules().createWithSchedule()
.withTotalAmount(10000) // 100 GBP in Pence, collected from the customer.
.withAppFee(10) // Your 10 pence fee, applied to each instalment, to be
// paid out to you
.withCurrency("GBP")
.withIntervalUnit(IntervalUnit.WEEKLY)
.withInterval(2)
.withAmounts(amountsArray)
.withLinksMandate("MD0000YTKZKY4J")
.withMetadata("invoiceId", "001")
.withIdempotencyKey("random_instalment_schedule_specific_string")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const instalmentSchedule = await client.instalmentSchedules.createWithSchedule(
{
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: {
start_date: "2019-08-20",
interval_unit: "weekly",
interval: 2,
amounts: [
3400,
3400,
3200
]
}
links: {
mandate: "MD0000XH9A3T4C"
},
metadata: {}
},
"instalment_schedule_idempotency_key"
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
int?[] amountsArray = new int?[]{ 3400, 3400, 3200 };
var createResponse = await gocardless.InstalmentSchedules.CreateWithScheduleAsync(
new InstalmentScheduleCreateWithScheduleRequest
{
TotalAmount = 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 = GoCardless.Services.InstalmentScheduleCreateWithScheduleRequest.InstalmentScheduleCurrency.GBP,
Name = "ACME Invoice 103",
Instalments = new GoCardless
.Services
.InstalmentScheduleCreateWithScheduleRequest
.InstalmentScheduleInstalments
{
StartDate = "2019-08-20",
IntervalUnit = InstalmentScheduleCreateWithScheduleRequest.InstalmentScheduleInstalments.InstalmentScheduleIntervalUnit.Weekly,
Interval = 2,
Amounts = amountsArray
},
Metadata = new Dictionary<string, string>
{
{"Invoice ID", "001"}
},
Links = new GoCardless
.Services
.InstalmentScheduleCreateWithScheduleRequest
.InstalmentScheduleLinks
{
Mandate = "MD0000XH9A3T4C"
},
IdempotencyKey = "random_instalment_schedule_specific_string"
}
);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
instalmentScheduleCreateWithScheduleParams := gocardless.InstalmentScheduleCreateWithScheduleParams{
TotalAmount: 10000,
AppFee: 10,
Currency: "GBP",
Instalments: gocardless.InstalmentScheduleCreateWithScheduleParamsInstalments{
Interval: 2,
IntervalUnit: "monthly",
Amounts: []int{3400, 3400, 3200},
},
Metadata: map[string]interface{}{"invoiceId": "001"},
}
requestOption := gocardless.WithIdempotencyKey("random_instalment_schedule_specific_string")
instalmentSchedule, err := client.InstalmentSchedules().CreateWithSchedule(context, instalmentScheduleCreateWithScheduleParams, requestOption)
}
List instalment schedules
Returns a cursor-paginated list of your instalment schedules.
Relative endpoint: GET /instalment_schedules
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
customer
- ID of the associated customer.
limit
- Number of records to return.
mandate
- ID of the associated mandate which the instalment schedule will create payments against.
status
- At most five valid status values
GET https://api.gocardless.com/instalment_schedules?after=IS123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": "IS000",
"after": "IS456",
},
"limit": 50
},
"instalment_schedules": [{
"id": "IS123",
"name": "Bike Invoice 271",
"currency": "GBP",
"status": "active",
"total_amount": "2500",
"metadata": {},
"payment_errors": {},
"links": {
"mandate": "MD123",
"payments": ["PM123", "PM345"],
"customer": "CU123"
}
}, {
"id": "IS456",
"name": "INV-7465",
"currency": "GBP",
"status": "cancelled",
"total_amount": "3600",
"metadata": {},
"payment_errors": {},
"links": {
"mandate": "MD456",
"payments": ["PM567", "PM789"],
"customer": "CU456"
}
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->instalmentSchedules()->list();
$client->instalmentSchedules()->list([
"params" => ["created_at[gt]" => "2015-11-03T09:30:00Z"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.instalment_schedules.list().records
client.instalment_schedules.list(params={"after": "IS123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.instalment_schedules.list
@client.instalment_schedules.list(
params: {
"created_at[gt]" => "2016-08-06T09:30:00Z"
}
)
@client.instalment_schedules.list.records.each do |instalment_schedule|
puts instalment_schedule.inspect
end
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (InstalmentSchedule instalmentSchedule : client.instalmentSchedules().all().execute()) {
System.out.println(instalmentSchedule.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const instalmentSchedules = await client.instalmentSchedules.list();
// List all instalment schedules associated with a given customer.
const instalmentSchedules = await client.instalmentSchedules.list({ customer: "CU123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var instalmentScheduleListResponse = gocardless.InstalmentSchedules.All();
foreach (GoCardless.Resources.InstalmentSchedule instalmentSchedule in instalmentScheduleListResponse)
{
Console.WriteLine(instalmentSchedule.Name);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
instalmentScheduleListParams := gocardless.InstalmentScheduleListParams{}
instalmentScheduleListResult, err := client.InstalmentSchedules.List(context, instalmentScheduleListParams)
for _, instalmentSchedule := range instalmentScheduleListResult.InstalmentSchedules {
fmt.Println(instalmentSchedule.Name)
}
}
Get a single instalment schedule
Retrieves the details of an existing instalment schedule.
Relative endpoint: GET /instalment_schedules/IS123
GET https://api.gocardless.com/instalment_schedules/IS123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"instalment_schedules": {
"id": "IS123",
"name": "INV-4142",
"currency": "GBP",
"status": "active",
"total_amount": "2500",
"metadata": {},
"payment_errors": {},
"links": {
"mandate": "MD456",
"payments": ["PM123", "PM345"],
"customer": "CU456"
}
}
}
{
"instalment_schedules": {
"id": "IS123",
"name": "INV-4142",
"currency": "GBP",
"status": "creation_failed",
"total_amount": "2500",
"metadata": {},
"payment_errors": {
"0": { "field": "description", "message": "was too long" },
"1": {}
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->instalmentSchedules()->get("IS123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.instalment_schedules.get("IS123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.instalment_schedules.get("IS123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
InstalmentSchedule instalmentSchedule = client.instalmentSchedules().get("IS123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const instalmentSchedule = await client.instalmentSchedules.find("IS123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var instalmentScheduleResponse = await gocardless.InstalmentSchedules.GetAsync("IS123");
GoCardless.Resources.Customer instalmentSchedule = instalmentScheduleResponse.InstalmentSchedule;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
instalmentSchedule, err := client.InstalmentSchedules.Get(context, "IS123")
}
Update an instalment schedule
Updates an instalment schedule. This accepts only the metadata parameter.
Relative endpoint: PUT /instalment_schedules/IS123
Parameters
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.
PUT https://api.gocardless.com/instalment_schedules/IS123 HTTP/1.1
Content-Type: application/json
{
"instalment_schedules": {
"metadata": {
"key": "value"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"instalment_schedules": {
"id": "IS123",
"name": "INV-4142",
"currency": "GBP",
"status": "active",
"total_amount": "2500",
"metadata": {
"key": "value"
},
"payment_errors": {},
"links": {
"mandate": "MD456",
"payments": ["PM123", "PM345"],
"customer": "CU456"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->instalmentSchedules()->update("IS123", [
"params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.instalment_schedules.update("IS123", params={
"metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.instalment_schedules.update(
"IS123",
params: {
metadata: { key: "value" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.instalmentSchedules().update("IS123")
.withMetadata("key", "value")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const instalmentSchedule = await client.instalmentSchedules.update(
"IS123",
{
metadata: {
key: "value"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var instalmentScheduleRequest = new GoCardless.Services.InstalmentScheduleUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"key", "value"}
}
};
var instalmentScheduleResponse = await gocardless.InstalmentSchedules.UpdateAsync("IS123", instalmentScheduleRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
instalmentScheduleUpdateParams := gocardless.InstalmentScheduleUpdateParams{
Metadata: map[string]interface{"key": "value"}
}
instalmentSchedule, err := client.InstalmentSchedules.Update(context, "IS123", instalmentScheduleUpdateParams)
}
Cancel an instalment schedule
Immediately cancels an instalment schedule; no further payments will be collected for it.
This will fail with a cancellation_failed
error if the instalment schedule is already cancelled or has completed.
Relative endpoint: POST /instalment_schedules/IS123/actions/cancel
Parameters
POST https://api.gocardless.com/instalment_schedules/IS123/actions/cancel HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"instalment_schedules": {
"id": "IS123",
"name": "Bike Invoice 271",
"currency": "GBP",
"status": "cancelled",
"total_amount": "2500",
"metadata": {},
"payment_errors": {},
"links": {
"mandate": "MD123",
"payments": ["PM123", "PM345"],
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->instalmentSchedules()->cancel("IS123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.instalment_schedules.cancel("IS123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.instalment_schedules.cancel("IS123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.instalmentSchedules().cancel("IS123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const instalmentScheduleResponse = await client.instalmentSchedules.cancel("IS123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var response = await gocardless.InstalmentSchedules.CancelAsync("IS123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
instalmentScheduleCancelParams = make(map[string]interface)
instalmentSchedule, err := client.InstalmentSchedules.Cancel(context, "IS123", instalmentScheduleCancelParams)
}
Logos
Logos are image uploads that, when associated with a creditor, are shown on the billing request flow payment pages.
Properties
id
- Unique identifier, beginning with “LO”.
Create a logo associated with a creditor
Creates a new logo associated with a creditor. If a creditor already has a logo, this will update the existing logo linked to the creditor.
We support JPG and PNG formats. Your logo will be scaled to a maximum of 300px by 40px. For more guidance on how to upload logos that will look great across your customer payment page and notification emails see here.
Relative endpoint: POST /branding/logos
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
Parameters
image
- required Base64 encoded string.
links
[creditor] - ID of the creditor the logo belongs to
POST https://api.gocardless.com/branding/logos HTTP/1.1
Content-Type: application/json
{
"logos": {
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 201 OK
Content-Type: application/json
{
"logos": {
"id": "LO123"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->logos()->createForCreditor([
"params" => [
"image" => "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
"links" => [
"creditor" => "CR123"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.logos.create_for_creditor(params={
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
"links": {
"creditor": "CR123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.logos.create_for_creditor(
params: {
image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
links: {
creditor: "CR123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Logo logo = client.logos().createForCreditor()
.withImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA")
.withLinksCreditor("CR123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const logo = await client.logos.createForCreditor({
image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
links: {
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var logoCreateForCreditorRequest = new GoCardless.Services.LogoCreateForCreditorRequest()
{
Image = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
Links = new GoCardless.Services.LogoCreateForCreditorRequest.LogoLinks()
{
Creditor = "CR0123"
}
};
var logoCreateForCreditorResponse = await gocardless.Logos.CreateForCreditorAsync(logoCreateForCreditorRequest);
GoCardless.Resources.Logo creditorLogo = logoCreateForCreditorResponse.LogoResponse;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
logoCreateForCreditorParams := gocardless.LogoCreateForCreditorParams{
Image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA",
Links: gocardless.LogoCreateForCreditorParamsLinks{
Creditor: "CR123"
}
}
logo, err := client.Logos.CreateForCreditor(context, logoCreateForCreditorParams)
}
Mandates
Mandates represent the Direct Debit mandate with a customer.
GoCardless will notify you via a webhook whenever the status of a mandate changes.
Properties
id
- Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
authorisation_
source - This field is ACH specific, sometimes referred to as SEC code.
This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)
consent_
parameters [end_ date] - The latest date at which payments can be taken, must occur after start_date if present
consent_
parameters [max_ amount_ per_ payment] - The maximum amount that can be charged for a single payment
periods
- Frequency configuration
Each instance will contain these properties:
-
max_amount_per_period
: The maximum total amount that can be charged for all payments in this period -
max_payments_per_period
: The maximum number of payments that can be collected in this period -
period
: The repeating period for this mandate
-
consent_
parameters [start_ date] - The date from which payments can be taken
consent_
type - (Optional) Specifies the type of authorisation agreed between the payer and merchant. It can be set to one-off, recurring or standing for ACH, or single, recurring and sporadic for PAD.
created_
at - Fixed timestamp, recording when this resource was created.
funds_
settlement - This field will decide how GoCardless handles settlement of funds from the customer.
-
managed
will be moved through GoCardless’ account, batched, and payed out. -
direct
will be a direct transfer from the payer’s account to the merchant where invoicing will be handled separately.
-
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.
next_
possible_ charge_ date - The earliest date that can be used as a
charge_date
on any newly created payment for this mandate. This value will change over time. next_
possible_ standard_ ach_ charge_ date - If this is an an ACH mandate, the earliest date that can be used as a
charge_date
on any newly created payment to be charged through standard ACH, rather than Faster ACH. This value will change over time.It is only present in the API response for ACH mandates.
payments_
require_ approval - Boolean value showing whether payments and subscriptions under this mandate require approval via an automated email before being processed.
reference
- Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
scheme
- Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer’s bank account.
status
- One of:
-
pending_customer_approval
: the mandate has not yet been signed by the second customer -
pending_submission
: the mandate has not yet been submitted to the customer’s bank -
submitted
: the mandate has been submitted to the customer’s bank but has not been processed yet -
active
: the mandate has been successfully set up by the customer’s bank -
suspended_by_payer
: the mandate has been suspended by payer -
failed
: the mandate could not be created -
cancelled
: the mandate has been cancelled -
expired
: the mandate has expired due to dormancy -
consumed
: the mandate has been consumed and cannot be reused (note that this only applies to schemes that are per-payment authorised) -
blocked
: the mandate has been blocked and payments cannot be created
-
verified_
at - Timestamp recording when this mandate was verified.
links
[creditor] - ID of the associated creditor.
links
[customer] - ID of the associated customer
links
[customer_ bank_ account] - ID of the associated customer bank account which the mandate is created and submits payments against.
links
[new_ mandate] - ID of the new mandate if this mandate has been replaced.
Create a mandate
Creates a new mandate object.
Relative endpoint: POST /mandates
Note: this endpoint is a legacy API endpoint and does not support GoCardless’ newest features. We recommend using the Billing Requests API instead.
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.
Warning: by default, the ability to provide a custom mandate reference is switched off. The banking system rules for valid references are quite complex, and we recommend allowing GoCardless to generate it. If you would like to provide custom references, please contact support.
Parameters
authorisation_
source - This field is ACH specific, sometimes referred to as SEC code.
This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD)
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.
payer_
ip_ address - For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
Not required for creating offline mandates where
authorisation_source
is set to telephone or paper. reference
- Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
scheme
- Bank payment scheme to which this mandate and associated payments are submitted. Can be supplied or automatically detected from the customer’s bank account.
links
[creditor] - ID of the associated creditor. Only required if your account manages multiple creditors.
links
[customer_ bank_ account] - required ID of the associated customer bank account which the mandate is created and submits payments against.
POST https://api.gocardless.com/mandates HTTP/1.1
Content-Type: application/json
{
"mandates": {
"scheme": "bacs",
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123"
}
}
}
HTTP/1.1 201 Created
Location: /mandates/MD123
Content-Type: application/json
{
"mandates": {
"id": "MD123",
"created_at": "2014-05-08T17:01:06.000Z",
"reference": "REF-123",
"status": "pending_submission",
"scheme": "bacs",
"next_possible_charge_date": "2014-11-10",
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandates()->create([
"params" => ["scheme" => "bacs",
"metadata" => ["contract" => "ABCD1234"],
"links" => ["customer_bank_account" => "BA123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandates.create(params={
"scheme": "bacs",
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandates.create(
params: {
scheme: "bacs",
links: {
customer_bank_account: "BA123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Mandate mandate = client.mandates().create()
.withScheme("bacs")
.withLinksCustomerBankAccount("BA123")
.withMetadata("contract", "ABCD1234")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandate = await client.mandates.create({
scheme: "bacs",
metadata: {
contract: "ABCD1234"
},
links: {
customer_bank_account: "BA123",
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandateRequest = new GoCardless.Services.MandateCreateRequest()
{
Links = new GoCardless.Services.MandateCreateRequest.MandateLinks()
{
CustomerBankAccount = "BA0123"
},
Metadata = new Dictionary<string, string>()
{
{"internal_reference", "ref_09011991"}
},
Scheme = "bacs"
};
var mandateResponse = await gocardless.Mandates.CreateAsync(mandateRequest);
GoCardless.Resources.Mandate mandate = mandateResponse.Mandate;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateCreateParams := gocardless.MandateCreateParams{
Scheme: "bacs",
Links: gocardless.MandateCreateParamsLinks{
CustomerBankAccount: "BA123",
Creditor: "CR123",
},
Metadata: map[string]interface{}{"contract": "ABCD1234"},
}
mandate, err := client.Mandates().Create(context, mandateCreateParams)
}
List mandates
Returns a cursor-paginated list of your mandates.
Relative endpoint: GET /mandates
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
creditor
- ID of a creditor. If specified, this endpoint will return all mandates for the given creditor. Cannot be used in conjunction with
customer
orcustomer_bank_account
customer
- ID of a customer. If specified, this endpoint will return all mandates for the given customer. Cannot be used in conjunction with
customer_bank_account
orcreditor
customer_
bank_ account - ID of a customer bank account. If specified, this endpoint will return all mandates for the given bank account. Cannot be used in conjunction with
customer
orcreditor
limit
- Number of records to return.
mandate_
type - Mandate type
reference
- Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
scheme
- Scheme you’d like to retrieve mandates for
status
- At most four valid status values
GET https://api.gocardless.com/mandates HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"mandates": [{
"id": "MD123",
"created_at": "2014-05-08T17:01:06.000Z",
"reference": "REF-123",
"status": "pending_submission",
"scheme": "bacs",
"mandate_type": "bank_debit",
"next_possible_charge_date": "2014-11-10",
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123",
"customer": "CU123"
}
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandates()->list();
$client->mandates()->list([
"params" => ["customer" => "CU123"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandates.list().records
client.mandates.list(params={"customer": "CU123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandates.list
@client.mandates.list(params: { customer: "CU123" })
@client.mandates.list.records.each { |mandate| puts mandate.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Mandate mandate : client.mandates().all().withCustomer("CU123").execute()) {
System.out.println(mandate.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandates = await client.mandates.list();
// List all mandates associated with a given customer.
const mandates = await client.mandates.list({ customer: "CU123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandateRequest = new GoCardless.Services.MandateListRequest()
{
Customer = "CU000123"
};
var mandateListResponse = gocardless.Mandates.All(mandateRequest);
foreach (GoCardless.Resources.Mandate mandate in mandateListResponse)
{
Console.WriteLine(mandate.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateListParams := gocardless.MandateListParams{
Customer: "CU123",
}
mandateListResult, err := client.Mandates.List(context, mandateListParams)
for _, mandate := mandateListResult.Mandates {
fmt.Println(mandate.Id)
}
}
Get a single mandate
Retrieves the details of an existing mandate.
Relative endpoint: GET /mandates/MD123
GET https://api.gocardless.com/mandates/MD123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandates": {
"id": "MD123",
"created_at": "2014-05-08T17:01:06.000Z",
"reference": "REF-123",
"status": "pending_submission",
"scheme": "bacs",
"mandate_type": "bank_debit",
"next_possible_charge_date": "2014-11-10",
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandates()->get("MD123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandates.get("MD123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandates.get("MD123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Mandate mandate = client.mandates().get("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandate = await client.mandates.find("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandateResponse = await gocardless.Mandates.GetAsync("MD0123");
GoCardless.Resources.Mandate mandate = mandateResponse.Mandate;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandate, err := client.Mandates.Get(context, "MD123")
}
Update a mandate
Updates a mandate object. This accepts only the metadata parameter.
Relative endpoint: PUT /mandates/MD123
Parameters
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.
PUT https://api.gocardless.com/mandates/MD123 HTTP/1.1
Content-Type: application/json
{
"mandates": {
"metadata": {
"key": "value"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandates": {
"id": "MD123",
"created_at": "2014-05-08T17:01:06.000Z",
"reference": "REF-123",
"status": "pending_submission",
"scheme": "bacs",
"next_possible_charge_date": "2014-11-10",
"metadata": {
"key": "value"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandates()->update("MD123", [
"params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandates.update("MD123", params={
"metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandates.update(
"MD123",
params: {
metadata: { contract_id: "ref_09011991" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.mandates().update("MD123").withMetadata("contract_id", "ref_09011991").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandate = await client.mandates.update(
"MD123",
{
metadata: {"key": "value"}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandateRequest = new GoCardless.Services.MandateUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"internal_reference", "ref_09011991"}
}
};
var mandateResponse = await gocardless.Mandates.UpdateAsync("MD0123", mandateRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateUpdateParams := gocardless.MandateUpdateParams{
Metadata: map[string]interface{}{"key": "value"},
}
mandate, err := client.Mandates.Update(context, "MD123", mandateUpdateParams)
}
Cancel a mandate
Immediately cancels a mandate and all associated cancellable payments. Any metadata supplied to this endpoint will be stored on the mandate cancellation event it causes.
This will fail with a cancellation_failed
error if the mandate is already cancelled.
Relative endpoint: POST /mandates/MD123/actions/cancel
Parameters
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.
POST https://api.gocardless.com/mandates/MD123/actions/cancel HTTP/1.1
Content-Type: application/json
{
"data": {
"metadata": {}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandates": {
"id": "MD123",
"created_at": "2014-05-08T17:01:06.000Z",
"reference": "REF-123",
"status": "cancelled",
"scheme": "bacs",
"next_possible_charge_date": null,
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandates()->cancel("MD123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandates.cancel("MD123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandates.cancel("MD123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.mandates().cancel("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateResponse = await client.mandates.cancel("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandateResponse = await gocardless.Mandates.CancelAsync("MD0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateCancelParams := gocardless.MandateCancelParams{}
mandate, err := client.Mandates.Cancel(context, "MD123", mandateCancelParams)
}
Reinstate a mandate
Reinstates a cancelled or expired mandate to the banks. You will receive a resubmission_requested
webhook, but after that reinstating the mandate follows the same process as its initial creation, so you will receive a submitted
webhook, followed by a reinstated
or failed
webhook up to two working days later. Any metadata supplied to this endpoint will be stored on the resubmission_requested
event it causes.
This will fail with a mandate_not_inactive
error if the mandate is already being submitted, or is active.
Mandates can be resubmitted up to 10 times.
Relative endpoint: POST /mandates/MD123/actions/reinstate
Restricted: this endpoint is restricted to accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.
Warning: A mandate can only be reinstated if it has been cancelled through the dashboard or the API. Any mandate that has been cancelled by the bank cannot be reinstated.
Parameters
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.
POST https://api.gocardless.com/mandates/MD123/actions/reinstate HTTP/1.1
Content-Type: application/json
{
"data": {
"metadata": {
"ticket_id": "TK123"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandates": {
"id": "MD123",
"created_at": "2014-05-08T17:01:06.000Z",
"reference": "REF-123",
"status": "submitted",
"scheme": "bacs",
"next_possible_charge_date": "2014-11-10",
"metadata": {
"contract": "ABCD1234"
},
"links": {
"customer_bank_account": "BA123",
"creditor": "CR123",
"customer": "CU123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandates()->reinstate("MD123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandates.reinstate("MD123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandates.reinstate("MD123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.mandates().reinstate("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateResponse = await client.mandates.reinstate("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandateResponse = await gocardless.Mandates.ReinstateAsync("MD0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateReinstateParams := gocardless.MandateReinstateParams{}
mandate, err := client.Mandates.Reinstate(context, "MD123", mandateReinstateParams)
}
Mandate Imports
Mandate Imports allow you to migrate existing mandates from other providers into the GoCardless platform.
The process is as follows:
- Create a mandate import
- Add entries to the import
- Submit the import
- Wait until a member of the GoCardless team approves the import, at which point the mandates will be created
- Link up the mandates in your system
When you add entries to your mandate import, they are not turned into actual mandates until the mandate import is submitted by you via the API, and then processed by a member of the GoCardless team. When that happens, a mandate will be created for each entry in the import.
We will issue a mandate_created
webhook for each entry, which will be the same as the webhooks
triggered when creating a mandate using the mandates API. Once these
webhooks start arriving, any reconciliation can now be accomplished by
checking the current status of the mandate import and
linking up the mandates to your system.
Note that all Mandate Imports have an upper limit of 30,000 entries, so we recommend you split your import into several smaller imports if you’re planning to exceed this threshold.
Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.
Properties
id
- Unique identifier, beginning with “IM”.
created_
at - Fixed timestamp, recording when this resource was created.
scheme
- The scheme of the mandates to be imported.
All mandates in a single mandate import must be for the same scheme. status
- The status of the mandate import.
-
created
: A new mandate import. -
submitted
: After the integrator has finished adding mandates and submitted the import. -
cancelled
: If the integrator cancelled the mandate import. -
processing
: Once a mandate import has been approved by a GoCardless team member it will be in this state while mandates are imported. -
processed
: When all mandates have been imported successfully.
-
links
[creditor] - ID of the associated creditor.
Create a new mandate import
Mandate imports are first created, before mandates are added one-at-a-time, so this endpoint merely signals the start of the import process. Once you’ve finished adding entries to an import, you should submit it.
Relative endpoint: POST /mandate_imports
Parameters
scheme
- required A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported.
links
[creditor] - ID of the associated creditor. Only required if your account manages multiple creditors.
POST https://api.gocardless.com/mandate_imports HTTP/1.1
Content-Type: application/json
{
"mandate_imports": {
"scheme": "bacs"
}
}
HTTP/1.1 201 Created
Location: /mandate_imports/IM000010790WX1
Content-Type: application/json
{
"mandate_imports": {
"id": "IM000010790WX1",
"scheme": "bacs",
"status": "created",
"created_at": "2018-03-12T14:03:04.000Z",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandateImports()->create([
"params" => ["scheme" => "bacs"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_imports.create(params={
"scheme": "bacs"
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_imports.create(params: {
scheme: "bacs"
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
MandateImport import = client.mandateImports().create()
.withScheme(com.gocardless.services.MandateImportService.MandateImportCreateRequest.Scheme.BACS)
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateImport = await client.mandateImports.create({
scheme: "bacs"
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var importRequest = new GoCardless.Services.MandateImportCreateRequest()
{
Scheme = MandateImportCreateRequest.MandateImportScheme.Bacs
};
var importResponse = await gocardless.MandateImports.CreateAsync(importRequest);
GoCardless.Resources.MandateImport import = importResponse.MandateImport;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateImportCreateParams := gocardless.MandateImportCreateParams{
Scheme: "bacs",
}
mandateImport, err := client.MandateImports.Create(context, mandateImportCreateParams)
}
Get a mandate import
Returns a single mandate import.
Relative endpoint: GET /mandate_imports/IM000010790WX1
Parameters
GET https://api.gocardless.com/mandate_imports/IM000010790WX1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_imports": {
"id": "IM000010790WX1",
"scheme": "bacs",
"status": "created",
"created_at": "2018-03-12T14:03:04.000Z",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandateImports()->get("IM000010790WX1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_imports.get("IM000010790WX1")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_imports.get("IM000010790WX1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
MandateImport import = client.mandateImports().get("IM000010790WX1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateImport = await client.mandateImports.find("IM000010790WX1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var response = await gocardless.MandateImports.GetAsync("IM000010790WX1");
GoCardless.Resources.MandateImport import = response.MandateImport;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateImport, err := client.MandateImports.Get("IM000010790WX1")
}
Submit a mandate import
Submits the mandate import, which allows it to be processed by a member of the GoCardless team. Once the import has been submitted, it can no longer have entries added to it.
In our sandbox environment, to aid development, we automatically process mandate imports approximately 10 seconds after they are submitted. This will allow you to test both the “submitted” response and wait for the webhook to confirm the processing has begun.
Relative endpoint: POST /mandate_imports/IM000010790WX1/actions/submit
Parameters
POST https://api.gocardless.com/mandate_imports/IM000010790WX1/actions/submit HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_imports": {
"id": "IM000010790WX1",
"scheme": "bacs",
"status": "submitted",
"created_at": "2018-03-12T14:03:04.000Z",
"links": {
"creditor": "CR123"
}
}
}
POST https://api-sandbox.gocardless.com/mandate_imports/IM000010790WX1/actions/submit HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_imports": {
"id": "IM000010790WX1",
"scheme": "bacs",
"status": "processing",
"created_at": "2018-03-12T14:03:04.000Z",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandateImports()->submit("IM000010790WX1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_imports.submit("IM000010790WX1")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_imports.submit("IM000010790WX1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.mandateImports().submit("IM000010790WX1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateImport = await client.mandateImports.submit("IM000010790WX1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var response = await gocardless.MandateImports.SubmitAsync("IM000010790WX1");
GoCardless.Resources.MandateImport import = response.MandateImport;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateImportSubmitParams := map[string]interface{}
mandateImport, err := client.MandateImports.Submit(context, "IM000010790WX1", mandateImportSubmitParams)
}
Cancel a mandate import
Cancels the mandate import, which aborts the import process and stops the mandates being set up in GoCardless. Once the import has been cancelled, it can no longer have entries added to it. Mandate imports which have already been submitted or processed cannot be cancelled.
Relative endpoint: POST /mandate_imports/IM000010790WX1/actions/cancel
Parameters
POST https://api.gocardless.com/mandate_imports/IM000010790WX1/actions/cancel HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_imports": {
"id": "IM000010790WX1",
"scheme": "bacs",
"status": "cancelled",
"created_at": "2018-03-12T14:03:04.000Z",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandateImports()->cancel("IM000010790WX1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_imports.cancel("IM000010790WX1")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_imports.cancel("IM000010790WX1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.mandateImports().cancel("IM000010790WX1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateImportResponse = await client.mandateImports.cancel("IM000010790WX1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var response = await gocardless.MandateImports.CancelAsync("IM000010790WX1");
GoCardless.Resources.MandateImport import = response.MandateImport;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateImportCancelParams := make(map[string]interface)
mandateImport, err := client.MandateImports.Cancel(context, "IM000010790WX1", mandateImportCancelParams)
}
Mandate Import Entries
Mandate Import Entries are added to a Mandate Import. Each entry corresponds to one mandate to be imported into GoCardless.
To import a mandate you will need:
- Identifying information about the customer (name/company and address)
- Bank account details, consisting of an account holder name and either an IBAN or local bank details
- Amendment details (SEPA only)
We suggest you provide a record_identifier
(which is unique within the context of a
single mandate import) to help you to identify mandates that have been created once the
import has been processed by GoCardless. You can
list the mandate import entries,
match them up in your system using the record_identifier
, and look at the links
fields to find the mandate, customer and customer bank account that have been imported.
Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.
Properties
created_
at - Fixed timestamp, recording when this resource was created.
record_
identifier - A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.
links
[customer] - The ID of the customer which was created when the mandate import was processed.
links
[customer_ bank_ account] - The ID of the customer bank account which was created when the mandate import was processed.
links
[mandate] - The ID of the mandate which was created when the mandate import was processed.
links
[mandate_ import] - The ID of the mandate import. This is returned when you create a Mandate Import.
Add a mandate import entry
For an existing mandate import, this endpoint can be used to add individual mandates to be imported into GoCardless.
You can add no more than 30,000 rows to a single mandate import.
If you attempt to go over this limit, the API will return a record_limit_exceeded
error.
Relative endpoint: POST /mandate_import_entries
Parameters
bank_
account [account_ holder_ name] - required Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
bank_
account [account_ number] - Bank account number - see local details for more information. Alternatively you can provide an
iban
. bank_
account [account_ type] - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
account [bank_ code] - Bank code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [branch_ code] - Branch code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [country_ code] -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. bank_
account [iban] - International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_
account [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.
customer
[address_ line1] - The first line of the customer’s address. Required if mandate import scheme is either
bacs
orsepa
. customer
[address_ line2] - The second line of the customer’s address.
customer
[address_ line3] - The third line of the customer’s address.
customer
[city] - The city of the customer’s address.
customer
[company_ name] - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). customer
[country_ code] - ISO 3166-1 alpha-2 code.
customer
[danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer
[email] - Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer
[family_ name] - Customer’s surname. Required unless a
company_name
is provided. customer
[given_ name] - Customer’s first name. Required unless a
company_name
is provided. customer
[language] -
ISO 639-1 code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see compliance requirements). Currently only “en”, “fr”, “de”, “pt”, “es”, “it”, “nl”, “da”, “nb”, “sl”, “sv” are supported. If this is not provided, the language will be chosen based on the
country_code
(if supplied) or default to “en”. customer
[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.
customer
[phone_ number] - ITU E.123 formatted phone number, including country code.
customer
[postal_ code] - The customer’s postal code. Required if mandate import scheme is either
bacs
orsepa
. customer
[region] - The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). customer
[swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
amendment
[original_ creditor_ id] - The creditor identifier of the direct debit originator. Required if mandate
import scheme is
sepa
. amendment
[original_ creditor_ name] - Data about the original mandate to be moved or modified.
amendment
[original_ mandate_ reference] - The unique SEPA reference for the mandate being amended. Required if mandate
import scheme is
sepa
. mandate
[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.
mandate
[reference] - Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
record_
identifier - A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters.
links
[mandate_ import] - required Unique identifier, beginning with “IM”.
POST https://api.gocardless.com/mandate_import_entries HTTP/1.1
Content-Type: application/json
{
"mandate_import_entries": {
"links": {
"mandate_import": "IM000010790WX1"
},
"record_identifier": "bank-file.xml/line-1",
"customer": {
"company_name": "Jane's widgets",
"email": "jane@janeswidgets.fr"
},
"bank_account": {
"account_holder_name": "Jane Doe",
"iban": "FR14BARC20000055779911"
},
"amendment": {
"original_mandate_reference": "REFNMANDATE",
"original_creditor_id": "FR123OTHERBANK",
"original_creditor_name": "Existing DD Provider"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"mandate_import_entries": {
"record_identifier": "bank-file.xml/line-1",
"created_at": "2018-03-03T00:00:00Z",
"links": {
"mandate_import": "IM000010790WX1"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandateImportEntries()->create([
"params" => [
"links" => [
"mandate_import" => "IM000010790WX1"
],
"record_identifier" => "bank-file.xml/line-1",
"customer" => [
"company_name" => "Jane's widgets",
"email" => "jane@janeswidgets.fr"
],
"bank_account" => [
"account_holder_name" => "Jane Doe",
"iban" => "FR14BARC20000055779911"
],
"amendment" => [
"original_mandate_reference" => "REFNMANDATE",
"original_creditor_id" => "FR123OTHERBANK",
"original_creditor_name" => "Existing DD Provider"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_import_entries.create(params={
"links": {
"mandate_import": "IM000010790WX1"
},
"record_identifier": "bank-file.xml/line-1",
"customer": {
"company_name": "Jane's widgets",
"email": "jane@janeswidgets.fr"
},
"bank_account": {
"account_holder_name": "Jane Doe",
"iban": "FR14BARC20000055779911"
},
"amendment": {
"original_mandate_reference": "REFNMANDATE",
"original_creditor_id": "FR123OTHERBANK",
"original_creditor_name": "Existing DD Provider"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_import_entries.create(params: {
links: {
mandate_import: "IM000010790WX1"
},
record_identifier: "bank-file.xml/line-1",
customer: {
company_name: "Jane's widgets",
email: "jane@janeswidgets.fr"
},
bank_account: {
account_holder_name: "Jane Doe",
iban: "FR14BARC20000055779911"
},
amendment: {
original_mandate_reference: "REFNMANDATE",
original_creditor_id: "FR123OTHERBANK",
original_creditor_name: "Existing DD Provider"
}
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
MandateImport import = client.mandateImportEntries().create()
.withCustomerCompanyName("Jane's widgets")
.withCustomerEmail("jane@janeswidgets.fr")
.withBankAccountAccountHolderName("Jane Doe")
.withBankAccountIban("FR14BARC20000055779911")
.withAmendmentOriginalMandateReference("REFNMANDATE")
.withAmendmentOriginalCreditorId("FR123OTHERBANK")
.withAmendmentOriginalCreditorName("Existing DD Provider")
.withLinksMandateImport("IM000010790WX1")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateImportEntry = await client.mandateImportEntries.create({
links: {
mandate_import: "IM000010790WX1"
},
record_identifier: "bank-file.xml/line-1",
customer: {
company_name: "Jane's widgets",
email: "jane@janeswidgets.fr"
},
bank_account: {
account_holder_name: "Jane Doe",
iban: "FR14BARC20000055779911"
},
amendment: {
original_mandate_reference: "REFNMANDATE",
original_creditor_id: "FR123OTHERBANK",
original_creditor_name: "Existing DD Provider"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.MandateImportEntryCreateRequest()
{
Customer = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryCustomer()
{
CompanyName = "Jane's widgets"
Email = "jane@janeswidgets.fr"
}
BankAccount = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryBankAccount()
{
AccountHolderName = "Jane Doe"
Iban = "FR14BARC20000055779911"
}
Amendment = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryAmendment()
{
OriginalMandateReference = "REFNMANDATE"
OriginalCreditorId = "FR123OTHERBANK"
OriginalCreditorName = "Existing DD Provider"
}
Links = new GoCardless.Services.MandateImportEntryCreateRequest.MandateImportEntryLinks()
{
MandateImport = "IM000010790WX1"
}
};
var importResponse = await gocardless.MandateImportEntries.CreateAsync(request);
GoCardless.Resources.MandateImportEntry entry = importResponse.MandateImportEntry;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateImportEntryCreateParams := gocardless.MandateImportEntryCreateParams{
Customer: gocardless.MandateImportEntryCreateParamsCustomer{
CompanyName: "Théâtre du Palais-Royal",
Email: "moliere@tdpr.fr",
},
BankAccount: gocardless.MandateImportEntryCreateParamsBankAccount{
AccountHolderName: "Jean-Baptiste Poquelin",
Iban: "FR14BARC20000055779911",
},
Amendment: &gocardless.MandateImportEntryCreateParamsAmendment{
OriginalMandateReference: "REFMANDATE",
OriginalCreditorId: "FR123OTHERBANK",
OriginalCreditorName: "Amphitryon",
},
Links: gocardless.MandateImportEntryCreateParamsLinks{
MandateImport: "IM000010790WX1",
},
}
mandateImportEntry, err := client.MandateImportEntries.Create(context, mandateImportEntryCreateParams)
}
List all mandate import entries
For an existing mandate import, this endpoint lists all of the entries attached.
After a mandate import has been submitted, you can use this endpoint to associate records
in your system (using the record_identifier
that you provided when creating the
mandate import).
Relative endpoint: GET /mandate_import_entries
Parameters
mandate_
import - required Unique identifier, beginning with “IM”.
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
limit
- Number of records to return.
GET https://api.gocardless.com/mandate_import_entries?mandate_import=IM000010790WX1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_import_entries": [
{
"record_identifier": "bank-file.xml/line-2",
"created_at": "2018-03-03T00:00:01Z",
"links": {
"mandate_import": "IM000010790WX1"
}
},
{
"record_identifier": "bank-file.xml/line-1",
"created_at": "2018-03-03T00:00:00Z",
"links": {
"mandate_import": "IM000010790WX1"
}
}
],
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandateImportEntries()->all([
"params" => ["mandate_import" => "IM000010790WX1"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_import_entries.all(
params= { "mandate_import": "IM000010790WX1" }
).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_import_entries.all(
params: {
"mandate_import" => "IM000010790WX1"
}
).each { |entry| puts entry.record_identifier }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (MandateImportEntry entry : client.mandateImportEntries().all().withMandateImport("IM000010790WX1").execute()) {
System.out.println(entry.getRecordIdentifier());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const mandateImportEntries = await client.mandateImportEntries.list();
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.MandateImportEntryListRequest()
{
MandateImport = "IM000010790WX1"
};
var response = gocardless.MandateImportEntries.All(request);
foreach (GoCardless.Resources.MandateImportEntry entry in response)
{
Console.WriteLine(entry.RecordIdentifier);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandateImportEntryListParams := gocardless.MandateImportEntryListParams{
MandateImport: "IM000010790WX1",
}
mandateImportEntryListPagingIterator := client.MandateImportEntries.All(context, mandateImportEntryListParams)
for mandateImportEntryListPagingIterator.Next() {
mandateImportEntryListResult, err := mandateImportEntryListPagingIterator.Value(ctx)
for _, mandateImportEntry := mandateImportEntryListResult.MandateImportEntries {
fmt.Println(mandateImportEntry.RecordIdentifier)
}
}
}
Negative Balance Limits
The negative balance limit is a threshold for the creditor balance beyond which refunds are not permitted. The default limit is zero — refunds are not permitted if the creditor has a negative balance. The limit can be changed on a per-creditor basis.
Properties
id
- Unique identifier, beginning with “NBL”.
balance_
limit - The limit amount in pence (e.g. 10000 for a -100 GBP limit).
created_
at - Fixed timestamp, recording when this limit was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
links
[creator_ user] - ID of the creator_user who created this limit
links
[creditor] - ID of creditor which this limit relates to
List negative balance limits
Returns a cursor-paginated list of negative balance limits.
Relative endpoint: GET /negative_balance_limits
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
creditor
- Unique identifier, beginning with “CR”.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
limit
- Number of records to return.
GET https://api.gocardless.com/negative_balance_limits?currency=GBP&creditor=CR123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"negative_balance_limits": [
{
"id": "NBL123",
"created_at": "2014-05-08T17:01:06.000Z",
"balance_limit": "10000",
"currency": "GBP",
"links": {
"creditor": "CR123"
}
}
]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->negativeBalanceLimits()->list([
"params" => [
"currency" => "GBP",
"creditor" => "CR123",
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.negative_balance_limits.list(params={
"currency": "GBP",
"creditor": "CR123",
}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.negative_balance_limits.list(
params: {
currency: "GBP",
creditor: "CR123",
}
).records
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.negativeBalanceLimits().
all().
withCreditor("CR123").
withCurrency("GBP").
execute()
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
await client.negativeBalanceLimits.list({
currency: "GBP",
creditor: "CR123",
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.NegativeBalanceLimitListRequest()
{
Currency = "GBP",
Creditor = "CR123",
};
gocardless.NegativeBalanceLimits.All(request);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
params := gocardless.NegativeBalanceLimitListParams{
Currency: "GBP",
Creditor: "CR123",
}
response, err := client.NegativeBalanceLimits.List(context, params)
}
Create a negative balance limit
Creates a new negative balance limit, which replaces the existing limit (if present) for that currency and creditor combination.
Relative endpoint: POST /negative_balance_limits
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
Parameters
POST https://api.gocardless.com/negative_balance_limits HTTP/1.1
Content-Type: application/json
{
"negative_balance_limits": {
"currency": "GBP",
"balance_limit": "10000",
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"negative_balance_limits": {
"id": "NBL123",
"created_at": "2014-05-08T17:01:06.000Z",
"currency": "GBP",
"balance_limit": "10000",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->negativeBalanceLimits()->create([
"params" => [
"currency" => "GBP",
"balance_limit" => "10000",
"links" => ["creditor" => "CR123"],
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.negative_balance_limits.create(params={
"balance_limit": "10000",
"currency": "GBP",
"links": {
"creditor": "CR123",
},
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.negative_balance_limits.create(
params: {
balance_limit: "10000",
currency: "GBP",
links: {
creditor: "CR123",
},
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.negativeBalanceLimits().create()
.withCurrency("GBP")
.withBalanceLimit(10000)
.withLinksCreditor("CR123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
await client.negative_balance_limits.create({
currency: "GBP",
balance_limit: 10000,
links: {
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.NegativeBalanceLimitCreateRequest()
{
Currency = "GBP",
BalanceLimit = 10000,
Links = new GoCardless.Services.NegativeBalanceLimitCreateRequest.NegativeBalanceLimitLinks()
{
Creditor = "CR123"
},
};
await gocardless.NegativeBalanceLimits.CreateAsync(request);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
createParams := gocardless.NegativeBalanceLimitCreateParams{
Currency: "GBP",
BalanceLimit: 10000,
Links: gocardless.NegativeBalanceLimitCreateParamsLinks{
Creditor: "CR123",
},
}
limit, err := client.negativeBalanceLimits().Create(context, createParams)
}
Payer Authorisations
Don’t use Payer Authorisations for new integrations. It is deprecated in favour of Billing Requests. Use Billing Requests to build any future integrations.
Payer Authorisation resource acts as a wrapper for creating customer, bank account and mandate details in a single request. PayerAuthorisation API enables the integrators to build their own custom payment pages.
The process to use the Payer Authorisation API is as follows:
- Create a Payer Authorisation, either empty or with already available information
- Update the authorisation with additional information or fix any mistakes
- Submit the authorisation, after the payer has reviewed their information
- [coming soon] Redirect the payer to the verification mechanisms from the response of the Submit request (this will be introduced as a non-breaking change)
- Confirm the authorisation to indicate that the resources can be created
After the Payer Authorisation is confirmed, resources will eventually be created as it’s an asynchronous process.
To retrieve the status and ID of the linked resources you can do one of the following:
- Listen to
payer_authorisation_completed
webhook (recommended) - Poll the GET endpoint
- Poll the GET events API
https://api.gocardless.com/events?payer_authorisation={id}&action=completed
Note that the create
and update
endpoints behave differently than
other existing create
and update
endpoints. The Payer Authorisation is still saved if incomplete data is provided.
We return the list of incomplete data in the incomplete_fields
along with the resources in the body of the response.
The bank account details(account_number, bank_code & branch_code) must be sent together rather than splitting across different request for both create
and update
endpoints.
The API is designed to be flexible and allows you to collect information in multiple steps without storing any sensitive data in the browser or in your servers.
Properties
id
- Unique identifier, beginning with “PA”.
bank_
account [account_ holder_ name] - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
bank_
account [account_ number] - Bank account number - see local details for more information. Alternatively you can provide an
iban
. bank_
account [account_ number_ ending] - The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
bank_
account [account_ number_ suffix] - Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
bank_
account [account_ type] - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
account [bank_ code] - Bank code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [branch_ code] - Branch code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [country_ code] -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. bank_
account [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
bank_
account [iban] - International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_
account [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.
created_
at - Timestamp, recording when this Payer Authorisation was created.
customer
[address_ line1] - The first line of the customer’s address.
customer
[address_ line2] - The second line of the customer’s address.
customer
[address_ line3] - The third line of the customer’s address.
customer
[city] - The city of the customer’s address.
customer
[company_ name] - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). customer
[country_ code] - ISO 3166-1 alpha-2 code.
customer
[danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer
[email] - Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer
[family_ name] - Customer’s surname. Required unless a
company_name
is provided. customer
[given_ name] - Customer’s first name. Required unless a
company_name
is provided. customer
[locale] - An IETF Language Tag, used for both language and regional variations of our product.
customer
[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.
customer
[postal_ code] - The customer’s postal code.
customer
[region] - The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). customer
[swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
incomplete_
fields - An array of fields which are missing and is required to set up the mandate.
Each instance will contain these properties:
-
field
: The root resource. -
message
: A localised error message -
request_pointer
: The path to the field e.g. “/payer_authorisations/customer/city”
-
mandate
[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.
mandate
[payer_ ip_ address] - For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
Not required for creating offline mandates where
authorisation_source
is set to telephone or paper. mandate
[reference] - Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
mandate
[scheme] - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported.
status
- One of:
-
created
: The PayerAuthorisation has been created, and not been confirmed yet -
submitted
: The payer information has been submitted -
confirmed
: PayerAuthorisation is confirmed and resources are ready to be created -
completed
: The PayerAuthorisation has been completed and customer, bank_account and mandate has been created -
failed
: The PayerAuthorisation has failed and customer, bank_account and mandate is not created
-
links
[bank_ account] - Unique identifier, beginning with “BA”.
links
[customer] - Unique identifier, beginning with “CU”.
links
[mandate] - Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
Get a single Payer Authorisation
Retrieves the details of a single existing Payer Authorisation. It can be used for polling the status of a Payer Authorisation.
Relative endpoint: GET /payer_authorisations/PA123
GET https://api.gocardless.com/payer_authorisations/PAU123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payer_authorisations": {
"id": "PAU123",
"created_at": "2020-09-11T14:04:50.579Z",
"customer": {
"address_line1": "Unit 12, 2 Somerset Road",
"address_line2": "terertertre",
"city": "London",
"company_name": "",
"country_code": "US",
"email": "mail@example.com",
"family_name": "test",
"given_name": "lastname",
"postal_code": "1234",
"region": "AR",
"metadata": {}
},
"bank_account": {
"account_holder_name": "test lastname",
"account_number_ending": "11",
"account_type": "savings",
"country_code": "US",
"bank_name": "COMMUNITY FEDERAL SAVINGS BANK",
"metadata": {}
},
"mandate": {
"scheme": "ach",
"metadata": {}
},
"status": "completed",
"incomplete_fields": [],
"links": {
"customer": "CU00123",
"bank_account": "BA00123",
"mandate": "MD000123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payerAuthorisations()->get("PAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payer_authorisations.get("PAU123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payer_authorisations.get("PAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
PayerAuthorisation payerAuthorisation = client.payerAuthorisations.get("PAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payerAuthorisation = await client.payerAuthorisations.find("PAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payerAuthorisationResponse = await gocardless.payerAuthorisations.GetAsync("PAU123");
GoCardless.Resources.PayerAuthorisation payerAuthorisation = payerAuthorisationResponse.PayerAuthorisation;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payerAuthorisation, err := clienet.PayerAuthorisations.Get(context, "PAU123")
}
Create a Payer Authorisation
Creates a Payer Authorisation. The resource is saved to the database even if incomplete. An empty array of incomplete_fields means that the resource is valid. The ID of the resource is used for the other actions. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such as a multi-step form.
Relative endpoint: POST /payer_authorisations
Parameters
bank_
account [account_ holder_ name] - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
bank_
account [account_ number] - Bank account number - see local details for more information. Alternatively you can provide an
iban
. bank_
account [account_ number_ ending] - The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
bank_
account [account_ number_ suffix] - Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
bank_
account [account_ type] - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
account [bank_ code] - Bank code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [branch_ code] - Branch code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [country_ code] -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. bank_
account [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
bank_
account [iban] - International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_
account [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.
customer
[address_ line1] - The first line of the customer’s address.
customer
[address_ line2] - The second line of the customer’s address.
customer
[address_ line3] - The third line of the customer’s address.
customer
[city] - The city of the customer’s address.
customer
[company_ name] - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). customer
[country_ code] - ISO 3166-1 alpha-2 code.
customer
[danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer
[email] - Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer
[family_ name] - Customer’s surname. Required unless a
company_name
is provided. customer
[given_ name] - Customer’s first name. Required unless a
company_name
is provided. customer
[locale] - An IETF Language Tag, used for both language and regional variations of our product.
customer
[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.
customer
[postal_ code] - The customer’s postal code.
customer
[region] - The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). customer
[swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
mandate
[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.
mandate
[payer_ ip_ address] - For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
Not required for creating offline mandates where
authorisation_source
is set to telephone or paper. mandate
[reference] - Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
mandate
[scheme] - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported.
POST https://api.gocardless.com/payer_authorisations HTTP/1.1
Content-Type: application/json
{
"payer_authorisations": {
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
}
}
}
Example response with incomplete_fields
HTTP/1.1 201 Created
Location: /payer_authorisations/PA123
Content-Type: application/json
{
"payer_authorisations": {
"id": "PA123",
"created_at": "2020-04-15T15:00:00.000Z",
"status": "created",
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"account_number_ending": "11",
"bank_name": "BARCLAYS BANK",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
},
"links": {},
"incomplete_fields":[
{
"field": "payer_authorisations",
"message": "is required",
"request_pointer": "/payer_authorisations/customer/address_line1"
},
{
"field": "payer_authorisations",
"message": "is required",
"request_pointer": "/payer_authorisations/customer/city"
},
{
"field": "payer_authorisations",
"message": "is required",
"request_pointer": "/payer_authorisations/customer/postal_code"
}
]
}
}
Example response with all properties
HTTP/1.1 201 Created
Content-Type: application/json
{
"payer_authorisations": {
"id": "PA123",
"created_at": "2020-04-15T15:00:00.000Z",
"status": "created",
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"account_number_ending": "11",
"bank_name": "BARCLAYS BANK",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
},
"links": {},
"incomplete_fields": []
}
}
Example response with errors
HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{
"error": {
"message": "Validation failed",
"errors": [
{
"field": "bank_account",
"message": "is the wrong length (should be 8 characters)",
"request_pointer": "/payer_authorisations/bank_account/account_number"
},
{
"field": "bank_account",
"message": "is required",
"request_pointer": "/payer_authorisations/bank_account/branch_code"
},
{
"field": "bank_account",
"message": "is required",
"request_pointer": "/payer_authorisations/bank_account/branch_code"
}
],
"documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
"type": "validation_failed",
"request_id": "5a83ff47-cfb0-4bb8-8bcd-a3bddf0118e1",
"code": 422
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payerAuthorisations()->create([
"params" => ["customer" => [
"email" => "mail@example.com",
"given_name" => "Name",
"family_name" => "Surname",
"metadata" => [
"salesforce_id" => "EFGH5678"
]
],
"bank_account" => [
"account_holder_name" => "Name Surname",
"branch_code" => "200000",
"account_number" => "55779911",
"metadata" => []
],
"mandate" => [
"reference" => "XYZ789",
"metadata" => []
]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payer_authorisations.create(params={
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payer_authorisations.create(
params: {
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().create()
.withCustomerEmail("mail@example.com")
.withCustomerGivenName("Name")
.withCustomerFamilyName("Surname")
.withCustomerMetadata()
.withBankAccountAccountHolderName("Name Surname")
.withBankAccountBranchCode("200000")
.withBankAccountAccountNumber("55779911")
.withBankAccountMetadata()
.withMandateReference("XYZ789")
.withMandateMetadata()
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payerAuthorisation = await client.payerAuthorisations.create({
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customer = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationCustomer()
{
"email" = "mail@example.com",
"given_name" = "Name",
"family_name" = "Surname",
"metadata" = {}
};
var bankAccount = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationBankAccount()
{
"account_holder_name" = "Name Surname",
"branch_code" = "200000",
"account_number" = "55779911",
"metadata" = {}
};
var mandate = new GoCardless.Services.PayerAuthorisationCreateRequest.PayerAuthorisationMandate()
{
"reference" = "XYZ789",
"metadata" = {}
};
var PayerAuthorisationRequest = new GoCardless.Services.PayerAuthorisationCreateRequest()
{
Customer = customer,
BankAccount = bankAccount,
Mandate = mandate
};
var PayerAuthorisationResponse = await gocardless.PayerAuthorisations.CreateAsync(PayerAuthorisationRequest);
GoCardless.Resources.PayerAuthorisation payerAuthorisation = PayerAuthorisationResponse.PayerAuthorisation;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payerAuthorisationCreateParams := gocardless.PayerAuthorisationCreateParams{
Customer: gocardless.PayerAuthorisationCreateParamsCustomer{
Email: "mail@example.com",
GivenName: "Name",
FamilyName: "Surname",
Metadata: map[string]interface{}{"salesforce_id": "EFGH5678"},
},
BankAccount: gocardless.PayerAuthorisationCreateParamsBankAccount{
AccountHolderName: "Name Surname",
BranchCode: "200000",
AccountNumber: "55779911",
},
Mandate: gocardless.PayerAuthorisationCreateParamsMandate{
Reference: "XYZ789",
},
}
payerAuthorisation, err := client.PayerAuthorisations.Create(context, payerAuthorisationCreateParams)
}
Update a Payer Authorisation
Updates a Payer Authorisation. Updates the Payer Authorisation with the request data. Can be invoked as many times as needed. Only fields present in the request will be modified. An empty array of incomplete_fields means that the resource is valid. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such a multi-step form. Note that in order to update the metadata
attribute values it must be sent completely as it overrides the previously existing values.
Relative endpoint: PUT /payer_authorisations/PA123
Parameters
bank_
account [account_ holder_ name] - Name of the account holder, as known by the bank. This field will be transliterated, upcased and truncated to 18 characters. This field is required unless the request includes a customer bank account token.
bank_
account [account_ number] - Bank account number - see local details for more information. Alternatively you can provide an
iban
. bank_
account [account_ number_ ending] - The last few digits of the account number. Currently 4 digits for NZD bank accounts and 2 digits for other currencies.
bank_
account [account_ number_ suffix] - Account number suffix (only for bank accounts denominated in NZD) - see local details for more information.
bank_
account [account_ type] - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
bank_
account [bank_ code] - Bank code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [branch_ code] - Branch code - see local details for more information. Alternatively you can provide an
iban
. bank_
account [country_ code] -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. bank_
account [currency] - ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
bank_
account [iban] - International Bank Account Number. Alternatively you can provide local details. IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply local details.
bank_
account [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.
customer
[address_ line1] - The first line of the customer’s address.
customer
[address_ line2] - The second line of the customer’s address.
customer
[address_ line3] - The third line of the customer’s address.
customer
[city] - The city of the customer’s address.
customer
[company_ name] - Customer’s company name. Required unless a
given_name
andfamily_name
are provided. For Canadian customers, the use of acompany_name
value will mean that any mandate created from this customer will be considered to be a “Business PAD” (otherwise, any mandate will be considered to be a “Personal PAD”). customer
[country_ code] - ISO 3166-1 alpha-2 code.
customer
[danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer’s bank account is denominated in Danish krone (DKK).
customer
[email] - Customer’s email address. Required in most cases, as this allows GoCardless to send notifications to this customer.
customer
[family_ name] - Customer’s surname. Required unless a
company_name
is provided. customer
[given_ name] - Customer’s first name. Required unless a
company_name
is provided. customer
[locale] - An IETF Language Tag, used for both language and regional variations of our product.
customer
[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.
customer
[postal_ code] - The customer’s postal code.
customer
[region] - The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). customer
[swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
mandate
[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.
mandate
[payer_ ip_ address] - For ACH customers only. Required for ACH customers. A string containing the IP address of the payer to whom the mandate belongs (i.e. as a result of their completion of a mandate setup flow in their browser).
Not required for creating offline mandates where
authorisation_source
is set to telephone or paper. mandate
[reference] - Unique reference. Different schemes have different length and character set requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank.
mandate
[scheme] - A bank payment scheme. Currently “ach”, “autogiro”, “bacs”, “becs”, “becs_nz”, “betalingsservice”, “faster_payments”, “pad”, “pay_to” and “sepa_core” are supported.
PUT https://api.gocardless.com/payer_authorisations/PA123 HTTP/1.1
Content-Type: application/json
{
"payer_authorisations": {
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911"
},
"mandate": {
"reference": "XYZ789",
}
}
}
Example response with incomplete fields
HTTP/1.1 200 OK
Content-Type: application/json
{
"payer_authorisations": {
"id": "PA123",
"created_at": "2020-04-15T15:00:00.000Z",
"status": "created",
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"account_number_ending": "11",
"bank_name": "BARCLAYS BANK",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
}
"links": {},
"incomplete_fields":[
{
"field": "payer_authorisations",
"message": "is required",
"request_pointer": "/payer_authorisations/customer/address_line1"
},
{
"field": "payer_authorisations",
"message": "is required",
"request_pointer": "/payer_authorisations/customer/city"
},
{
"field": "payer_authorisations",
"message": "is required",
"request_pointer": "/payer_authorisations/customer/postal_code"
}
]
}
}
Example response where Payer Authorisation is updated after submitting
HTTP/1.1 422 Bad Request
Content-Type: application/json
{
"error": {
"message": "The Payer Authorisation cannot be updated after submitted",
"errors": [
{
"reason": "payer_authorisation_cannot_update_after_submit",
"message": "The Payer Authorisation cannot be updated after submitting"
}
],
"documentation_url": "https://developer.gocardless.com/api-reference#payer_authorisation_cannot_update_after_submit",
"type": "invalid_state",
"request_id": "...",
"code": 422
}
}
Example response with errors
HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{
"error": {
"message": "Validation failed",
"errors": [
{
"field": "customer",
"message": "is not valid",
"request_pointer": "/payer_authorisations/customer/email"
}
],
"documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
"type": "validation_failed",
"request_id": "2f0db86c-251c-432a-a7af-b77f1a426a37",
"code": 422
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payerAuthorisations()->update("PA123", [
"params" => ["customer" => [
"email" => "mail@example.com",
"given_name" => "Name",
"family_name" => "Surname",
"metadata" => {
"salesforce_id" => "EFGH5678"
}
],
"bank_account" => [
"account_holder_name" => "Name Surname",
"branch_code" => "200000",
"account_number" => "55779911",
],
"mandate" => [
"reference" => "XYZ789",
]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payer_authorisations.update("PA123", params={
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
},
"mandate": {
"reference": "XYZ789",
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payer_authorisations.update(
"PA123",
params: {
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
},
"mandate": {
"reference": "XYZ789",
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
PayerAuthorisation payerAuthorisation = client.payerAuthorisations().update("PA123")
.withCustomerEmail("mail@example.com")
.withCustomerGivenName("Name")
.withCustomerFamilyName("Surname")
.withCustomerMetadata("salesforce_id", "EFGH5678")
.withBankAccountAccountHolderName("Name Surname")
.withBankAccountBranchCode("200000")
.withBankAccountAccountNumber("55779911")
.withMandateReference("XYZ789")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payerAuthorisation = await client.payerAuthorisations.update(
"PA123",
{
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"branch_code": "200000",
"account_number": "55779911",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var customer = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationCustomer()
{
"email" = "mail@example.com",
"given_name" = "Name",
"family_name" = "Surname",
"metadata" = {
"salesforce_id" = "EFGH5678"
}
};
var bankAccount = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationBankAccount()
{
"account_holder_name" = "Name Surname",
"branch_code" = "200000",
"account_number" = "55779911",
};
var mandate = new GoCardless.Services.PayerAuthorisationUpdateRequest.PayerAuthorisationMandate()
{
"reference" = "XYZ789",
};
var PayerAuthorisationRequest = new GoCardless.Services.PayerAuthorisationUpdateRequest()
{
Customer = customer,
BankAccount = bankAccount,
Mandate = mandate
};
var PayerAuthorisationResponse = await gocardless.PayerAuthorisations.UpdateAsync("PA123", PayerAuthorisationRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payerAuthorisationUpdateParams := gocardless.PayerAuthorisationUpdateParams{
Customer: gocardless.PayerAuthorisationUpdateParamsCustomer{
Email: "mail@example.com",
GivenName: "Name",
FamilyName: "Surname",
Metadata: map[string]interface{}{"salesforce_id": "EFGH5678"},
},
BankAccount: gocardless.PayerAuthorisationUpdateParamsBankAccount{
AccountHolderName: "Name Surname",
BranchCode: "200000",
AccountNumber: "55779911",
},
Mandate: gocardless.PayerAuthorisationUpdateParamsMandate{
Reference: "XYZ789",
},
}
payerAuthorisation, err := client.PayerAuthorisations.Update(context, payerAuthorisationUpdateParams)
}
Submit a Payer Authorisation
Submits all the data previously pushed to this PayerAuthorisation for verification. This time, a 200 HTTP status is returned if the resource is valid and a 422 error response in case of validation errors. After it is successfully submitted, the Payer Authorisation can no longer be edited.
Relative endpoint: POST /payer_authorisations/PA123/actions/submit
POST https://api.gocardless.com/payer_authorisations/PA123/actions/submit HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payer_authorisations": {
"id": "PA123",
"created_at": "2020-04-15T15:00:00.000Z",
"status": "submitted",
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"account_number_ending": "11",
"bank_name": "BARCLAYS BANK",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
},
"links": {},
"incomplete_fields": []
}
}
or
Example response with errors
HTTP/1.1 422 Unprocessable entity
Content-Type: application/json
{
"error": {
"message": "Validation failed",
"errors": [
{
"field": "customer",
"message": "is not valid",
"request_pointer": "/payer_authorisations/customer/email"
}
],
"documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
"type": "validation_failed",
"request_id": "2f0db86c-251c-432a-a7af-b77f1a426a37",
"code": 422
}
}
or
Example response if the resource is already submitted
HTTP/1.1 304 Not modified
{}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payerAuthorisations()->submit("PAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payer_authorisations.submit("PAU123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payer_authorisations.submit("PAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
PayerAuthorisation payerAuthorisation = client.payerAuthorisations.submit("PAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payerAuthorisation = await client.payerAuthorisations.submit("PAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payerAuthorisationResponse = await gocardless.payerAuthorisations.SubmitAsync("PAU123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payerAuthorisation, err := client.PayerAuthorisations.Submit(context, "PAU123")
}
Confirm a Payer Authorisation
Confirms the Payer Authorisation, indicating that the resources are ready to be created. A Payer Authorisation cannot be confirmed if it hasn’t been submitted yet.
The main use of the confirm endpoint is to enable integrators to acknowledge the end of the setup process. They might want to make the payers go through some other steps after they go through our flow or make them go through the necessary verification mechanism (upcoming feature).
Relative endpoint: POST /payer_authorisations/PA123/actions/confirm
POST https://api.gocardless.com/payer_authorisations/PA123/actions/confirm HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payer_authorisations": {
"id": "PA123",
"created_at": "2020-04-15T15:00:00.000Z",
"status": "confirmed",
"customer": {
"email": "mail@example.com",
"given_name": "Name",
"family_name": "Surname",
"metadata": {
"salesforce_id": "EFGH5678"
}
},
"bank_account": {
"account_holder_name": "Name Surname",
"account_number_ending": "11",
"bank_name": "BARCLAYS BANK",
"metadata": {}
},
"mandate": {
"reference": "XYZ789",
"metadata": {}
},
"links": {},
"incomplete_fields": []
}
}
or
HTTP/1.1 422 Bad Request
Content-Type: application/json
{
"error": {
"message": "The Payer Authorisation needs to be submitted before confirmation",
"errors": [
{
"reason": "payer_authorisation_submit_before_confirm",
"message": "The Payer Authorisation needs to be submitted before confirmation"
}
],
"documentation_url": "https://developer.gocardless.com/api-reference#payer_authorisation_submit_before_confirm",
"type": "invalid_state",
"request_id": "...",
"code": 422
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payerAuthorisations()->confirm("PAU123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payer_authorisations.confirm("PAU123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payer_authorisations.confirm("PAU123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
PayerAuthorisation payerAuthorisation = client.payerAuthorisations.confirm("PAU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payerAuthorisation = await client.payerAuthorisations.confirm("PAU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payerAuthorisationResponse = await gocardless.payerAuthorisations.ConfirmAsync("PAU123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payerAuthorisation, err := client.PayerAuthorisations.Confirm(context, "PAU123")
}
Payer Themes
Custom colour themes for payment pages and customer notifications.
Properties
id
- Unique identifier, beginning with “PTH”.
Create a payer theme associated with a creditor
Creates a new payer theme associated with a creditor. If a creditor already has payer themes, this will update the existing payer theme linked to the creditor.
Relative endpoint: POST /branding/payer_themes
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
Parameters
button_
background_ colour - Colour for buttons background (hexcode)
content_
box_ border_ colour - Colour for content box border (hexcode)
header_
background_ colour - Colour for header background (hexcode)
link_
text_ colour - Colour for text links (hexcode)
links
[creditor] - ID of the creditor the payer theme belongs to
POST https://api.gocardless.com/branding/payer_themes HTTP/1.1
Content-Type: application/json
{
"payer_themes": {
"header_background_colour": "#BD10E0",
"link_text_colour": "#7ED321",
"button_background_colour": "#128DAA",
"content_box_border_colour": "#BD10E0",
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 201 OK
Content-Type: application/json
{
"payer_themes": {
"id": "PTH123"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payerThemes()->createForCreditor([
"params" => [
"header_background_colour" => "#BD10E0",
"link_text_colour" => "#7ED321",
"button_background_colour" => "#128DAA",
"content_box_border_colour" => "#BD10E0",
"links" => [
"creditor" => "CR123"
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payer_themes.create_for_creditor(params={
"header_background_colour": "#BD10E0",
"link_text_colour": "#7ED321",
"button_background_colour": "#128DAA",
"content_box_border_colour": "#BD10E0",
"links": {
"creditor": "CR123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payer_themes.create_for_creditor(
params: {
"header_background_colour": "#BD10E0",
"link_text_colour": "#7ED321",
"button_background_colour": "#128DAA",
"content_box_border_colour": "#BD10E0",
"links": {
"creditor": "CR123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
PayerTheme payerTheme = client.payerThemes().createForCreditor()
.withButtonBackgroundColour("#128DAA")
.withContentBoxBorderColour("#BD10E0")
.withHeaderBackgroundColour("#BD10E0")
.withLinkTextColour("#7ED321")
.withLinksCreditor("CR123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payerThemes = await client.payerThemes.createForCreditor({
header_background_colour: "#BD10E0",
link_text_colour: "#7ED321",
button_background_colour: "#128DAA",
content_box_border_colour: "#BD10E0",
links: {
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payerThemeCreateForCreditorRequest = new GoCardless.Services.PayerThemeCreateForCreditorRequest()
{
HeaderBackgroundColour = "#BD10E0",
LinkTextColour = "#7ED321",
ButtonBackgroundColour = "#128DAA",
ContentBoxBorderColour = "#BD10E0",
Links = new GoCardless.Services.PayerThemeCreateForCreditorRequest.PayerThemeLinks()
{
Creditor = "CR0123"
}
};
var payerThemeCreateForCreditorResponse = await gocardless.PayerThemes.CreateForCreditorAsync(payerThemeCreateForCreditorRequest);
GoCardless.Resources.PayerTheme creditorPayerTheme = payerThemeCreateForCreditorResponse.PayerThemeResponse;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payerThemeCreateForCreditorParams := gocardless.PayerThemeCreateForCreditorParams{
ButtonBackgroundColour: "#128DAA",
ContentBoxBorderColour: "#BD10E0",
HeaderBackgroundColour: "#BD10E0",
LinkTextColour: "#7ED321",
Links: gocardless.PayerThemeCreateForCreditorParamsLinks{
Creditor: "CR123"
}
}
payerThemes, err := client.PayerThemes.CreateForCreditor(context, payerThemeCreateForCreditorParams)
}
Payments
Payment objects represent payments from a customer to a creditor, taken against a Direct Debit mandate.
GoCardless will notify you via a webhook whenever the state of a payment changes.
Properties
id
- Unique identifier, beginning with “PM”.
amount
- Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
amount_
refunded - Amount refunded, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
charge_
date - A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate’s
next_possible_charge_date
creation will fail. If the value is not a working day it will be rolled forwards to the next available one. created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
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).
faster_
ach - This field indicates whether the ACH payment is processed through Faster
ACH or standard ACH.
It is only present in the API response for ACH payments.
fx
[estimated_ exchange_ rate] - Estimated rate that will be used in the foreign exchange of the
amount
into thefx_currency
. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places. fx
[exchange_ rate] - Rate used in the foreign exchange of the
amount
into thefx_currency
. Present only after a resource is paid out. Has up to 10 decimal places. fx
[fx_ amount] - Amount that was paid out in the
fx_currency
after foreign exchange. Present only after the resource has been paid out. fx
[fx_ currency] - ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. 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, Pro or Enterprise packages. Restricted: You can not specify a payment reference for Faster Payments. retry_
if_ possible - On failure, automatically retry the payment using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. status
- One of:
-
pending_customer_approval
: we’re waiting for the customer to approve this payment -
pending_submission
: the payment has been created, but not yet submitted to the banks -
submitted
: the payment has been submitted to the banks -
confirmed
: the payment has been confirmed as collected -
paid_out
: the payment has been included in a payout -
cancelled
: the payment has been cancelled -
customer_approval_denied
: the customer has denied approval for the payment. You should contact the customer directly -
failed
: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks. -
charged_back
: the payment has been charged back
-
links
[creditor] - ID of creditor to which the collected payment will be sent.
links
[instalment_ schedule] - ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule. links
[mandate] - ID of the mandate against which this payment should be collected.
links
[payout] - ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected. links
[subscription] - ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.
Create a payment
This fails with a mandate_is_inactive
error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pending_customer_approval
, pending_submission
, submitted
, and active
.
Relative endpoint: POST /payments
Warning: in Bacs, you have the option to provide a payment reference up to 10 characters in length. However, if you are providing custom mandate references (which can only be enabled by contacting support), the combined length of the two references separated by a dash character must not exceed 18 characters. Payment references may be up to 140 characters for SEPA, 11 for Autogiro and 30 for Betalingsservice, irrespective of the mandate reference.
Parameters
amount
- required Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
currency
- required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
app_
fee - The amount to be deducted from the payment as the OAuth app’s fee, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
charge_
date - A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate’s
next_possible_charge_date
creation will fail. If the value is not a working day it will be rolled forwards to the next available one. 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).
faster_
ach - Set this to true or false in the request to create an ACH payment to explicitly choose whether the payment should be processed through Faster ACH or standard ACH, rather than relying on the presence or absence of the charge date to indicate that.
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. 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, Pro or Enterprise packages. Restricted: You can not specify a payment reference for Faster Payments. retry_
if_ possible - On failure, automatically retry the payment using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. links
[mandate] - required ID of the mandate against which this payment should be collected.
POST https://api.gocardless.com/payments HTTP/1.1
Content-Type: application/json
{
"payments": {
"amount": 100,
"currency": "GBP",
"charge_date": "2014-05-19",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"mandate": "MD123"
}
}
}
HTTP/1.1 201 Created
Location: /payments/PM123
Content-Type: application/json
{
"payments": {
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-21",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "pending_submission",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"amount_refunded": 0,
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"links": {
"mandate": "MD123",
"creditor": "CR123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payments()->create([
"params" => ["amount" => 100,
"currency" => "GBP",
"metadata" => [
"order_dispatch_date" => "2016-08-04"
],
"links" => [
"mandate" => "MD123"
]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payments.create(params={
"amount": 100,
"currency": "GBP",
"charge_date": "2014-05-19",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"mandate": "MD123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payments.create(
params: {
amount: 1000,
currency: "GBP",
description: "Club membership fee",
links: {
mandate: "MD123"
}
},
headers: {
"Idempotency-Key" => "aaf50eb0-8ddb-4900-a97b-40ed794570a1"
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
import com.gocardless.services.PaymentService.PaymentCreateRequest.Currency;
Payment payment = client.payments().create()
.withAmount(100)
.withCurrency(Currency.GBP)
.withChargeDate("2014-05-19")
.withReference("WINEBOX001")
.withMetadata("order_dispatch_date", "2014-05-22")
.withLinksMandate("MD123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payment = await client.payments.create({
amount: 100,
currency: "GBP",
charge_date: "2014-05-19",
reference: "WINEBOX001",
metadata: {
order_dispatch_date: "2014-05-22"
},
links: {
mandate: "MD123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentRequest = new GoCardless.Services.PaymentCreateRequest()
{
Amount = 1000,
Currency = GoCardless.Services.PaymentCreateRequest.PaymentCurrency.GBP,
Description = "Membership fee",
Links = new GoCardless.Services.PaymentCreateRequest.PaymentLinks()
{
Mandate = "MD0123"
}
};
var paymentResponse = await gocardless.Payments.CreateAsync(paymentRequest);
GoCardless.Resources.Payment payment = paymentResponse.Payment;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
paymentCreateParams := gocardless.PaymentCreateParams{
Amount: 100,
Currency: "GBP",
ChargeDate: "2014-05-19",
Reference: "WINEBOX001",
Metadata: map[string]interface{}{"order_dispatch_date": "2014-05-22"},
Links: gocardless.PaymentCreateParamsLinks{
Mandate: "MD123",
},
}
payment, err := client.Payments.Create(context, paymentCreateParams)
}
List payments
Returns a cursor-paginated list of your payments.
Relative endpoint: GET /payments
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
charge_
date [gt] - Limit to records where the payment was or will be collected from the customer’s bank account after the specified date.
charge_
date [gte] - Limit to records where the payment was or will be collected from the customer’s bank account on or after the specified date.
charge_
date [lt] - Limit to records where the payment was or will be collected from the customer’s bank account before the specified date.
charge_
date [lte] - Limit to records where the payment was or will be collected from the customer’s bank account on or before the specified date.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
creditor
- ID of a creditor to filter payments by. If you pass this parameter, you cannot also pass
customer
. currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
customer
- ID of a customer to filter payments by. If you pass this parameter, you cannot also pass
creditor
. limit
- Number of records to return.
mandate
- Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
sort_
direction - The direction to sort in.
One of:
-
asc
-
desc
-
sort_
field - Field by which to sort records.
One of:
-
charge_date
-
amount
-
status
- One of:
-
pending_customer_approval
: we’re waiting for the customer to approve this payment -
pending_submission
: the payment has been created, but not yet submitted to the banks -
submitted
: the payment has been submitted to the banks -
confirmed
: the payment has been confirmed as collected -
paid_out
: the payment has been included in a payout -
cancelled
: the payment has been cancelled -
customer_approval_denied
: the customer has denied approval for the payment. You should contact the customer directly -
failed
: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks. -
charged_back
: the payment has been charged back
-
subscription
- Unique identifier, beginning with “SB”.
GET https://api.gocardless.com/payments HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"payments": [{
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-15",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "pending_submission",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"amount_refunded": 0,
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"links": {
"mandate": "MD123",
"creditor": "CR123"
},
"retry_if_possible": false
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payments()->list();
$client->payments()->list([
"params" => ["customer" => "CU123"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payments.list().records
client.payments.list(params={"customer": "CU123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payments.list
@client.payments.list(params: { customer: "CU123" })
@client.payments.list.records.each { |payment| puts payment.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Payment payment : client.payments().all().withCustomer("CU123").execute()) {
System.out.println(payment.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payments = await client.payments.list();
// List all payments past a certain date.
const payments = await client.payments.list({
created_at: {
gt: "2020-01-01T17:01:06.000Z"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentRequest = new GoCardless.Services.PaymentListRequest()
{
Customer = "CU000123"
};
var paymentListResponse = gocardless.Payments.All(paymentRequest);
foreach (GoCardless.Resources.Payment payment in paymentListResponse)
{
Console.WriteLine(payment.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
paymentListParams := gocardless.PaymentListParams{
CreatedAt: &gocardless.PaymentListParamsCreatedAt{
Gt: "2020-01-01T17:01:06.000Z",
},
}
paymentListResult, err := client.Payments.List(context, paymentListParams)
for _, payment := paymentListResult.Payments {
fmt.Println(payment.Id)
}
}
Get a single payment
Retrieves the details of a single existing payment.
Relative endpoint: GET /payments/PM123
GET https://api.gocardless.com/payments/PM123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payments": {
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-15",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "pending_submission",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"amount_refunded": 0,
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"links": {
"mandate": "MD123",
"creditor": "CR123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payments()->get("PM123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payments.get("PM123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payments.get("PM123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Payment payment = client.payments().get("PM123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payment = await client.payments.find("PM123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentResponse = await gocardless.Payments.GetAsync("PM0123");
GoCardless.Resources.Payment payment = paymentResponse.Payment;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payment, err := client.Payments.Get(context, "PM123")
}
Update a payment
Updates a payment object. This accepts only the metadata parameter.
Relative endpoint: PUT /payments/PM123
Parameters
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.
retry_
if_ possible - On failure, automatically retry the payment using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.
PUT https://api.gocardless.com/payments/PM123 HTTP/1.1
Content-Type: application/json
{
"payments": {
"metadata": {
"key": "value"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"payments": {
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-15",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "pending_submission",
"reference": "WINEBOX001",
"metadata": {
"key": "value"
},
"amount_refunded": 0,
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"links": {
"mandate": "MD123",
"creditor": "CR123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payments()->update("PM123", [
"params" => ["metadata" => ["internal_id" => "XX123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payments.update("PM123", params={
"metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payments.update(
"PM123",
params: {
metadata: { order_id: "transaction-0HE9WQ0WDE" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.payments().update("PM123")
.withMetadata("order_id", "transaction-0HE9WQ0WDE")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payment = await client.payments.update(
"PM123",
{
metadata: {
key: "value"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentRequest = new GoCardless.Services.PaymentUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"invoice_id", "INVOICE338"}
}
};
var paymentResponse = await gocardless.Payments.UpdateAsync("PM0123", paymentRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
paymentUpdateParams := gocardless.PaymentUpdateParams{
Metadata: map[string]interface{}{"key": "value"},
}
payment, err := client.Payments.Update(context, "PM123", paymentUpdateParams)
}
Cancel a payment
Cancels the payment if it has not already been submitted to the banks. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.
This will fail with a cancellation_failed
error unless the payment’s status is pending_submission
.
Relative endpoint: POST /payments/PM123/actions/cancel
Parameters
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.
POST https://api.gocardless.com/payments/PM123/actions/cancel HTTP/1.1
Content-Type: application/json
{
"data": {
"metadata": {
"ticket_id": "TK123"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"payments": {
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-21",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "cancelled",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"amount_refunded": 0,
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"links": {
"mandate": "MD123",
"creditor": "CR123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payments()->cancel("PM123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payments.cancel("PM123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payments.cancel("PM123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.payments().cancel("PM123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const paymentResponse = await client.payments.cancel("PM123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentResponse = await gocardless.Payments.CancelAsync("PM0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
paymentCancelParams := gocardless.PaymentCancelParams{}
payment, err := client.Payments.Cancel(context, "PM123", paymentCancelParams)
}
Retry a payment
Retries a failed payment if the underlying mandate is active. You will receive a resubmission_requested
webhook, but after that retrying the payment follows the same process as its initial creation, so you will receive a submitted
webhook, followed by a confirmed
or failed
event. Any metadata supplied to this endpoint will be stored against the payment submission event it causes.
This will return a retry_failed
error if the payment has not failed.
Payments can be retried up to 3 times.
Relative endpoint: POST /payments/PM123/actions/retry
Parameters
charge_
date - A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate’s
next_possible_charge_date
creation will fail. If the value is not a working day it will be rolled forwards to the next available one. 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.
POST https://api.gocardless.com/payments/PM123/actions/retry HTTP/1.1
Content-Type: application/json
{
"data": {
"metadata": {
"reason": "Customer request"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"payments": {
"id": "PM123",
"created_at": "2014-05-08T17:01:06.000Z",
"charge_date": "2014-05-21",
"amount": 100,
"description": null,
"currency": "GBP",
"status": "submitted",
"reference": "WINEBOX001",
"metadata": {
"order_dispatch_date": "2014-05-22"
},
"amount_refunded": 0,
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"links": {
"mandate": "MD123",
"creditor": "CR123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payments()->retry("PM123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payments.retry("PM123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payments.retry("PM123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.payments().retry("PM123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const paymentResponse = await client.payments.retry("PM123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var paymentResponse = await gocardless.Payments.RetryAsync("PM0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
paymentRetryParams := gocardless.PaymentRetryParams{}
payment, err := client.Payments.Retry(context, "PM123", paymentRetryParams)
}
Payouts
Payouts represent transfers from GoCardless to a creditor. Each payout contains the funds collected from one or many payments. All the payments in a payout will have been collected in the same currency. Payouts are created automatically after a payment has been successfully collected.
Properties
id
- Unique identifier, beginning with “PO”.
amount
- Amount in minor unit (e.g. pence in GBP, cents in EUR).
arrival_
date - Date the payout is due to arrive in the creditor’s bank account.
One of:
-
yyyy-mm-dd
: the payout has been paid and is due to arrive in the creditor’s bank account on this day -
null
: the payout hasn’t been paid yet
-
created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
deducted_
fees - Fees that have already been deducted from the payout amount in minor unit (e.g. pence in GBP, cents in EUR), inclusive of tax if applicable.
For eachlate_failure_settled
orchargeback_settled
action, we refund the transaction fees in a payout. This means that a payout can have a negativededucted_fees
value.
This field is calculated as(GoCardless fees + app fees + surcharge fees) - (refunded fees)
If the merchant is invoiced for fees separately from the payout, thendeducted_fees
will be 0. fx
[estimated_ exchange_ rate] - Estimated rate that will be used in the foreign exchange of the
amount
into thefx_currency
. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places. fx
[exchange_ rate] - Rate used in the foreign exchange of the
amount
into thefx_currency
. Present only after a resource is paid out. Has up to 10 decimal places. fx
[fx_ amount] - Amount that was paid out in the
fx_currency
after foreign exchange. Present only after the resource has been paid out. fx
[fx_ currency] - ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
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. Note: This should not be used for storing PII data.
payout_
type - Whether a payout contains merchant revenue or partner fees.
reference
- Reference which appears on the creditor’s bank statement.
status
- One of:
-
pending
: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider. -
paid
: the payout has been sent to the your bank. FX payouts will becomepaid
after we emit thefx_rate_confirmed
webhook. -
bounced
: the payout bounced when sent, the payout can be retried.
-
tax_
currency -
ISO 4217 code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR”, “GBP”, for French or British merchants, this will be
null
if tax is not applicable beta links
[creditor] - ID of creditor who will receive this payout, i.e. the owner of the
creditor_bank_account
. links
[creditor_ bank_ account] - ID of bank account which this will be sent to.
List payouts
Returns a cursor-paginated list of your payouts.
Relative endpoint: GET /payouts
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
creditor
- Unique identifier, beginning with “CR”.
creditor_
bank_ account - Unique identifier, beginning with “BA”.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
limit
- Number of records to return.
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. Note: This should not be used for storing PII data.
payout_
type - Whether a payout contains merchant revenue or partner fees.
reference
- Reference which appears on the creditor’s bank statement.
status
- One of:
-
pending
: the payout has been created, but not yet sent to your bank or it is in the process of being exchanged through our FX provider. -
paid
: the payout has been sent to the your bank. FX payouts will becomepaid
after we emit thefx_rate_confirmed
webhook. -
bounced
: the payout bounced when sent, the payout can be retried.
-
GET https://api.gocardless.com/payouts HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payouts": [{
"id": "PO123",
"amount": 1000,
"arrival_date": "2014-06-27",
"deducted_fees": 10,
"currency": "GBP",
"created_at": "2014-06-20T13:23:34.000Z",
"payout_type": "merchant",
"reference": "ref-1",
"status": "pending",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.11667"
},
"tax_currency": "GBP",
"metadata":{ "key": "value" },
"links": {
"creditor_bank_account": "BA123",
"creditor": "CR123"
}
}],
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payouts()->list();
$client->payouts()->list([
"params" => ["creditor" => "CR123"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payouts.list().records
client.payouts.list(params={"status": "pending"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payouts.list
@client.payouts.list(params: { creditor_bank_account: "BA123" })
@client.payouts.list.records.each { |payout| puts payout.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Payout payout : client.payouts().all().withStatus("pending").execute()) {
System.out.println(payout.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payouts = await client.payouts.list();
// List all payouts with a given status.
await client.payouts.list({ status: "pending" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payoutRequest = new GoCardless.Services.PayoutListRequest()
{
Currency = GoCardless.Services.PayoutListRequest.PayoutCurrency.EUR,
};
var payoutListResponse = gocardless.Payouts.All(payoutRequest);
foreach (GoCardless.Resources.Payout payout in payoutListResponse)
{
Console.WriteLine(payout.Amount);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payoutListParams := gocardless.PayoutListParams{}
payoutListResult, err := client.Payouts.List(context, payoutListParams)
for _, payout := range payoutListResult.Payouts {
fmt.Println(payout.Amount)
}
}
Get a single payout
Retrieves the details of a single payout. For an example of how to reconcile the transactions in a payout, see this guide.
Relative endpoint: GET /payouts/PO123
GET https://api.gocardless.com/payouts/PO123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payouts": {
"id": "PO123",
"amount": 1000,
"arrival_date": "2014-06-27",
"deducted_fees": 10,
"currency": "GBP",
"created_at": "2014-06-20T13:23:34.000Z",
"payout_type": "merchant",
"reference": "ref-1",
"status": "pending",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.11667"
},
"tax_currency": "GBP",
"metadata":{ "key": "value" },
"links": {
"creditor_bank_account": "BA123",
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payouts()->get("PO123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payouts.get("PO123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payouts.get("PO123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.payouts().get("PO123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payout = await client.payouts.find("PO123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payoutResponse = await gocardless.Payouts.GetAsync("PO0123");
GoCardless.Resources.Payout payout = payoutResponse.Payout;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payout, err := client.Payouts.Get(context, "PO123")
}
Update a payout
Updates a payout object. This accepts only the metadata parameter.
Relative endpoint: PUT /payouts/PO123
Parameters
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.
PUT https://api.gocardless.com/payouts/PO123 HTTP/1.1
Content-Type: application/json
{
"payouts": {
"metadata": {
"key": "value"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"payouts": {
"id": "PO123",
"amount": 1000,
"arrival_date": "2014-06-27",
"deducted_fees": 10,
"currency": "GBP",
"created_at": "2014-06-20T13:23:34.000Z",
"payout_type": "merchant",
"reference": "ref-1",
"status": "pending",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.11667"
},
"tax_currency": "GBP",
"metadata":{"key":"value"},
"links": {
"creditor_bank_account": "BA123",
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payouts()->update("PO123", [
"params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payouts.update("PO123", params={
"metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payouts.update(
"PO123",
params: {
metadata: { key: "value" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.payouts().update("PO123")
.withMetadata("key", "value")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payout = await client.payouts.update(
"PO123",
{
metadata: {
key: "value"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var payoutRequest = new GoCardless.Services.PayoutUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"key", "value"}
}
};
var payoutResponse = await gocardless.Payouts.UpdateAsync("PO123", payoutRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payoutUpdateParams := gocardless.PayoutUpdateParams{
Metadata: map[string]interface{}{"key": "value"},
}
payout, err := client.Payouts.Update(context, "PO123", payoutUpdateParams)
}
Payout Items
When we collect a payment on your behalf, we add the money you’ve collected to your GoCardless balance, minus any fees paid. Periodically (usually every working day), we take any positive balance in your GoCardless account, and pay it out to your nominated bank account.
Other actions in your GoCardless account can also affect your balance. For example, if a customer charges back a payment, we’ll deduct the payment’s amount from your balance, but add any fees you paid for that payment back to your balance.
The Payout Items API allows you to view, on a per-payout basis, the credit and debit
items that make up that payout’s amount. Payout items can only be retrieved for payouts
created in the last 6 months. Requests for older payouts will return an HTTP status
410 Gone
.
Properties
amount
- The positive (credit) or negative (debit) value of the item, in fractional currency;
the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.
For accuracy, we store some of our fees to greater precision than we can actually pay out (for example, a GoCardless fee we record might come to 0.5 pence, but it is not possible to send a payout via bank transfer including a half penny).
To calculate the final amount of the payout, we sum all of the items and then round to the nearest currency unit. taxes
- An array of tax items beta
Note: VAT applies to transaction and surcharge fees for merchants operating in the UK and France.
Each instance will contain these properties:
-
amount
: The amount of tax applied to a fee in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place. -
currency
: ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. -
destination_amount
: The amount of tax to be paid out to the tax authorities in fractional currency; the lowest denomination for the currency (e.g. pence in GBP, cents in EUR), to one decimal place.When
currency
anddestination_currency
don’t match this will benull
until theexchange_rate
has been finalised. -
destination_currency
: ISO 4217 code for the currency in which tax is paid out to the tax authorities of your tax jurisdiction. Currently “EUR” for French merchants and “GBP” for British merchants. -
exchange_rate
: The exchange rate for the tax from the currency into the destination currency.Present only if the currency and the destination currency don’t match and the exchange rate has been finalised.
You can listen for the payout’s
tax_exchange_rates_confirmed
webhook to know when the exchange rate has been finalised for all fees in the payout. -
tax_rate_id
: The unique identifier created by the jurisdiction, tax type and version
-
type
- The type of the credit (positive) or debit (negative) item in the payout (inclusive of VAT if applicable). One of:
-
payment_paid_out
(credit) -
payment_failed
(debit): The payment failed to be processed. -
payment_charged_back
(debit): The payment has been charged back. -
payment_refunded
(debit): The payment has been refunded to the customer. -
refund
(debit): A refund sent to a customer, not linked to a payment. -
refund_funds_returned
(credit): The refund could not be sent to the customer, and the funds have been returned to you. -
gocardless_fee
(credit/debit): The fees that GoCardless charged for a payment. In the case of a payment failure or chargeback, these will appear as credits. Will include taxes if applicable for merchants. -
app_fee
(credit/debit): The optional fees that a partner may have taken for a payment. In the case of a payment failure or chargeback, these will appear as credits. -
revenue_share
(credit/debit): A share of the fees that GoCardless collected which some partner integrations receive when their users take payments. Only shown in partner payouts. In the case of a payment failure or chargeback, these will appear as credits. -
surcharge_fee
(credit/debit): GoCardless deducted a surcharge fee as the payment failed or was charged back, or refunded a surcharge fee as the bank or customer cancelled the chargeback. Will include taxes if applicable for merchants.
-
links
[mandate] - Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016. Present only for the items of type
payment_refunded
,refund
andrefund_funds_returned
. links
[payment] - Unique identifier, beginning with “PM”.
links
[refund] - Unique identifier, beginning with “RF”. Present only for the items of type
payment_refunded
,refund
andrefund_funds_returned
.
Get all payout items in a single payout
Returns a cursor-paginated list of items in the payout.
This endpoint only serves requests for payouts created in the last 6 months. Requests for older payouts will return an HTTP status 410 Gone
.
Relative endpoint: GET /payout_items
Parameters
payout
- required Unique identifier, beginning with “PO”.
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
include_
2020_ tax_ cutover - Boolean value indicating whether the API should return tax data for the cutover period of April to August 2020. Defaults to false.
limit
- Number of records to return.
GET https://api.gocardless.com/payout_items?payout=PO123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"payout_items": [
{
"amount": "4.0",
"type": "gocardless_fee",
"taxes": [{
"amount": "1.0",
"currency": "GBP",
"destination_amount": "1.1",
"destination_currency": "EUR",
"exchange_rate": "1.11205",
"tax_rate_id": "FR_VAT_1"
}],
"links": {
"payment": "PM456"
}
},
{
"amount": "1000.0",
"type": "payment_paid_out",
"taxes": [],
"links": {
"payment": "PM123"
}
},
{
"amount": "-24.0",
"type": "gocardless_fee",
"taxes": [{
"amount": "4.0",
"currency": "EUR",
"destination_amount": "4.0",
"destination_currency": "EUR",
"exchange_rate": null,
"tax_rate_id": "FR_VAT_1",
}],
"links": {
"payment": "PM123"
}
},
{
"amount": "30.0",
"type": "payment_paid_out",
"taxes": [],
"links": {
"payment": "PM456"
}
},
{
"amount": "-500.0",
"type": "payment_refunded",
"taxes": [],
"links": {
"payment": "PM789"
}
},
{
"amount": "4.0",
"type": "gocardless_fee",
"taxes": [{
"amount": "1.0",
"currency": "GBP",
"destination_amount": "1.1",
"destination_currency": "EUR",
"exchange_rate": "1.11205",
"tax_rate_id": "FR_VAT_1"
}],
"links": {
"payment": "PM456"
}
},
{
"amount": "-1.0",
"type": "app_fee",
"taxes": [],
"links": {
"payment": "PM456"
}
},
],
"meta": {
"cursors": { "before": null, "after": null },
"limit": 50
}
}
GET https://api.gocardless.com/payout_items?payout=PO456 HTTP/1.1
HTTP/1.1 410 Gone
Content-Type: application/json
{
"error": {
"documentation_url": "https://developer.gocardless.com/api-reference#payout_items_data_archived",
"message": "Payout items for payouts created more than 6 months ago are archived. Please contact support if you require access to this data.",
"type": "invalid_api_usage",
"errors": [
{
"reason": "payout_items_data_archived",
"message": "Payout items for payouts created more than 6 months ago are archived. Please contact support if you require access to this data."
}
],
"code": 410,
"request_id": "deadbeef-0000-4000-0000-444400004444"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->payoutItems()->list([
'params' => ['payout' => 'PO123']
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.payout_items.list(params={'payout': 'PO123'})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.payout_items.list(params: {payout: "PO123"})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.payoutItems().all().withPayout("PO123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const payoutItems = await client.payoutItems.list({ payout: "P0123" });
// List the first three payout items for a payout
const payoutItems = await client.payoutItems.list({ payout: "P0123", limit: 3 });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var itemsRequest = new GoCardless.Services.PayoutItemsListRequest()
{
Payout = "PO123"
};
var response = gocardless.PayoutItems.All(payoutRequest);
foreach (GoCardless.Resources.PayoutItem item in response)
{
Console.WriteLine(item.Amount);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
payoutItemsListParams := gocardless.PayoutItemListParams{
Payout: "PO123",
}
payoutItemsListResult, err := client.PayoutItems.List(context, payoutItemsListParams)
for _, payoutItem := payoutItemsListResult.PayoutItems {
fmt.Println(payoutItem.Amount)
}
}
Redirect Flows
Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.
Redirect flows enable you to use GoCardless’ hosted payment pages to set up mandates with your customers. These pages are fully compliant and have been translated into Danish, Dutch, French, German, Italian, Norwegian, Portuguese, Slovak, Spanish and Swedish.
The overall flow is:
-
You create a redirect flow for your customer, and redirect them to the returned redirect url, e.g.
https://pay.gocardless.com/flow/RE123
. -
Your customer supplies their name, email, address, and bank account details, and submits the form. This securely stores their details, and redirects them back to your
success_redirect_url
withredirect_flow_id=RE123
in the querystring. -
You complete the redirect flow, which creates a customer, customer bank account, and mandate, and returns the ID of the mandate. You may wish to create a subscription or payment at this point.
Once you have completed the redirect flow via the API, you should display a confirmation page to your customer, confirming that their Direct Debit has been set up. You can build your own page, or redirect to the one we provide in the confirmation_url
attribute of the redirect flow.
Redirect flows expire 30 minutes after they are first created. You cannot complete an expired redirect flow. For an integrator this is shorter and they will expire after 10 minutes.
Properties
id
- Unique identifier, beginning with “RE”.
confirmation_
url - The URL of a confirmation page, which you may optionally redirect the customer to rather than use your own page, that confirms in their chosen language that their Direct Debit has been set up successfully. Only returned once the customer has set up their mandate via the payment pages and the redirect flow has been completed, and only available for 15 minutes from when you complete the redirect flow. The structure of this URL may change at any time, so you should read it directly from the API response.
created_
at - Fixed timestamp, recording when this resource was created.
description
- A description of the item the customer is paying for. This will be shown on the hosted payment pages.
mandate_
reference - Mandate reference generated by GoCardless or submitted by an integrator.
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. Note: This should not be used for storing PII data.
redirect_
url - The URL of the hosted payment pages for this redirect flow. This is the URL you should redirect your customer to.
scheme
- The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer’s bank account.
session_
token - The customer’s session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.
success_
redirect_ url - The URL to redirect to upon successful mandate setup. You must use a URL beginning
https
in the live environment. links
[billing_ request] - ID of billing request that a redirect flow can create.
Note: The redirect flow will only create a billing request in the event the redirect flow is eligible to send the payer down this new and improved flow links
[creditor] - The creditor for whom the mandate will be created. The
name
of the creditor will be displayed on the payment page. links
[customer] - ID of customer created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed. links
[customer_ bank_ account] - ID of customer bank account created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed. links
[mandate] - ID of mandate created by this redirect flow.
Note: this property will not be present until the redirect flow has been successfully completed.
Create a redirect flow
Creates a redirect flow object which can then be used to redirect your customer to the GoCardless hosted payment pages.
Relative endpoint: POST /redirect_flows
Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.
Parameters
session_
token - required The customer’s session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.
success_
redirect_ url -
required The URL to redirect to upon successful mandate setup. You must use a URL beginning
https
in the live environment. description
- A description of the item the customer is paying for. This will be shown on the hosted payment pages.
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. Note: This should not be used for storing PII data.
prefilled_
bank_ account [account_ type] - Bank account type for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
prefilled_
customer [address_ line1] - The first line of the customer’s address.
prefilled_
customer [address_ line2] - The second line of the customer’s address.
prefilled_
customer [address_ line3] - The third line of the customer’s address.
prefilled_
customer [city] - The city of the customer’s address.
prefilled_
customer [company_ name] - Customer’s company name. Company name should only be provided if
given_name
andfamily_name
are null. prefilled_
customer [country_ code] - ISO 3166-1 alpha-2 code.
prefilled_
customer [danish_ identity_ number] - For Danish customers only. The civic/company number (CPR or CVR) of the customer.
prefilled_
customer [email] - Customer’s email address.
prefilled_
customer [family_ name] - Customer’s surname.
prefilled_
customer [given_ name] - Customer’s first name.
prefilled_
customer [language] - ISO 639-1 code.
prefilled_
customer [phone_ number] - For New Zealand customers only.
prefilled_
customer [postal_ code] - The customer’s postal code.
prefilled_
customer [region] - The customer’s address region, county or department.
prefilled_
customer [swedish_ identity_ number] - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer.
scheme
- The Direct Debit scheme of the mandate. If specified, the payment pages will only allow the set-up of a mandate for the specified scheme. It is recommended that you leave this blank so the most appropriate scheme is picked based on the customer’s bank account.
links
[creditor] - The creditor for whom the mandate will be created. The
name
of the creditor will be displayed on the payment page. Required if your account manages multiple creditors.
POST https://api.gocardless.com/redirect_flows HTTP/1.1
Content-Type: application/json
{
"redirect_flows": {
"description": "Wine boxes",
"session_token": "SESS_wSs0uGYMISxzqOBq",
"success_redirect_url": "https://example.com/pay/confirm",
"prefilled_customer": {
"given_name": "Frank",
"family_name": "Osborne",
"email": "frank.osborne@acmeplc.com"
},
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 201 Created
Location: /redirect_flows/RE123
Content-Type: application/json
{
"redirect_flows": {
"id": "RE123",
"description": "Wine boxes",
"session_token": "SESS_wSs0uGYMISxzqOBq",
"scheme": null,
"success_redirect_url": "https://example.com/pay/confirm",
"redirect_url": "http://pay.gocardless.com/flow/RE123",
"created_at": "2014-10-22T13:10:06.000Z",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->redirectFlows()->create([
"params" => ["description" => "Wine boxes",
"session_token" => "SESS_wSs0uGYMISxzqOBq",
"success_redirect_url" => "https://example.com/pay/confirm",
"prefilled_customer" => [
"given_name" => "Frank",
"family_name" => "Osborne",
"email" => "frank.osborne@acmeplc.com"
]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.redirect_flows.create(params={
"description": "Wine boxes",
"session_token": "SESS_wSs0uGYMISxzqOBq",
"success_redirect_url": "https://example.com/pay/confirm",
"prefilled_customer": {
"given_name": "Frank",
"family_name": "Osborne",
"email": "frank.osborne@acmeplc.com"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.redirect_flows.create(
params: {
description: "Team membership",
session_token: "my_unique_tracking_id",
success_redirect_url: "https://example.com/pay/confirm",
prefilled_customer: {
given_name: "Frank",
family_name: "Osborne",
email: "frank.osborne@acmeplc.com"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
RedirectFlow redirectFlow = client.redirectFlows().create()
.withDescription("Wine boxes")
.withSessionToken("SESS_wSs0uGYMISxzqOBq")
.withSuccessRedirectUrl("https://example.com/pay/confirm")
.withPrefilledCustomerGivenName("Frank")
.withPrefilledCustomerFamilyName("Osborne")
.withPrefilledCustomerEmail("frank.osborne@acmeplc.com")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const redirectFlow = await client.redirectFlows.create({
description: "Wine boxes",
session_token: "SESS_wSs0uGYMISxzqOBq",
success_redirect_url: "https://example.com/pay/confirm",
prefilled_customer: {
given_name: "Frank",
family_name: "Osborne",
email: "frank.osborne@acmeplc.com"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var prefilledCustomer = new GoCardless.Services.RedirectFlowCreateRequest.RedirectFlowPrefilledCustomer()
{
AddressLine1 = "338 Goswell Road",
Email = "api@gocardless.com",
GivenName = "Bobby",
FamilyName = "Tables"
};
var redirectFlowRequest = new GoCardless.Services.RedirectFlowCreateRequest()
{
Description = "Gold package",
SessionToken = "SESS_wSs0uGYMISxzqOBq",
SuccessRedirectUrl = "https://example.com/pay/confirm",
PrefilledCustomer = prefilledCustomer
};
var redirectFlowResponse = await gocardless.RedirectFlows.CreateAsync(redirectFlowRequest);
GoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;
Console.WriteLine(redirectFlow.RedirectUrl);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
redirectFlowCreateParams := gocardless.RedirectFlowCreateParams{
Description: "Cider Barrels",
Links: &gocardless.RedirectFlowCreateParamsLinks{
Creditor: "CR00006A7FRJA5",
},
PrefilledCustomer: &gocardless.RedirectFlowCreateParamsPrefilledCustomer{
AddressLine1: "338-346 Goswell Road",
City: "London",
GivenName: "Tim",
FamilyName: "Rogers",
Email: "tim@gocardless.com",
PostalCode: "EC1V 7LQ",
},
Scheme: "bacs",
SessionToken: "dummy_session_token",
SuccessRedirectUrl: "https://developer.gocardless.com/example-redirect-uri/",
}
redirectFlow, err := client.RedirectFlows.Create(ctx, redirectFlowCreateParams)
}
Get a single redirect flow
Returns all details about a single redirect flow
Relative endpoint: GET /redirect_flows/RE123456
Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.
GET https://api.gocardless.com/redirect_flows/RE123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"redirect_flows": {
"id": "RE123",
"description": "Wine boxes",
"session_token": "SESS_wSs0uGYMISxzqOBq",
"scheme": null,
"success_redirect_url": "https://example.com/pay/confirm",
"redirect_url": "http://pay.gocardless.com/flow/RE123",
"created_at": "2014-10-22T13:10:06.000Z",
"links": {
"creditor": "CR123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->redirectFlows()->get("RE123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.redirect_flows.get("RE123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.redirect_flows.get("RE123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
RedirectFlow redirectFlow = client.redirectFlows.get("RE123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const redirectFlow = await client.redirectFlows.find("RE123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var redirectFlowResponse = await gocardless.RedirectFlows.GetAsync("RE123");
GoCardless.Resources.RedirectFlow redirectFlow = redirectFlowResponse.RedirectFlow;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
redirectFlow, err := client.RedirectFlows.Get(context, "RE123")
}
Complete a redirect flow
This creates a customer, customer bank account, and mandate using the details supplied by your customer and returns the ID of the created mandate.
This will return a redirect_flow_incomplete
error if your customer has not yet been redirected back to your site, and a redirect_flow_already_completed
error if your integration has already completed this flow. It will return a bad_request
error if the session_token
differs to the one supplied when the redirect flow was created.
Relative endpoint: POST /redirect_flows/RE123456/actions/complete
Deprecated: Redirect Flows are legacy APIs and cannot be used by new integrators. The Billing Request flow API should be used for your payment flows.
Parameters
session_
token - required The customer’s session ID must be provided when the redirect flow is set up and again when it is completed. This allows integrators to ensure that the user who was originally sent to the GoCardless payment pages is the one who has completed them.
POST https://api.gocardless.com/redirect_flows/RE123/actions/complete HTTP/1.1
Content-Type: application/json
{
"data": {
"session_token": "SESS_wSs0uGYMISxzqOBq"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"redirect_flows": {
"id": "RE123",
"description": "Wine boxes",
"session_token": "SESS_wSs0uGYMISxzqOBq",
"scheme": null,
"success_redirect_url": "https://example.com/pay/confirm",
"confirmation_url": "https://pay.gocardless.com/flow/RE123/success"
"created_at": "2014-10-22T13:10:06.000Z",
"mandate_reference": "AB1YZ"
"links": {
"creditor": "CR123",
"mandate": "MD123",
"customer": "CU123",
"customer_bank_account": "BA123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->redirectFlows()->complete("RE123", [
"params" => ["session_token" => "SESS_wSs0uGYMISxzqOBq"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.redirect_flows.complete("RE123", params={
"session_token": "SESS_wSs0uGYMISxzqOBq"
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.redirect_flows.complete(
"RE123",
params: {
session_token: "my_unique_tracking_id"
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.redirectFlows().complete("RE123")
.withSessionToken("SESS_wSs0uGYMISxzqOBq")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const redirectFlowResponse = await client.redirectFlows.complete(
"RE123",
{
session_token: "SESS_wSs0uGYMISxzqOBq"
}
)
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var redirectFlowRequest = new GoCardless.Services.RedirectFlowCompleteRequest()
{
SessionToken = "SESS_wSs0uGYMISxzqOBq"
};
var redirectFlowResponse = await gocardless.RedirectFlows.CompleteAsync("RE123", redirectFlowRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
redirectFlowCompleteParams := gocardless.RedirectFlowCompleteParams{
SessionToken: "dummy_session_token",
}
redirectFlow, err := client.RedirectFlows.Complete(ctx, "RE0003QNP5DE2101R80QZHJ2X12P93Q4", redirectFlowCompleteParams)
}
Refunds
Refund objects represent (partial) refunds of a payment back to the customer.
GoCardless will notify you via a webhook whenever a refund is created, and will update the amount_refunded
property of the payment.
Properties
id
- Unique identifier, beginning with “RF”.
amount
- Amount in minor unit (e.g. pence in GBP, cents in EUR).
created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. This is set to the currency of the refund’s payment.
fx
[estimated_ exchange_ rate] - Estimated rate that will be used in the foreign exchange of the
amount
into thefx_currency
. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places. fx
[exchange_ rate] - Rate used in the foreign exchange of the
amount
into thefx_currency
. Present only after a resource is paid out. Has up to 10 decimal places. fx
[fx_ amount] - Amount that was paid out in the
fx_currency
after foreign exchange. Present only after the resource has been paid out. fx
[fx_ currency] - ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported. Present only if payouts will be (or were) made via foreign exchange.
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. 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, Pro or Enterprise packages. Restricted: You can not specify a payment reference for Faster Payments. status
- One of:
-
created
: the refund has been created -
pending_submission
: the refund has been created, but not yet submitted to the banks -
submitted
: the refund has been submitted to the banks -
paid
: the refund has been included in a payout -
cancelled
: the refund has been cancelled -
bounced
: the refund has failed to be paid -
funds_returned
: the refund has had its funds returned
-
links
[mandate] - ID of the mandate against which the refund is being made.
links
[payment] - ID of the payment against which the refund is being made.
Create a refund
Creates a new refund object.
-
total_amount_confirmation_invalid
if the confirmation amount doesn’t match the total amount refunded for the payment. This safeguard is there to prevent two processes from creating refunds without awareness of each other. -
number_of_refunds_exceeded
if five or more refunds have already been created against the payment. -
available_refund_amount_insufficient
if the creditor does not have sufficient balance for refunds available to cover the cost of the requested refund.
Relative endpoint: POST /refunds
Restricted: This endpoint is disabled by default. You can contact us to request that we enable this for you.
Warning: A payment that has been (partially) refunded can still receive a late failure or chargeback from the customer’s bank.
A refund can only be created once it is outside the safer refund period (7 calendar days after the charge date) otherwise an error is returned. The safer refund period can be disabled by contacting GoCardless.
Parameters
amount
- required Amount in minor unit (e.g. pence in GBP, cents in EUR).
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 reference that will appear on your customer’s bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn’t offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. 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, Pro or Enterprise packages. Restricted: You can not specify a payment reference for Faster Payments. total_
amount_ confirmation - Total expected refunded amount in minor unit (e.g. pence/cents/öre). If there are
other partial refunds against this payment, this value should be the sum of the
existing refunds plus the amount of the refund being created.
Must be supplied iflinks[payment]
is present. links
[mandate] - ID of the mandate against which the refund is being made.
Restricted: You must request access to Mandate Refunds by contacting our support team. links
[payment] - ID of the payment against which the refund is being made.
POST https://api.gocardless.com/refunds HTTP/1.1
Content-Type: application/json
{
"refunds": {
"amount": 100,
"total_amount_confirmation": 150,
"reference": "Acme refund",
"metadata": {
"reason": "late delivery"
},
"links": {
"payment": "PM123"
}
}
}
HTTP/1.1 201 Created
Location: /payments/RF123
Content-Type: application/json
{
"refunds": {
"id": "RF123",
"created_at": "2014-05-08T17:01:06.000Z",
"amount": 100,
"currency": "GBP",
"reference": "Acme refund",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"status": "created",
"metadata": {
"reason": "late delivery"
},
"links": {
"payment": "PM123"
}
}
}
// Or, if the creditor does not have a sufficient balance to create the refund:
HTTP/1.1 422 Validation Failed
Content-Type: application/json
{
"error": {
"message": "It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP",
"errors": [
{
"reason": "available_refund_amount_insufficient",
"message": "It’s not possible to process this refund because you don’t have enough funds in GBP. Your available refund amount for payments in GBP is: 0.9 GBP",
"metadata": {
"available_refund_amount": 90
}
}
],
"documentation_url": "https://developer.gocardless.com/api-reference#available_refund_amount_insufficient",
"type": "validation_failed",
"request_id": "...",
"code": 422
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->refunds()->create([
"params" => ["amount" => 100,
"total_amount_confirmation" => 150,
"reference" => "Acme refund",
"metadata" => ["reason" => "Late delivery"],
"links" => ["payment" => "PM123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.refunds.create(params={
"amount": 100,
"total_amount_confirmation": 150,
"reference": "Acme refund",
"metadata": {
"reason": "late delivery"
},
"links": {
"payment": "PM123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.refunds.create(
params: {
amount: 100,
total_amount_confirmation: 150,
reference: "Service refund",
metadata: { reason: "Late delivery" },
links: { payment: "PM123"}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.refunds().create()
.withAmount(100)
.withTotalAmountConfirmation(150)
.withReference("Acme refund")
.withMetadata("reason", "late delivery")
.withLinksPayment("PM123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const refund = await client.refunds.create({
amount: 100,
total_amount_confirmation: 150,
reference: "Acme refund",
metadata: {
reason: "late delivery"
},
links: {
payment: "PM123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var refundRequest = new GoCardless.Services.RefundCreateRequest()
{
Amount = 100,
TotalAmountConfirmation = 150,
Reference = "Partial refund",
Links = new GoCardless.Services.RefundCreateRequest.RefundLinks()
{
Payment = "PM0123"
}
};
var refundResponse = await gocardless.Refunds.CreateAsync(refundRequest);
GoCardless.Resources.Refund refund = refundResponse.Refund;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
refundCreateParams := gocardless.RefundCreateParams{
Amount: 100,
TotalAmountConfirmation: 150,
Reference: "Acme refund",
Metadata: map[string]interface{}{"reason": "late delivery"},
Links: gocardless.RefundCreateParamsLinks{
Payment: "PM123",
},
}
refund, err := client.Refunds.Create(context, refundCreateParams)
}
List refunds
Returns a cursor-paginated list of your refunds.
Relative endpoint: GET /refunds
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
limit
- Number of records to return.
mandate
- Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
payment
- Unique identifier, beginning with “PM”.
refund_
type - Whether a refund was issued against a mandate or a payment. One of:
-
payment
: default returns refunds created against payments only -
mandate
: returns refunds created against mandates only
-
GET https://api.gocardless.com/refunds HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"refunds": [{
"id": "RF123",
"created_at": "2014-05-08T17:01:06.000Z",
"amount": 100,
"currency": "GBP",
"reference": "Acme refund",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"status": "created",
"metadata": {
"reason": "late failure"
},
"links": {
"payment": "PM123"
}
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->refunds()->list();
$client->refunds()->list([
"params" => ["payment" => "PM123"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.refunds.list().records
client.refunds.list(params={"payment": "PM123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.refunds.list
@client.refunds.list(params: { payment: "PM123" })
@client.refunds.list.records.each { |refund| puts refund.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Refund refund : client.refunds().all().withPayment("PM123").execute()) {
System.out.println(refund.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const refunds = await client.refunds.list();
// List all refunds associated with a given mandate.
const refunds = await client.refunds.list({ mandate: "MD0123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var refundRequest = new GoCardless.Services.RefundListRequest()
{
Mandate = "MD0123"
};
var refundListResponse = gocardless.Refunds.All(refundRequest);
foreach (GoCardless.Resources.Refund refund in refundListResponse)
{
Console.WriteLine(refund.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
refundListParams := gocardless.RefundListParams{
Mandate: "MD123",
}
refundListResult, err := client.Refunds.List(context, refundListParams)
for _, refund := refundListResult.Refunds {
fmt.Println(refund.Id)
}
}
Get a single refund
Retrieves all details for a single refund
Relative endpoint: GET /refunds/RF123
GET https://api.gocardless.com/refunds/RF123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"refunds": {
"id": "RF123",
"created_at": "2014-05-08T17:01:06.000Z",
"amount": 100,
"currency": "GBP",
"reference": "Acme refund",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"status": "created",
"metadata": {
"reason": "late failure"
},
"links": {
"payment": "PM123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->refunds()->get("RF123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.refunds.get("RF123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.refunds.get("RF123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Refund refund = client.refunds().get("RF123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const refund = await client.refunds.find("RF123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var refundResponse = await gocardless.Refunds.GetAsync("RF0123");
GoCardless.Resources.Refund refund = refundResponse.Refund;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
refund, err := client.Refunds.Get(context, "RF123")
}
Update a refund
Updates a refund object.
Relative endpoint: PUT /refunds/RF123
Parameters
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.
PUT https://api.gocardless.com/refunds/RF123 HTTP/1.1
Content-Type: application/json
{
"refunds": {
"metadata": {
"key": "value"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"refunds": {
"id": "RF123",
"created_at": "2014-05-08T17:01:06.000Z",
"amount": 100,
"currency": "GBP",
"reference": "Acme refund",
"fx": {
"fx_currency": "EUR",
"fx_amount": null,
"exchange_rate": null,
"estimated_exchange_rate": "1.1234567890"
},
"status": "created",
"metadata": {
"key": "value"
},
"links": {
"payment": "PM123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->refunds()->update("RF123", [
"params" => ["metadata" => ["key" => "value"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.refunds.update("RF123", params={
"metadata": {"key": "value"}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.refunds.update(
"RF123",
params: {
metadata: { reason: "Late delivery", internal_code: "refund_1A" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.refunds().update("RF123")
.withMetadata("internal_code", "refund_1A")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const refund = await client.refunds.update(
"RF123",
{
metadata: {
key: "value"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var refundRequest = new GoCardless.Services.RefundUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{"reason", "Late delivery"}
}
};
var refundResponse = await gocardless.Refunds.UpdateAsync("RF0123", refundRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
refundUpdateParams := gocardless.RefundUpdateParams{
Metadata: map[string]interface{}{"key": "value"}
}
refund, err := client.Refunds.Update(context, "RF123", refundUpdateParams)
}
Scenario Simulators
Scenario Simulators allow you to manually trigger and test certain paths that your integration will encounter in the real world. These endpoints are only active in the sandbox environment.
Properties
id
- The unique identifier of the simulator, used to initiate simulations. One of:
-
creditor_verification_status_action_required
: Sets a creditor’sverification status
toaction required
, meaning that the creditor must provide further information to GoCardless in order to verify their account to receive payouts. -
creditor_verification_status_in_review
: Sets a creditor’sverification status
toin review
, meaning that the creditor has provided all of the information requested by GoCardless to verify their account, and is now awaiting review. -
creditor_verification_status_successful
: Sets a creditor’sverification status
tosuccessful
, meaning that the creditor is fully verified and can receive payouts. -
payment_confirmed
: Transitions a payment through toconfirmed
. It must start in thepending_submission
state, and its mandate must be in theactivated
state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may bepending_submission
, since their mandates are submitted with their first payment). -
payment_paid_out
: Transitions a payment through topaid_out
, having been collected successfully and paid out to you. It must start in thepending_submission
state, and its mandate must be in theactivated
state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may bepending_submission
, since their mandates are submitted with their first payment). -
payment_failed
: Transitions a payment through tofailed
. It must start in thepending_submission
state, and its mandate must be in theactivated
state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may bepending_submission
, since their mandates are submitted with their first payment). -
payment_charged_back
: Behaves the same as thepayout_paid_out
simulator, except that the payment is transitioned tocharged_back
after it is paid out, having been charged back by the customer. -
payment_chargeback_settled
: Behaves the same as thepayment_charged_back
simulator, except that the charged back payment is additionally included as a debit item in a payout, thereby settling the charged back payment. -
payment_late_failure
: Transitions a payment through tolate_failure
, having been apparently collected successfully beforehand. It must start in thepending_submission
state, and its mandate must be in theactivated
state (unless it is a payment for ACH, BECS, BECS_NZ or SEPA, in which cases the mandate may bepending_submission
, since their mandates are submitted with their first payment). Not compatible with Autogiro mandates. -
payment_late_failure_settled
: Behaves the same as thepayment_late_failure
simulator, except that the late failure is additionally included as a debit item in a payout, thereby settling the late failure. -
payment_submitted
: Transitions a payment tosubmitted
, without proceeding any further. It must start in thepending_submission
state. -
mandate_activated
: Transitions a mandate through toactivated
, having been submitted to the banks and set up successfully. It must start in thepending_submission
state. Not compatible with ACH, BECS, BECS_NZ and SEPA mandates, which are submitted and activated with their first payment. -
mandate_customer_approval_granted
: Transitions a mandate through topending_submission
, as if the customer approved the mandate creation. It must start in thepending_customer_approval
state. Compatible only with Bacs and SEPA mandates, which support customer signatures on the mandate. All payments associated with the mandate will be transitioned topending_submission
. All subscriptions associated with the mandate will becomeactive
. -
mandate_customer_approval_skipped
: Transitions a mandate through topending_submission
, as if the customer skipped the mandate approval during the mandate creation process. It must start in thepending_customer_approval
state. Compatible only with Bacs and SEPA mandates, which support customer signatures on the mandate. All payments associated with the mandate will be transitioned topending_submission
. All subscriptions associated with the mandate will becomeactive
. -
mandate_failed
: Transitions a mandate through tofailed
, having been submitted to the banks but found to be invalid (for example due to invalid bank details). It must start in thepending_submission
orsubmitted
states. Not compatible with SEPA mandates, which are submitted with their first payment. -
mandate_expired
: Transitions a mandate through toexpired
, having been submitted to the banks, set up successfully and then expired because no collection attempts were made against it for longer than the scheme’s dormancy period (13 months for Bacs, 3 years for SEPA, 15 months for ACH, Betalingsservice, and BECS). It must start in thepending_submission
state. Not compatible with Autogiro, BECS NZ, and PAD mandates, which do not expire. -
mandate_transferred
: Transitions a mandate through totransferred
, having been submitted to the banks, set up successfully and then moved to a new bank account due to the customer using the UK’s Current Account Switching Service (CASS). It must start in thepending_submission
state. Only compatible with Bacs mandates. -
mandate_transferred_with_resubmission
: Transitions a mandate throughtransferred
and resubmits it to the banks, can be caused be the UK’s Current Account Switching Service (CASS) or when a customer contacts GoCardless to change their bank details. It must start in thepending_submission
state. Only compatible with Bacs mandates. -
mandate_suspended_by_payer
: Transitions a mandate tosuspended_by_payer
, as if payer has suspended the mandate after it has been setup successfully. It must start in theactivated
state. Only compatible with PAY_TO mandates. -
refund_paid
: Transitions a refund topaid
. It must start in either thepending_submission
orsubmitted
state. -
refund_settled
: Transitions a refund topaid
, if it’s not already, then generates a payout that includes the refund, thereby settling the funds. It must start in one ofpending_submission
,submitted
orpaid
states. -
refund_bounced
: Transitions a refund tobounced
. It must start in either thepending_submission
,submitted
, orpaid
state. -
refund_returned
: Transitions a refund torefund_returned
. The refund must start inpending_submission
. -
payout_bounced
: Transitions a payout tobounced
. It must start in thepaid
state. -
billing_request_fulfilled
: Authorises the billing request, and then fulfils it. The billing request must be in thepending
state, with all actions completed except forbank_authorisation
. Only billing requests with apayment_request
are supported. -
billing_request_fulfilled_and_payment_failed
: Authorises the billing request, fulfils it, and moves the associated payment tofailed
. The billing request must be in thepending
state, with all actions completed except forbank_authorisation
. Only billing requests with apayment_request
are supported. -
billing_request_fulfilled_and_payment_paid_out
: Authorises the billing request, fulfils it, and moves the associated payment topaid_out
. The billing request must be in thepending
state, with all actions completed except forbank_authorisation
. Only billing requests with apayment_request
are supported.
-
Simulate a scenario
Runs the specific scenario simulator against the specific resource
Relative endpoint: POST /scenario_simulators/payment_failed/actions/run
Parameters
links
[resource] - ID of the resource to run the simulation against.
Must be same type of resource as the simulator that is being run.
eg. Payment ID for
payment_failed
, Mandate ID formandate_activated
etc
POST https://api.gocardless.com/scenario_simulators/payment_failed/actions/run HTTP/1.1
Content-Type: application/json
{
"data": {
"links": {
"resource": "PM123"
}
}
}
HTTP/1.1 200 OK
{}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->scenarioSimulators()->run("payment_failed", [
"params" => ["links" => ["resource" => "PM123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.scenario_simulators.run("payment_failed", params={
"links": { "resource": "PM123" }
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.scenario_simulators.run(
"payment_failed",
params: { links: { resource: "PM123" } }
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.scenario_simulators().run("payment_failed")
.withLinks("resource", "PM123").
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const response = await client.scenarioSimulators.run(
"payment_failed",
{
links: {
resource: "PM123"
}
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var simulateRequest = new GoCardless.Services.ScenarioSimulatorRunRequest()
{
Links = new Dictionary<string, string>()
{
{"resource", "PM123"}
}
};
var response = await gocardless.ScenarioSimulators.RunAsync(
"payment_failed", simulateRequest
);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
scenarioSimulatorRunParams := gocardless.ScenarioSimulatorRunParams{
Links: &gocardless.ScenarioSimulatorRunParamsLinks{
Resource: "PM123",
},
}
action := "payment_failed"
scenarioSimulator, err := client.ScenarioSimulators.Run(context, action, scenarioSimulatorRunParams)
}
Scheme Identifiers
This represents a scheme identifier (e.g. a SUN in Bacs or a CID in SEPA). Scheme identifiers are used to specify the beneficiary name that appears on customers’ bank statements.
Properties
id
- Unique identifier, usually beginning with “SU”.
address_
line1 - The first line of the scheme identifier’s support address.
address_
line2 - The second line of the scheme identifier’s support address.
address_
line3 - The third line of the scheme identifier’s support address.
can_
specify_ mandate_ reference - Whether a custom reference can be submitted for mandates using this scheme identifier.
city
- The city of the scheme identifier’s support address.
country_
code - ISO 3166-1 alpha-2 code.
created_
at - Fixed timestamp, recording when this resource was created.
currency
- The currency of the scheme identifier.
email
- Scheme identifier’s support email address.
minimum_
advance_ notice - The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier.
By default, GoCardless sends these notifications automatically. Please see our compliance requirements for more details.
name
- The name which appears on customers’ bank statements. This should usually be the merchant’s trading name.
phone_
number - Scheme identifier’s support phone number.
postal_
code - The scheme identifier’s support postal code.
reference
- The scheme-unique identifier against which payments are submitted.
region
- The scheme identifier’s support address region, county or department.
scheme
- The scheme which this scheme identifier applies to.
status
- The status of the scheme identifier. Only
active
scheme identifiers will be applied to a creditor and used against payments.
Create a scheme identifier
Creates a new scheme identifier. The scheme identifier status will be pending
while GoCardless is
processing the request. Once the scheme identifier is ready to be used the status will be updated to active
.
At this point, GoCardless will emit a scheme identifier activated event via webhook to notify you of this change.
In Bacs, it will take up to five working days for a scheme identifier to become active. On other schemes, including SEPA,
this happens instantly.
Scheme identifier name validations
The name
field of a scheme identifier can contain alphanumeric characters, spaces and
special characters.
Its maximum length and the special characters it supports depend on the scheme:
scheme | maximum length | special characters allowed |
---|---|---|
bacs | 18 characters | / . & - |
sepa | 70 characters | / ? : ( ) . , + & < > ' " |
ach | 16 characters | / ? : ( ) . , ' + - |
faster_ |
18 characters | / ? : ( ) . , ' + - |
The validation error that gets returned for an invalid name will contain a suggested name in the metadata that is guaranteed to pass name validations.
You should ensure that the name you set matches the legal name or the trading name of the creditor, otherwise, there is an increased risk of chargeback.
Relative endpoint: POST /scheme_identifiers
Restricted: This endpoint is restricted to GoCardless Embed customers. Please contact us if you are interested in using this product.
Parameters
name
- required The name which appears on customers’ bank statements. This should usually be the merchant’s trading name.
scheme
- required The scheme which this scheme identifier applies to.
links
[creditor] - required ID of the associated creditor.
POST https://api.gocardless.com/scheme_identifiers HTTP/1.1
Content-Type: application/json
{
"scheme_identifiers": {
"name": "The Wine Club",
"scheme": "bacs",
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 201 Created
Location: /scheme_identifiers/SU123
Content-Type: application/json
{
"scheme_identifiers": {
"id": "SU123",
"created_at": "2021-01-23T13:44:19.006Z",
"name": "The Wine Club",
"scheme": "bacs",
"reference": null,
"status": "pending",
"minimum_advance_notice": 3,
"can_specify_mandate_reference": false,
"currency": "GBP",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"email": null,
"phone_number": null
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->schemeIdentifiers()->create([
'params' => ['scheme' => 'bacs',
'name' => 'Example Ltd',
'links' => ['creditor' => 'CR123']
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.scheme_identifiers.create(params={
"scheme": "bacs",
"name": "Example Ltd",
"links": {
"creditor": "CR123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.scheme_identifiers.create(
params: {
scheme: "bacs",
name: "Example Ltd",
links: {
creditor: "CR123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
SchemeIdentifier schemeIdentifier = client.schemeIdentifiers().create()
.withScheme(SchemeIdentifierService.SchemeIdentifierCreateRequest.Scheme.BACS)
.withName("The Wine Club")
.withLinksCreditor("CR123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const schemeIdentifier = await client.schemeIdentifiers.create({
scheme: "bacs",
name: "The Wine Club",
links: {
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
SchemeIdentifierCreateRequest schemeIdentifierRequest = new SchemeIdentifierCreateRequest
{
Name = "The Wine Club",
Scheme = SchemeIdentifierCreateRequest.SchemeIdentifierScheme.Bacs,
Links = new SchemeIdentifierCreateRequest.SchemeIdentifierLinks()
{
Creditor = "CR123"
}
};
var schemeIdentifierResponse = await client.SchemeIdentifiers.CreateAsync(schemeIdentifierRequest);
GoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
context := context.Background()
schemeIdentifierCreateParams := gocardless.SchemeIdentifierCreateParams{
Name: "Durian Co",
Scheme: "bacs",
Links: gocardless.SchemeIdentifierCreateParamsLinks{
Creditor: "CR123",
},
}
schemeIdentifier, err := client.SchemeIdentifiers.Create(context, schemeIdentifierCreateParams)
if err != nil {
fmt.Printf("error creating scheme identifier: %s", err.Error())
return
}
}
List scheme identifiers
Returns a cursor-paginated list of your scheme identifiers.
Relative endpoint: GET /scheme_identifiers
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
creditor
- Unique identifier, beginning with “CR”.
limit
- Number of records to return.
GET https://api.gocardless.com/scheme_identifiers HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"scheme_identifiers": [
{
"id": "SU123",
"created_at": "2021-01-23T09:41:36.234Z",
"name": "The Wine Club",
"scheme": "bacs",
"reference": null,
"status": "active",
"minimum_advance_notice": 3,
"can_specify_mandate_reference": false,
"currency": "GBP",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"email": null,
"phone_number": null
}
],
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->schemeIdentifiers()->list()->records;
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.scheme_identifiers.list().records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.scheme_identifiers.list.records
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (SchemeIdentifier schemeIdentifier: client.schemeIdentifiers().all().execute()) {
System.out.println(schemeIdentifier.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const schemeIdentifierList = await client.schemeIdentifiers.list();
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var schemeIdentifierListResponse = client.SchemeIdentifiers.All();
foreach (GoCardless.Resources.SchemeIdentifier schemeIdentifier in schemeIdentifierListResponse)
{
Console.WriteLine(schemeIdentifier.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
context := context.Background()
schemeIdentifierListParams := gocardless.SchemeIdentifierListParams{}
schemeIdentifeirListResult, err := client.SchemeIdentifiers.List(context, schemeIdentifierListParams)
if err != nil {
fmt.Printf("error listing scheme identifiers: %s", err.Error())
return
}
for _, schemeIdentifier := range schemeIdentifeirListResult.SchemeIdentifiers {
fmt.Println(schemeIdentifier.Id)
}
}
Get a single scheme identifier
Retrieves the details of an existing scheme identifier.
Relative endpoint: GET /scheme_identifiers/SU123
GET https://api.gocardless.com/scheme_identifiers/SU123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"scheme_identifiers": {
"id": "SU123",
"created_at": "2021-01-23T09:41:36.234Z",
"name": "The Wine Club",
"scheme": "bacs",
"reference": null,
"status": "active",
"minimum_advance_notice": 3,
"can_specify_mandate_reference": false,
"currency": "GBP",
"address_line1": null,
"address_line2": null,
"address_line3": null,
"city": null,
"region": null,
"postal_code": null,
"country_code": null,
"email": null,
"phone_number": null
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->schemeIdentifiers()->get('SU123');
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.scheme_identifiers.get("SU123").attributes
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.scheme_identifiers.get("SU123").attributes
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
SchemeIdentifier schemeIdentifier = client.schemeIdentifiers().get("SU123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const schemeIdentifier = await client.schemeIdentifiers.find("SU123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var schemeIdentifierResponse = await client.SchemeIdentifiers.GetAsync("SU123");
GoCardless.Resources.SchemeIdentifier schemeIdentifier = schemeIdentifierResponse.SchemeIdentifier;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
context := context.Background()
schemeIdentifier, err := client.SchemeIdentifiers.Get(context, "SU123")
if err != nil {
fmt.Printf("error getting scheme identifier: %s", err.Error())
return
}
}
Subscriptions
Subscriptions create payments according to a schedule.
Recurrence Rules
The following rules apply when specifying recurrence:
- If
day_of_month
andstart_date
are not providedstart_date
will be the mandate’snext_possible_charge_date
and the subscription will then recur based on theinterval
&interval_unit
- If
month
orday_of_month
are present the following validations apply:
interval_unit | month | day_of_month |
---|---|---|
yearly | optional (required if day_ |
optional (invalid if month not provided) |
monthly | invalid | optional |
weekly | invalid | invalid |
Examples:
interval_unit | interval | month | day_of_month | valid? |
---|---|---|---|---|
yearly | 1 | january | -1 | valid |
monthly | 6 | valid | ||
monthly | 6 | 12 | valid | |
weekly | 2 | valid | ||
yearly | 1 | march | invalid - missing day_ |
|
yearly | 1 | 2 | invalid - missing month | |
monthly | 6 | august | 12 | invalid - month must be blank |
weekly | 2 | october | 10 | invalid - month and day_ |
Rolling dates
When a charge date falls on a non-business day, one of two things will happen:
- if the recurrence rule specified
-1
as theday_of_month
, the charge date will be rolled backwards to the previous business day (i.e., the last working day of the month). -
otherwise the charge date will be rolled forwards to the next business day.
Properties
id
- Unique identifier, beginning with “SB”.
amount
- Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
app_
fee - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
count
- The total number of payments that should be taken by this subscription.
created_
at - Fixed timestamp, recording when this resource was created.
currency
- ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
day_
of_ month - As per RFC 2445. The day of the month to charge customers on.
1
-28
or-1
to indicate the last day of the month. earliest_
charge_ date_ after_ resume - The earliest date that will be used as a
charge_date
on payments created for this subscription if it is resumed. Only present forpaused
subscriptions. This value will change over time. end_
date - Date on or after which no further payments should be created.
If this field is blank andcount
is not specified, the subscription will continue forever.
Deprecated: This field will be removed in a future API version. Usecount
to specify a number of payments instead. interval
- Number of
interval_units
between customer charge dates. Must be greater than or equal to1
. Must result in at least one charge date per year. Defaults to1
. interval_
unit - The unit of time between customer charge dates. One of
weekly
,monthly
oryearly
. 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.
month
- Name of the month on which to charge a customer. Must be lowercase. Only applies
when the interval_unit is
yearly
. name
- Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
parent_
plan_ paused - Whether the parent plan of this subscription is paused.
payment_
reference - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
Restricted: You need your own Service User Number to specify a payment reference for Bacs payments. retry_
if_ possible - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. start_
date - The date on which the first payment should be charged. Must be on or after the mandate’s
next_possible_charge_date
. When left blank andmonth
orday_of_month
are provided, this will be set to the date of the first payment. If created withoutmonth
orday_of_month
this will be set as the mandate’snext_possible_charge_date
status
- One of:
-
pending_customer_approval
: the subscription is waiting for customer approval before becoming active -
customer_approval_denied
: the customer did not approve the subscription -
active
: the subscription is currently active and will continue to create payments -
finished
: all of the payments scheduled for creation under this subscription have been created -
cancelled
: the subscription has been cancelled and will no longer create payments -
paused
: the subscription has been paused and will not create payments
-
upcoming_
payments - Up to 10 upcoming payments with their amounts and charge dates.
Each instance will contain these properties:
-
amount
: The amount of this payment, in minor unit (e.g. pence in GBP, cents in EUR). -
charge_date
: The date on which this payment will be charged.
-
links
[mandate] - ID of the associated mandate which the subscription will create payments against.
Create a subscription
Creates a new subscription object
Relative endpoint: POST /subscriptions
Parameters
amount
- required Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
currency
- required ISO 4217 currency code. Currently “AUD”, “CAD”, “DKK”, “EUR”, “GBP”, “NZD”, “SEK” and “USD” are supported.
interval_
unit -
required The unit of time between customer charge dates. One of
weekly
,monthly
oryearly
. app_
fee - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
count
- The total number of payments that should be taken by this subscription.
day_
of_ month - As per RFC 2445. The day of the month to charge customers on.
1
-28
or-1
to indicate the last day of the month. end_
date - Date on or after which no further payments should be created.
If this field is blank andcount
is not specified, the subscription will continue forever.
Deprecated: This field will be removed in a future API version. Usecount
to specify a number of payments instead. interval
- Number of
interval_units
between customer charge dates. Must be greater than or equal to1
. Must result in at least one charge date per year. Defaults to1
. 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.
month
- Name of the month on which to charge a customer. Must be lowercase. Only applies
when the interval_unit is
yearly
. name
- Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
payment_
reference - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
Restricted: You need your own Service User Number to specify a payment reference for Bacs payments. retry_
if_ possible - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard. start_
date - The date on which the first payment should be charged. Must be on or after the mandate’s
next_possible_charge_date
. When left blank andmonth
orday_of_month
are provided, this will be set to the date of the first payment. If created withoutmonth
orday_of_month
this will be set as the mandate’snext_possible_charge_date
links
[mandate] - required ID of the associated mandate which the subscription will create payments against.
POST https://api.gocardless.com/subscriptions HTTP/1.1
Content-Type: application/json
{
"subscriptions": {
"amount": "2500",
"currency": "GBP",
"name": "Monthly Magazine",
"interval_unit": "monthly",
"day_of_month": "1",
"metadata": {
"order_no": "ABCD1234"
},
"links": {
"mandate": "MA123"
}
}
}
HTTP/1.1 201 Created
Location: /subscriptions/SB123
Content-Type: application/json
{
"subscriptions": {
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "active",
"name": "Monthly Magazine",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"app_fee": null,
"earliest_charge_date_after_resume": null,
"upcoming_payments": [
{ "charge_date": "2014-11-03", "amount": 2500 },
{ "charge_date": "2014-12-01", "amount": 2500 },
{ "charge_date": "2015-01-02", "amount": 2500 },
{ "charge_date": "2015-02-02", "amount": 2500 },
{ "charge_date": "2015-03-02", "amount": 2500 },
{ "charge_date": "2015-04-01", "amount": 2500 },
{ "charge_date": "2015-05-01", "amount": 2500 },
{ "charge_date": "2015-06-01", "amount": 2500 },
{ "charge_date": "2015-07-01", "amount": 2500 },
{ "charge_date": "2015-08-03", "amount": 2500 }
],
"metadata": {
"order_no": "ABCD1234"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->create([
"params" => ["amount" => 2500,
"currency" => "GBP",
"name" => "Monthly Magazine",
"interval_unit" => "monthly",
"day_of_month" => 1,
"metadata" => ["order_no" => "ABCD1234"],
"links" => ["mandate" => "MA123"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.create(params={
"amount": "2500",
"currency": "GBP",
"name": "Monthly Magazine",
"interval_unit": "monthly",
"day_of_month": "1",
"metadata": {
"order_no": "ABCD1234"
},
"links": {
"mandate": "MA123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.create(
params: {
amount: 2500,
currency: "GBP",
name: "Monthly magazine",
interval_unit: "monthly",
day_of_month: 1,
links: {
mandate: "MD123"
}
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
import com.gocardless.services.SubscriptionService.SubscriptionCreateRequest.IntervalUnit;
Subscription subscription = client.subscriptions().create()
.withAmount(2500)
.withCurrency("GBP")
.withName("Monthly Magazine")
.withIntervalUnit(IntervalUnit.MONTHLY)
.withDayOfMonth(1)
.withMetadata("order_no", "ABCD1234")
.withLinksMandate("MD123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscription = await client.subscriptions.create({
amount: "2500",
currency: "GBP",
name: "Monthly Magazine",
interval_unit: "monthly",
day_of_month: "1",
metadata": {
order_no: "ABCD1234"
},
links: {
mandate: "MA123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionRequest = new GoCardless.Services.SubscriptionCreateRequest()
{
Amount = 1000,
Currency = "GBP",
Name = "Monthly subscription",
Interval = 1,
IntervalUnit = GoCardless.Services.SubscriptionCreateRequest.SubscriptionIntervalUnit.Monthly,
Links = new GoCardless.Services.SubscriptionCreateRequest.SubscriptionLinks()
{
Mandate = "MD0123"
}
};
var subscriptionResponse = await gocardless.Subscriptions.CreateAsync(subscriptionRequest);
GoCardless.Resources.Subscription subscription = subscriptionResponse.Subscription;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscriptionCreateParams := gocardless.SubscriptionCreateParams{
Amount: 1500, // 15 GBP in pence
Currency: "GBP",
IntervalUnit: "monthly",
DayOfMonth: 5,
Links: gocardless.SubscriptionCreateParamsLinks{
Mandate: "MD123",
},
Metadata: map[string]interface{}{"subscription_number": "ABC123"},
}
subscription, err := client.Subscriptions.Create(ctx, subscriptionCreateParams)
}
List subscriptions
Returns a cursor-paginated list of your subscriptions. Please note if the subscriptions are related to customers who have been removed, they will not be shown in the response.
Relative endpoint: GET /subscriptions
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
customer
- Unique identifier, beginning with “CU”.
limit
- Number of records to return.
mandate
- Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016.
status
- Upto 5 of:
-
pending_customer_approval
-
customer_approval_denied
-
active
-
finished
-
cancelled
-
paused
-
Omit entirely to include subscriptions in all states.
GET https://api.gocardless.com/subscriptions HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"before": null,
"after": null
},
"limit": 50
},
"subscriptions": [{
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "active",
"name": "Monthly Magazine",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"earliest_charge_date_after_resume": null,
"parent_plan_paused": false,
"upcoming_payments": [
{ "charge_date": "2014-11-03", "amount": 2500 },
{ "charge_date": "2014-12-01", "amount": 2500 },
{ "charge_date": "2015-01-02", "amount": 2500 },
{ "charge_date": "2015-02-02", "amount": 2500 },
{ "charge_date": "2015-03-02", "amount": 2500 },
{ "charge_date": "2015-04-01", "amount": 2500 },
{ "charge_date": "2015-05-01", "amount": 2500 },
{ "charge_date": "2015-06-01", "amount": 2500 },
{ "charge_date": "2015-07-01", "amount": 2500 },
{ "charge_date": "2015-08-03", "amount": 2500 }
],
"metadata": {
"order_no": "ABCD1234"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->list();
$client->subscriptions()->list([
"params" => ["customer" => "CU123"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.list().records
client.subscriptions.list(params={"customer": "CU123"}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.list
@client.subscriptions.list(params: { customer: "CU123" })
@client.subscriptions.list.records.each { |subscription| puts subscription.inspect }
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Subscription subscription : client.subscriptions().all().withCustomer("CU123").execute()) {
System.out.println(subscription.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscriptions = await client.subscriptions.list();
// List all subscriptions associated with a given customer.
const subscriptions = await client.subscriptions.list({ customer: "CU123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionRequest = new GoCardless.Services.SubscriptionListRequest()
{
Customer = "CU000123"
};
var subscriptionListResponse = gocardless.Subscriptions.All(subscriptionRequest);
foreach (GoCardless.Resources.Subscription subscription in subscriptionListResponse)
{
Console.WriteLine(subscription.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscriptionListParams := gocardless.SubscriptionListParams{}
subscriptionListResult, err := client.Subscriptions.List(context, subscriptionListParams)
for _, subscription := subscriptionListResult.Subscriptions {
fmt.Println(subscription.Id)
}
}
Get a single subscription
Retrieves the details of a single subscription.
Relative endpoint: GET /subscriptions/SB123
GET https://api.gocardless.com/subscriptions/SB123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": {
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "active",
"name": "Monthly Magazine",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"earliest_charge_date_after_resume": null,
"parent_plan_paused": false,
"upcoming_payments": [
{ "charge_date": "2014-11-03", "amount": 2500 },
{ "charge_date": "2014-12-01", "amount": 2500 },
{ "charge_date": "2015-01-02", "amount": 2500 },
{ "charge_date": "2015-02-02", "amount": 2500 },
{ "charge_date": "2015-03-02", "amount": 2500 },
{ "charge_date": "2015-04-01", "amount": 2500 },
{ "charge_date": "2015-05-01", "amount": 2500 },
{ "charge_date": "2015-06-01", "amount": 2500 },
{ "charge_date": "2015-07-01", "amount": 2500 },
{ "charge_date": "2015-08-03", "amount": 2500 }
],
"metadata": {
"order_no": "ABCD1234"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->get("SB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.get("SB123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.get("SB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Subscription subscription = client.subscriptions().get("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscription = await client.subscriptions.find("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionResponse = await gocardless.Subscriptions.GetAsync("SB0123");
GoCardless.Resources.Subscription subscription = subscriptionResponse.Subscription;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscription, err := client.Subscriptions.Get(context, "SB123")
}
Update a subscription
Updates a subscription object.
This fails with:
-
validation_failed
if invalid data is provided when attempting to update a subscription. -
subscription_not_active
if the subscription is no longer active. -
subscription_already_ended
if the subscription has taken all payments. -
mandate_payments_require_approval
if the amount is being changed and the mandate requires approval. -
number_of_subscription_amendments_exceeded
error if the subscription amount has already been changed 10 times. -
forbidden
if the amount is being changed, and the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app -
resource_created_by_another_app
if the app fee is being changed, and the subscription was created by an app other than the app you are authenticated as
Relative endpoint: PUT /subscriptions/SB123
Parameters
amount
- Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
app_
fee - The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
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.
name
- Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters.
payment_
reference - An optional payment reference. This will be set as the reference on each payment
created and will appear on your customer’s bank statement. See the documentation for
the create payment endpoint for more details.
Restricted: You need your own Service User Number to specify a payment reference for Bacs payments. retry_
if_ possible - On failure, automatically retry payments using intelligent retries. Default is
false
. Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.
PUT https://api.gocardless.com/subscriptions/SU123 HTTP/1.1
Content-Type: application/json
{
"subscriptions": {
"name": "New name",
"metadata": {
"order_no": "ABCD4321"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": {
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "active",
"name": "New name",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"earliest_charge_date_after_resume": null,
"parent_plan_paused": false,
"upcoming_payments": [
{ "charge_date": "2014-11-03", "amount": 2500 },
{ "charge_date": "2014-12-01", "amount": 2500 },
{ "charge_date": "2015-01-02", "amount": 2500 },
{ "charge_date": "2015-02-02", "amount": 2500 },
{ "charge_date": "2015-03-02", "amount": 2500 },
{ "charge_date": "2015-04-01", "amount": 2500 },
{ "charge_date": "2015-05-01", "amount": 2500 },
{ "charge_date": "2015-06-01", "amount": 2500 },
{ "charge_date": "2015-07-01", "amount": 2500 },
{ "charge_date": "2015-08-03", "amount": 2500 }
],
"metadata": {
"order_no": "ABCD4321"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->update("SB123", [
"params" => ["name" => "New name",
"metadata" => ["order_no" => "ABCD4321"]]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.update("SB123", params={
"name": "New name"
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.update(
"SB123",
params: {
metadata: { order_no: "ABCD4321" }
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.subscriptions().update("SB123")
.withName("New name")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscription = await client.subscriptions.update(
"SB123",
{
amount: "42",
name: "New Name"
}
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionRequest = new GoCardless.Services.SubscriptionUpdateRequest()
{
Metadata = new Dictionary<string, string>()
{
{“custom_reference", "ref_09011991"}
}
};
var subscriptionResponse = await gocardless.Subscriptions.UpdateAsync(“SB0123", subscriptionRequest);
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscriptionUpdateParams := gocardless.SubscriptionUpdateParams{
Amount: 4200,
Name: "New Name",
}
subscription, err := client.Subscriptions.Update(context, "SB123", subscriptionUpdateParams)
}
Pause a subscription
Pause a subscription object. No payments will be created until it is resumed.
This can only be used when a subscription is collecting a fixed number of payments (created using count
),
when they continue forever (created without count
or end_date
) or
the subscription is already paused for a number of cycles.
When pause_cycles
is omitted the subscription is paused until the resume endpoint is called.
If the subscription is collecting a fixed number of payments, end_date
will be set to null
.
When paused indefinitely, upcoming_payments
will be empty.
When pause_cycles
is provided the subscription will be paused for the number of cycles requested.
If the subscription is collecting a fixed number of payments, end_date
will be set to a new value.
When paused for a number of cycles, upcoming_payments
will still contain the upcoming charge dates.
This fails with:
-
forbidden
if the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app -
validation_failed
if invalid data is provided when attempting to pause a subscription. -
subscription_paused_cannot_update_cycles
if the subscription is already paused for a number of cycles and the request provides a value forpause_cycle
. -
subscription_cannot_be_paused
if the subscription cannot be paused. -
subscription_already_ended
if the subscription has taken all payments. -
pause_cycles_must_be_greater_than_or_equal_to
if the provided value forpause_cycles
cannot be satisfied.
Relative endpoint: POST /subscriptions/SB123/actions/pause
Warning: Please note that any payments that have already been created from this subscription will still be collected unless you manually cancel them.
Parameters
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.
pause_
cycles - The number of cycles to pause a subscription for. A cycle is one duration of
interval
andinterval_unit
. This should be a non zero positive value. For AUD subscriptions withinterval_unit: weekly
the minimum value varies between3
&4
because of the mandatory minimum waiting period. For NZD subscriptions withinterval_unit: weekly
the minimum value is2
because of the mandatory minimum waiting period.
POST https://api.gocardless.com/subscriptions/SU123/actions/pause HTTP/1.1
Content-Type: application/json
{
"data": {
"metadata": {}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": {
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "paused",
"name": "Subscription name",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"earliest_charge_date_after_resume": "2014-10-23",
"parent_plan_paused": false,
"upcoming_payments": [
],
"metadata": {
"order_no": "ABCD4321"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->pause("SB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.pause("SB123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.pause("SB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.subscriptions().pause("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscriptionResponse = await client.subscriptions.pause("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionResponse = await gocardless.Subscriptions.PauseAsync(“SB0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscriptionPauseParams := gocardless.SubscriptionPauseParams{}
subscription, err := client.Subscriptions.Pause(context, "SB123",subscriptionPauseParams)
}
Resume a subscription
Resume a subscription object.
Payments will start to be created again based on the subscriptions recurrence rules.
The charge_date
on the next payment will be the same as the subscriptions earliest_charge_date_after_resume
This fails with:
-
forbidden
if the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app -
validation_failed
if invalid data is provided when attempting to resume a subscription. -
subscription_not_paused
if the subscription is not paused.
Relative endpoint: POST /subscriptions/SB123/actions/resume
Warning: There is a mandatory minimum 14 business day wait between resuming an AUD
subscription and its next charge date.
There is a mandatory minimum 10 calendar day wait between resuming an NZD
subscription and its next charge date.
Parameters
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.
POST https://api.gocardless.com/subscriptions/SU123/actions/resume HTTP/1.1
Content-Type: application/json
{
"data": {
"metadata": {}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": {
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "active",
"name": "Subscription name",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"earliest_charge_date_after_resume": null,
"parent_plan_paused": false,
"upcoming_payments": [
{ "charge_date": "2014-11-03", "amount": 2500 },
{ "charge_date": "2014-12-01", "amount": 2500 },
{ "charge_date": "2015-01-02", "amount": 2500 },
{ "charge_date": "2015-02-02", "amount": 2500 },
{ "charge_date": "2015-03-02", "amount": 2500 },
{ "charge_date": "2015-04-01", "amount": 2500 },
{ "charge_date": "2015-05-01", "amount": 2500 },
{ "charge_date": "2015-06-01", "amount": 2500 },
{ "charge_date": "2015-07-01", "amount": 2500 },
{ "charge_date": "2015-08-03", "amount": 2500 }
],
"metadata": {
"order_no": "ABCD4321"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->resume("SB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.resume("SB123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.resume("SB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.subscriptions().resume("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscriptionResponse = await client.subscriptions.resume("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionResponse = await gocardless.Subscriptions.ResumeAsync(“SB0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscriptionResumeParams := gocardless.SubscriptionResumeParams{}
subscription, err := client.Subscriptions.Resume(context, "SB123", subscriptionResumeParams)
}
Cancel a subscription
Immediately cancels a subscription; no more payments will be created under it. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.
This will fail with a cancellation_failed error if the subscription is already cancelled or finished.
Relative endpoint: POST /subscriptions/SB123/actions/cancel
Warning: Please note that this will not cancel any payments that have already been created from this subscription — these payments will still be collected unless you also manually cancel them.
Parameters
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.
POST https://api.gocardless.com/subscriptions/SU123/actions/cancel HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": {
"id": "SB123",
"created_at": "2014-10-20T17:01:06.000Z",
"amount": 2500,
"currency": "GBP",
"status": "cancelled",
"name": "Monthly Magazine",
"start_date": "2014-11-03",
"end_date": null,
"interval": 1,
"interval_unit": "monthly",
"day_of_month": 1,
"month": null,
"payment_reference": null,
"earliest_charge_date_after_resume": null,
"parent_plan_paused": false,
"upcoming_payments": [],
"metadata": {
"order_no": "ABCD1234"
},
"links": {
"mandate": "MA123"
},
"retry_if_possible": false
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->subscriptions()->cancel("SB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.subscriptions.cancel("SB123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.subscriptions.cancel("SB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.subscriptions().cancel("SB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const subscriptions = await client.subscriptions.cancel("SB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var subscriptionResponse = await gocardless.Subscriptions.CancelAsync("SB0123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
subscriptionCancelParams := gocardless.SubscriptionCancelParams{}
subscription, err := client.Subscriptions.Cancel(context, "SB123", subscriptionCancelParams)
}
Tax Rates
Tax rates from tax authority.
We also maintain a static list of the tax rates for each jurisdiction.
Properties
id
- The unique identifier created by the jurisdiction, tax type and version
end_
date - Date at which GoCardless stopped applying the tax rate for the jurisdiction.
jurisdiction
- The jurisdiction this tax rate applies to
percentage
- The percentage of tax that is applied onto of GoCardless fees
start_
date - Date at which GoCardless started applying the tax rate in the jurisdiction.
type
- The type of tax applied by this rate
List tax rates
Returns a cursor-paginated list of all tax rates.
Relative endpoint: GET /tax_rates
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
jurisdiction
- The jurisdiction this tax rate applies to
limit
- Number of records to return.
GET https://api.gocardless.com/tax_rates?jurisdiction=GB HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"tax_rates": [
{
"id": "GB_VAT_1",
"jurisdiction": "GB",
"type": "VAT",
"percentage": "20.0",
"start_date": "2020-02-24",
"end_date": null,
}
],
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 50
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->taxRates()->list([
"params" => ["jurisdiction" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.tax_rates.list(params={"jurisdiction": "GB" }).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.tax_rates.list(params: { jurisdiction: "GB" })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.taxRates().all().withJurisdiction("GB").execute()
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const taxRates = await client.taxRates.list();
// List the Tax rate for a jurisdiction.
const taxRates = await client.taxRates.list({ jurisdiction: 'GB'});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var request = new GoCardless.Services.TaxRateListRequest()
{
Jurisdiction = "GB",
};
var response = gocardless.TaxRates.All(request);
foreach (GoCardless.Resources.TaxRate rate in response)
{
Console.WriteLine(rate.Rate);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
taxRateListParams := gocardless.TaxRateListParams{
Jurisdiction: "GB",
}
taxRateListResult, err := client.TaxRates.List(context, taxRateListParams)
}
Get a single tax rate
Retrieves the details of a tax rate.
Relative endpoint: GET /tax_rates/GB_VAT_1
GET https://api.gocardless.com/tax_rates/GB_VAT_1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"tax_rates": {
"id": "GB_VAT_1",
"jurisdiction": "GB",
"type": "VAT",
"percentage": "20.0",
"start_date": "2020-02-24",
"end_date": null
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->taxRates()->get("GB_VAT_1");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.tax_rates.get("GB_VAT_1")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.tax_rates.get("GB_VAT_1")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
TaxRate taxRate = client.taxRates().get("GB_VAT_1").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const taxRate = await client.taxRate.find("GB_VAT_1");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var taxRateResponse = await gocardless.TaxRate.GetAsync("GB_VAT_1");
GoCardless.Resources.TaxRate taxRate = taxRateResponse.TaxRate;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
taxRate, err := client.TaxRates.Get(context, "GB_VAT_1")
}
Transferred Mandates
Mandates that have been transferred using Current Account Switch Service
Properties
encrypted_
customer_ bank_ details - Encrypted customer bank account details, containing:
iban
,account_holder_name
,swift_bank_code
,swift_branch_code
,swift_account_number
encrypted_
decryption_ key - Random AES-256 key used to encrypt bank account details, itself encrypted with your public key.
public_
key_ id - The ID of an RSA-2048 public key, from your JWKS, used to encrypt the AES key.
links
[customer_ bank_ account] - The ID of the updated customer_bank_account
links
[mandate] - The ID of the transferred mandate
Get updated customer bank details
Returns new customer bank details for a mandate that’s been recently transferred
Relative endpoint: GET /transferred_mandates/MD123
Note: See our Security Requirements before using this feature
Restricted: This endpoint is restricted to organisations with the Transfer Bank Accounts upgrade
Parameters
GET https://api.gocardless.com/transferred_mandates/MD123 HTTP/1.1
Content-Type: application/json
HTTP/1.1 200 (OK)
Location: /transferred_mandates/MD123
Content-Type: application/json
{
"transferred_mandates": {
"encrypted_decryption_key": "bXktZW5jcnlvcHRlZC1hZXMta2V5",
"public_key_id": "9770a024c90fb646e48c952ec5d4f53586e62e8154048e6b96dd9f74f164a472",
"encrypted_customer_bank_details": "OTc3MGEwMjRjOTBmYjY0NmU0OGM5NTJlYzVkNGY1MzU4NmU2MmU4MTU0MDQ4ZTZiOTZkZDlmNzRmMTY0YTQ3Mg==",
"links": {
"customer_bank_account": "BA123",
"mandate": "MD123"
}
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->transferred_mandates()->get("MD123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.transferred_mandates.get("MD123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.transferred_mandates.get("MD123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.transferredMandates().get("MD123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const transferredMandate = await client.transferredMandates.find("MD123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var response = await gocardless.TransferredMandates.GetAsync("MD123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
transferredMandate, err := client.TransferredMandates.Get(context, "MD123")
}
Verification Details
Verification details represent any information needed by GoCardless to verify a creditor.
Restricted: These endpoints are restricted to customers who want to collect their merchant’s verification details and pass them to GoCardless via our API. Please get in touch if you wish to enable this feature on your account.
Properties
address_
line1 - The first line of the company’s address.
address_
line2 - The second line of the company’s address.
address_
line3 - The third line of the company’s address.
city
- The city of the company’s address.
company_
number - The company’s registration number.
description
- A summary describing what the company does.
directors
- The company’s directors.
Each instance will contain these properties:
-
city
: The city of the person’s address. -
country_code
: ISO 3166-1 alpha-2 code. -
date_of_birth
: The person’s date of birth. -
family_name
: The person’s family name. -
given_name
: The person’s given name. -
postal_code
: The person’s postal code. -
street
: The street of the person’s address.
-
name
- The company’s legal name.
postal_
code - The company’s postal code.
links
[creditor] - ID of the creditor
Create a verification detail
Creates a new verification detail
Relative endpoint: POST /verification_details
Warning: This endpoint only supports UK based limited companies. Therefore the
creditor’s creditor_type
must be 'company'
and country_code
must be 'GB'
.
Parameters
address_
line1 - required The first line of the company’s address.
city
- required The city of the company’s address.
company_
number - required The company’s registration number.
description
- required A summary describing what the company does.
directors
- required The company’s directors.
name
- required The company’s legal name.
postal_
code - required The company’s postal code.
address_
line2 - The second line of the company’s address.
address_
line3 - The third line of the company’s address.
links
[creditor] - required ID of the associated creditor.
POST https://api.gocardless.com/verification_details/ HTTP/1.1
Content-Type: application/json
{
"verification_details": {
"name": "Acme Limited",
"company_number": "03768189",
"description": "wine and cheese seller",
"address_line1": "12 Drury lane",
"city": "London",
"postal_code": "B4 7NJ",
"directors": [{
"date_of_birth": "1986-02-19",
"given_name": "Gandalf",
"family_name": "Grey",
"city": "London",
"street": "Drury Lane",
"postal_code": "B4 7NJ",
"country_code": "GB"
}],
"links": {
"creditor": "CR123"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"verification_details": {
"name": "Acme Limited",
"company_number": "03768189",
"description": "wine and cheese seller",
"address_line1": "12 Drury lane",
"address_line2": null,
"address_line3": null,
"city": "London",
"region": null,
"postal_code": "B4 7NJ",
"country_code": "GB",
"directors": [{
"given_name": "Gandalf",
"family_name": "Grey",
"date_of_birth": "1986-02-19",
"street": "Drury lane",
"city":"London",
"postal_code":"B4 7NJ",
"country_code":"GB",
}],
},
"links": {
"creditor": "CR123"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$verification_details = $client->verificationDetails()->create([
'params' => [
'name' => 'Acme',
'company_number' => '03768189',
'address_line1' => '12 Drury lane',
'city' => 'London',
'description' => 'wine and cheese seller',
'postal_code' => 'B4 7NJ',
'directors' => [[
'given_name' => 'Gandalf',
'family_name' => 'Grey',
'city' => 'London',
'date_of_birth' => '1986-02-19',
'street' => 'Drury lane',
'postal_code' => 'B4 7NJ',
'country_code' => 'GB'
]],
'links' => [
'creditor' => 'CR123'
]
]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.verification_details.create(params={
"name": "Acme",
"company_number": "03768189",
"address_line1": "12 Drury lane",
"city": "London",
"description": "wine and cheese seller",
"postal_code": "B4 7NJ",
"directors": [{
"given_name": "Gandalf",
"family_name": "Grey",
"city": "London",
"date_of_birth": "1986-02-19",
"street": "Drury lane",
"postal_code": "B4 7NJ",
"country_code": "GB"
}],
"links": {
"creditor": "CR123"
}
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.verification_details.create(params: {
name: "Acme",
company_number: "03768189",
address_line1: "12 Drury lane",
city: "London",
description: "wine and cheese seller",
postal_code: "B4 7NJ",
directors: [{
given_name: "Gandalf",
family_name: "Grey",
city: "London",
date_of_birth: "1986-02-19",
street: "Drury lane",
postal_code: "B4 7NJ",
country_code: "GB",
}],
links: {
creditor: "CR123",
},
})
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
VerificationDetailService.VerificationDetailCreateRequest.Directors director = new VerificationDetailService.VerificationDetailCreateRequest.Directors();
director.withCity("London");
director.withCountryCode("GB");
director.withDateOfBirth("1986-02-19");
director.withGivenName("Gandalf");
director.withFamilyName("Grey");
director.withPostalCode("B4 7NJ");
director.withStreet("Drury Lane");
VerificationDetail verificationDetail = client.verificationDetails().create()
.withName("Acme")
.withDescription("wine and cheese seller")
.withCompanyNumber("03768189")
.withAddressLine1("12 Drury Lane")
.withCity("London")
.withPostalCode("B4 7NJ")
.withDirectors(director)
.withLinksCreditor("CR123")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const verificationDetail = await client.verificationDetails.create({
name: "Acme",
company_number: "03768189",
address_line1: "12 Drury lane",
city: "London",
description: "wine and cheese seller",
postal_code: "B4 7NJ",
directors: [{
given_name: "Gandalf",
family_name: "Grey",
city: "London",
date_of_birth: "1986-02-19",
street: "Drury lane",
postal_code: "B4 7NJ",
country_code: "GB"
}],
links: {
creditor: "CR123"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var verificationDetailCreateRequest = new VerificationDetailCreateRequest()
{
Name = "Acme",
CompanyNumber = "03768189",
AddressLine1 = "12 Drury lane",
City = "London",
Description = "wine and cheese seller",
PostalCode = "B4 7NJ",
Directors = new VerificationDetailCreateRequest.VerificationDetailDirectors[]
{
new VerificationDetailCreateRequest.VerificationDetailDirectors
{
GivenName = "Gandalf",
FamilyName = "Grey",
City = "London",
DateOfBirth = "1986-02-19",
Street = "Drury lane",
PostalCode = "B4 7NJ",
CountryCode = "GB"
}
},
Links = new VerificationDetailCreateRequest.VerificationDetailLinks()
{
Creditor = "CR123"
}
};
var verificationDetailResponse = await client.VerificationDetails.CreateAsync(verificationDetailCreateRequest);
var verificationDetail = verificationDetailResponse.VerificationDetail;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
context := context.Background()
verificationDetailCreateParams := gocardless.VerificationDetailCreateParams{
Name: "Acme",
CompanyNumber: "03768189",
AddressLine1: "12 Drury lane",
City: "London",
Description: "wine and cheese seller",
PostalCode: "B4 7NJ",
Directors: []gocardless.VerificationDetailCreateParamsDirectors{
{
GivenName: "Gandalf",
FamilyName: "Grey",
City: "London",
DateOfBirth: "1986-02-19",
Street: "Drury Lane",
PostalCode: "B4 7NJ",
CountryCode: "GB",
},
},
Links: gocardless.VerificationDetailCreateParamsLinks{
Creditor: "CR123",
},
}
verificationDetail, err := client.VerificationDetails.Create(context, verificationDetailCreateParams)
if err != nil {
fmt.Printf("error creating verification detail: %s", err.Error())
return
}
}
List verification details
Returns a list of verification details belonging to a creditor.
Relative endpoint: GET /verification_details
Parameters
creditor
- required Unique identifier, beginning with “CR”.
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
limit
- Number of records to return.
GET https://api.gocardless.com/verification_details?creditor=CR123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"verification_details": [{
"name": "Acme Limited",
"company_number": "03768189",
"description": "wine and cheese seller",
"address_line1": "12 Drury lane",
"address_line2": null,
"address_line3": null,
"city": "London",
"region": null,
"postal_code": "B4 7NJ",
"country_code": "GB",
"directors": [{
"given_name": "Gandalf",
"family_name": "Grey",
"date_of_birth": "1986-02-19",
"street": "Drury lane",
"city":"London",
"postal_code":"B4 7NJ",
"country_code":"GB",
}],
}],
"links": {
"creditor": "CR123"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$response = $client->verificationDetails()->list([
'params' => [
'creditor' => 'CR123'
]
])->records;
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.verification_details.list(params={
"creditor": "CR123"
}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.verification_details.list(params: {
creditor: "CR123",
}).records
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (VerificationDetail verificationDetail: client.verificationDetails().all().withCreditor("CR123").execute()){
System.out.println(verificationDetail.getDescription());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const verificationDetailList = await client.verificationDetails.list({ creditor: "CR123" });
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var verificationDetailListRequest = new VerificationDetailListRequest()
{
Creditor = "CR123"
};
var verificationDetailListResponse = client.VerificationDetails.All(verificationDetailListRequest);
foreach (var verificationDetail in verificationDetailListResponse)
{
Console.WriteLine(verificationDetail.Description);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
context := context.Background()
verificationDetailListParams := gocardless.VerificationDetailListParams{
Creditor: "CR123",
}
verificationDetailList, err := client.VerificationDetails.List(context, verificationDetailListParams)
if err != nil {
fmt.Printf("error listing verification details: %+v", err)
return
}
for _, verificationDetail := range verificationDetailList.VerificationDetails {
fmt.Println(verificationDetail.Name)
fmt.Println(verificationDetail.Description)
}
}
Webhooks
Basic description of a webhook
Properties
id
- Unique identifier, beginning with “WB”.
created_
at - Fixed timestamp, recording when this resource was created.
is_
test - Boolean value showing whether this was a demo webhook for testing
request_
body - The body of the request sent to the webhook URL
request_
headers - The request headers sent with the webhook
response_
body - The body of the response from the webhook URL
response_
body_ truncated - Boolean value indicating the webhook response body was truncated
response_
code - The response code from the webhook request
response_
headers - The headers sent with the response from the webhook URL
response_
headers_ content_ truncated - Boolean indicating the content of response headers was truncated
response_
headers_ count_ truncated - Boolean indicating the number of response headers was truncated
successful
- Boolean indicating whether the request was successful or failed
url
- URL the webhook was POST-ed to
List webhooks
Returns a cursor-paginated list of your webhooks.
Relative endpoint: GET /webhooks
Parameters
after
- Cursor pointing to the start of the desired set.
before
- Cursor pointing to the end of the desired set.
created_
at [gt] - Limit to records created after the specified date-time.
created_
at [gte] - Limit to records created on or after the specified date-time.
created_
at [lt] - Limit to records created before the specified date-time.
created_
at [lte] - Limit to records created on or before the specified date-time.
is_
test - Show only test/non test webhooks
limit
- Number of records to return.
successful
- Show only successful/failed webhooks
GET https://api.gocardless.com/webhooks/WB123?successful=true HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"cursors": {
"after": null,
"before": null
},
"limit": 5
},
"webhooks": [{
"created_at": "2018-03-12T15:13:37.416Z",
"id": "WB123",
"is_test": true,
"request_body": "{\"events\":[{\"id\":\"EV123\",\"created_at\":\"2018-03-12T15:13:37.158Z\",\"resource_type\":\"payments\",\"action\":\"created\",\"links\":{\"payment\":\"PM123\"},\"details\":{\"origin\":\"api\",\"cause\":\"payment_created\",\"description\":\"Payment created via the API.\"},\"metadata\":{}}]}",
"request_headers": {
"Content-Type": "application/json",
"Origin": "https://api.gocardless.com",
"User-Agent": "gocardless-webhook-service/1.1",
"Webhook-Signature": "e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365"
},
"response_body": "ok",
"response_body_truncated": false,
"response_code": 200,
"response_headers": {
"content-type": "text/html; charset=utf-8",
"date": "Mon, 12 Mar 2018 15:13:37 GMT",
},
"response_headers_content_truncated": false,
"response_headers_count_truncated": false,
"successful": true,
"url": "https://example.com/webhook_handler"
}]
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->webhooks()->list();
$client->webhooks()->list([
"params" => ["successful" => True]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.webhooks.list().records
client.webhooks.list(params={"successful": True}).records
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.webhooks.list
@client.webhooks.list(params: { successful: true })
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
for (Webhook webhook : client.webhooks().all().withSuccessful(true).execute()) {
System.out.println(webhook.getId());
}
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const webhooks = await client.webhooks.list();
// List all webhooks past a certain date.
const webhooks = await client.webhooks.list({
created_at: {
gt: "2020-01-01T17:01:06.000Z"
}
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var webhookRequest = new GoCardless.Services.WebhookListRequest()
{
Successful = true
};
var webhookListResponse = gocardless.Webhooks.All(webhookRequest);
foreach (GoCardless.Resources.Webhook webhook in webhookListResponse)
{
Console.WriteLine(webhook.Id);
}
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
webhookListParams := gocardless.WebhookListParams{
CreatedAt: &gocardless.WebhookListParamsCreatedAt{
Gt: "2020-01-01T17:01:06.000Z",
},
}
webhookListResult, err := client.Webhooks.List(context, webhookListParams)
for _, webhook := range webhookListResult.Webhooks {
fmt.Println(webhook.Id)
}
}
Get a single webhook
Retrieves the details of an existing webhook.
Relative endpoint: GET /webhooks/WB123
GET https://api.gocardless.com/webhooks/WB123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"webhooks": {
"created_at": "2018-03-12T15:13:37.416Z",
"id": "WB123",
"is_test": true,
"request_body": "{\"events\":[{\"id\":\"EV123\",\"created_at\":\"2018-03-12T15:13:37.158Z\",\"resource_type\":\"payments\",\"action\":\"created\",\"links\":{\"payment\":\"PM123\"},\"details\":{\"origin\":\"api\",\"cause\":\"payment_created\",\"description\":\"Payment created via the API.\"},\"metadata\":{}}]}",
"request_headers": {
"Content-Type": "application/json",
"Origin": "https://api.gocardless.com",
"User-Agent": "gocardless-webhook-service/1.1",
"Webhook-Signature": "e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365"
},
"response_body": "ok",
"response_body_truncated": false,
"response_code": 200,
"response_headers": {
"content-type": "text/html; charset=utf-8",
"date": "Mon, 12 Mar 2018 15:13:37 GMT",
},
"response_headers_content_truncated": false,
"response_headers_count_truncated": false,
"successful": true,
"url": "https://example.com/webhook_handler"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->webhooks()->get("WB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.webhooks.get("WB123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.webhooks.get("WB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
Webhook webhook = client.webhooks().get("WB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const webhook = await client.webhooks.find("WB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var webhookResponse = await gocardless.webhooks.GetAsync("WB123");
GoCardless.Resources.Webhook webhook = webhooksResponse.Webhook;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
webhook, err := client.Webhooks.Get(context, "WB123")
}
Retry a webhook
Requests for a previous webhook to be sent again
Relative endpoint: POST /webhooks/WB123/actions/retry
POST https://api.gocardless.com/webhooks/WB123/actions/retry HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"webhooks": {
"created_at": "2018-03-12T15:13:37.416Z",
"id": "WB123",
"is_test": true,
"request_body": "{\"events\":[{\"id\":\"EV123\",\"created_at\":\"2018-03-12T15:13:37.158Z\",\"resource_type\":\"payments\",\"action\":\"created\",\"links\":{\"payment\":\"PM123\"},\"details\":{\"origin\":\"api\",\"cause\":\"payment_created\",\"description\":\"Payment created via the API.\"},\"metadata\":{}}]}",
"request_headers": {
"Content-Type": "application/json",
"Origin": "https://api.gocardless.com",
"User-Agent": "gocardless-webhook-service/1.1",
"Webhook-Signature": "e4d043149b4cc27435d05ea275a09de2f810e45bed5448fd6a0a742a3846b365"
},
"response_body": "ok",
"response_body_truncated": false,
"response_code": 200,
"response_headers": {
"content-type": "text/html; charset=utf-8",
"date": "Mon, 12 Mar 2018 15:13:37 GMT",
},
"response_headers_content_truncated": false,
"response_headers_count_truncated": false,
"successful": true,
"url": "https://example.com/webhook_handler"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->webhooks()->retry("WB123");
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.webhooks.retry("WB123")
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.webhooks.retry("WB123")
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
client.webhooks().retry("WB123").execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const webhookResponse = await client.webhooks.retry("WB123");
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var webhookResponse = await gocardless.webhooks.RetryAsync("WB123");
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
webhook, err := client.Webhooks.Retry(context, "WB123")
}
Event Actions
All events are associated with a resource
. This section goes through each resource
in turn, and
lists all the possible actions
that can relate to that resource. Some actions have different
variations - these are listed in the relevant tables below each action.
Billing Request
This is a list of all the different values for action
created
This billing request has been created.
Origin | Cause | Description |
---|---|---|
gocardless | billing_ |
This billing request has been created. |
api | billing_ |
This billing request has been created. |
payer | billing_ |
This billing request has been created. |
flow_created
A billing request flow has been created against this billing request.
Origin | Cause | Description |
---|---|---|
gocardless | billing_ |
A billing request flow has been created against this billing request. |
api | billing_ |
A billing request flow has been created against this billing request. |
payer | billing_ |
A billing request flow has been created against this billing request. |
flow_visited
The billing request flow has been visited.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
The billing request flow has been visited. |
flow_exited
The billing request flow has been exited by the payer.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
The billing request flow has been exited by the payer. |
collect_customer_details
Customer details have been collected for this billing request.
Origin | Cause | Description |
---|---|---|
api | billing_ |
Customer details have been collected for this billing request. |
payer | billing_ |
Customer details have been collected for this billing request. |
select_institution
Institution details have been collected for this billing request.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
Institution details have been collected for this billing request. |
collect_bank_account
Bank account details have been collected for this billing request.
Origin | Cause | Description |
---|---|---|
api | billing_ |
Bank account details have been collected for this billing request. |
payer | billing_ |
Bank account details have been collected for this billing request. |
payer_details_confirmed
Payer has confirmed all their details for this billing request.
Origin | Cause | Description |
---|---|---|
api | billing_ |
Payer has confirmed all their details for this billing request. |
payer | billing_ |
Payer has confirmed all their details for this billing request. |
bank_authorisation_visited
A bank authorisation link for this billing request has been visited.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
A bank authorisation link for this billing request has been visited. |
bank_authorisation_authorised
A bank authorisation for this billing request has been authorised by the payer.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
A bank authorisation for this billing request has been authorised by the payer. |
gocardless | billing_ |
A bank authorisation for this billing request has been authorised by the payer. |
bank_authorisation_denied
A bank authorisation for this billing request has been denied by the payer.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
A bank authorisation for this billing request has been denied by the payer. |
gocardless | billing_ |
A bank authorisation for this billing request has been denied by the payer. |
bank_authorisation_expired
A bank authorisation for this billing request has expired.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
A bank authorisation for this billing request has expired. |
bank_authorisation_failed
A bank authorisation for this billing request has failed because of a bank account mismatch.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
A bank authorisation for this billing request has failed because of a bank account mismatch. |
gocardless | billing_ |
A bank authorisation for this billing request has failed because of a bank account mismatch. |
fulfilled
This billing request has been fulfilled, and the resources have been created.
Origin | Cause | Description |
---|---|---|
gocardless | billing_ |
This billing request has been fulfilled, and the resources have been created. |
api | billing_ |
This billing request has been fulfilled, and the resources have been created. |
cancelled
This billing request has been cancelled, none of the resources have been created.
Origin | Cause | Description |
---|---|---|
gocardless | billing_ |
This billing request has been cancelled, none of the resources have been created. |
api | billing_ |
This billing request has been cancelled, none of the resources have been created. |
choose_currency
Currency details have been collected for this billing request.
Origin | Cause | Description |
---|---|---|
api | billing_ |
Currency details have been collected for this billing request. |
payer | billing_ |
Currency details have been collected for this billing request. |
collect_amount
Amount has been collected for this billing request.
Origin | Cause | Description |
---|---|---|
payer | billing_ |
Amount has been collected for this billing request. |
payer_geo_blocked
Payer blocked for 24 hours for attempting to pay from an unsupported location.
Origin | Cause | Description |
---|---|---|
payer | payer_ |
Payer blocked for 24 hours for attempting to pay from an unsupported location. |
failed
This billing request has failed.
Origin | Cause | Description |
---|---|---|
gocardless | billing_ |
This billing request has failed. |
api | billing_ |
This billing request has failed. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2021-04-08T17:01:06.000Z",
"resource_type": "billing_requests",
"action": "created",
"details": {
"origin": "api",
"cause": "billing_request_created",
"description": "This billing request has been created."
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"billing_request": "BRQ123"
}
}
}
Creditor
This is a list of all the different values for action
updated
Something has changed about this creditor. The property that has changed will be included in the event details. Currently, this webhook is sent for logo_url
, verification_status
, mandate_imports_enabled
, custom_payment_pages_enabled
and merchant_responsible_for_notifications
.
Origin | Cause | Description |
---|---|---|
gocardless | creditor_ |
This creditor has been updated. |
new_payout_currency_added
This creditor has added a new payout currency.
Origin | Cause | Description |
---|---|---|
gocardless | new_ |
This creditor has added a new payout currency. |
account_auto_frozen
This creditor account has been automatically frozen and had restrictions applied.
Origin | Cause | Description |
---|---|---|
gocardless | account_ |
This creditor account has been automatically frozen and had restrictions applied. |
account_auto_frozen_reverted
This creditor accounts restrictions have been removed.
Origin | Cause | Description |
---|---|---|
gocardless | account_ |
The restrictions on this creditor account have been removed. |
bounced_payout
A payout for this creditor has failed. Please contact your bank for more information or retry the payout.
Origin | Cause | Description |
---|---|---|
gocardless | bounced_ |
A payout for this creditor has failed. Please retry the payout or contact your bank for more information. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2018-04-08T17:01:06.000Z",
"resource_type": "creditors",
"action": "updated",
"links": {
"creditor": "CR123"
},
"details": {
"origin": "gocardless",
"cause": "creditor_updated",
"description": "This creditor has been updated.",
"property": "fx_payout_currency"
},
"metadata": {}
}
}
Export
This is a list of all the different values for action
started
Export started
Origin | Cause | Description |
---|---|---|
gocardless | export_ |
Export started |
completed
Export completed
Origin | Cause | Description |
---|---|---|
gocardless | export_ |
Export completed |
failed
Export failed
Origin | Cause | Description |
---|---|---|
gocardless | export_ |
Export failed |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2024-07-10T00:00:00.000Z",
"resource_type": "exports",
"action": "started",
"links": {
"export": "EX0000116MFWYM",
},
"details": {
"origin": "gocardless",
"cause": "export_started",
"description": "Export started.",
"type": "payout_transactions_reconciliation",
"currency": "GBP"
},
"metadata": {}
}
}
Instalment Schedule
This is a list of all the different values for action
created
The instalment schedule has been created.
Origin | Cause | Description |
---|---|---|
api | instalment_ |
Instalment schedule has been created via the API |
creation_failed
The instalment schedule failed to create due to validation errors when creating the payments. The errors will be included in the event payload.
Origin | Cause | Description |
---|---|---|
api | instalment_ |
Instalment schedule failed to be created |
cancelled
The instalment schedule has been cancelled. Any pending payments have also been cancelled.
Origin | Cause | Description |
---|---|---|
api | instalment_ |
Instalment schedule has been cancelled |
gocardless | mandate_ |
Instalment schedule has been cancelled |
gocardless | mandate_ |
Instalment schedule has been cancelled |
gocardless | mandate_ |
Instalment schedule has been cancelled |
gocardless | mandate_ |
Instalment schedule has been cancelled |
errored
One or more instalments in this instalment schedule failed to collect successfully.
Origin | Cause | Description |
---|---|---|
gocardless | instalment_ |
Instalment schedule has errored |
gocardless | instalment_ |
One or more payments in the instalment schedule has had a late failure |
resumed
The instalment schedule has been rectified by remedying any failed payments.
Origin | Cause | Description |
---|---|---|
gocardless | instalment_ |
Instalment schedule has resumed |
completed
This instalment schedule has concluded. No further instalments will be collected.
Origin | Cause | Description |
---|---|---|
gocardless | instalment_ |
Instalment schedule has completed |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "instalment_schedules",
"action": "payment_created",
"links": {
"instalment_schedule": "IS123",
"payment": "PM123"
},
"details": {
"origin": "api",
"cause": "payment_created",
"description": "Payment created by an instalment schedule."
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
}
}
}
Mandate
This is a list of all the different values for action
created
The mandate has been created.
Origin | Cause | Description |
---|---|---|
api | mandate_ |
Mandate created via the API. |
gocardless | mandate_ |
Mandate created by a bulk change |
customer_approval_granted
The mandate required additional approval from the customer (e.g. permission from a second signatory), and that approval has been granted.
Origin | Cause | Description |
---|---|---|
customer | customer_ |
The customer has granted approval for this mandate |
customer_approval_skipped
The mandate originally was believed to require additional approval from the customer (e.g. permission from a second signatory), but approval has been skipped (for example because the mandate was erroneously marked as needing a second signature).
Origin | Cause | Description |
---|---|---|
customer | customer_ |
The customer has skipped approval for this mandate |
active
The mandate has been successfully set up by the customer’s bank.
Origin | Cause | Description |
---|---|---|
gocardless | mandate_ |
The time window after submission for the banks to refuse a mandate has ended without any errors being received, so this mandate is now active. |
bank | mandate_ |
The customer’s bank has confirmed that this mandate has been activated. |
cancelled
The mandate has been cancelled, either by the customer through their bank or this API, or automatically when their bank account is closed.
Origin | Cause | Scheme | Reason code | Description |
---|---|---|---|---|
bank | bank_ |
ach | ACH_ |
This bank account has been closed as the customer is deceased. |
bank | bank_ |
ach | ACH_ |
The bank account for this mandate has been closed. |
bank | mandate_ |
ach | ACH_ |
The mandate was cancelled at a bank branch. |
bank | authorisation_ |
ach | ACH_ |
The customer disputes having authorised you to set up a mandate with them. |
bank | invalid_ |
ach | ACH_ |
The specified bank account does not exist or was closed. |
bank | direct_ |
ach | ACH_ |
The bank account does not support Direct Debit. |
bank | refer_ |
ach | ACH_ |
This mandate has been cancelled because a payment under it failed. |
bank | return_ |
ach | ACH_ |
mandate_ |
api | mandate_ |
- | - | The mandate was cancelled at your request. |
api | bank_ |
- | - | The customer’s account was disabled at your request. |
bank | mandate_ |
bacs | ADDACS-0ADDACS-1 | The mandate was cancelled at a bank branch. |
bank | bank_ |
bacs | ADDACS-2 | This bank account has been closed as the customer is deceased. |
bank | bank_ |
bacs | ADDACS-3ADDACS-CADDACS-E | The customer’s bank account was transferred to a different bank or building society. |
bank | bank_ |
bacs | ADDACS-B | The customer’s account was closed at their bank. |
bank | authorisation_ |
bacs | ADDACS-D | The customer has disputed the amount of notice specified on the mandate via their bank. |
bank | mandate_ |
bacs | ARUDD-1 | The mandate was cancelled at a bank branch. |
bank | bank_ |
bacs | ARUDD-2 | This mandate has been cancelled, because a payment against it indicated that the customer is deceased. |
bank | bank_ |
bacs | ARUDD-B | The bank account for this mandate has been closed. |
bank | refer_ |
bacs | ARUDD-6 | This mandate has been cancelled because a payment under it failed. |
bank | authorisation_ |
bacs | DDICA-4 | The customer claims that they asked you to cancel their mandate before you took the payment. |
bank | authorisation_ |
bacs | DDICA-5DDICA-6DDICA-8 | The customer disputes having authorised you to set up a mandate with them. |
bank | invalid_ |
sepa_ |
AC01BE06 | The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
bank | bank_ |
sepa_ |
AC04 | The bank account for this mandate has been closed. Any subscriptions and pending payment will also be cancelled. |
bank | direct_ |
sepa_ |
AG01AC06 | The bank account for this mandate does not support SEPA direct debit. Any subscriptions and pending payments will also be cancelled. |
bank | account_ |
sepa_ |
AC06 | The bank account for this mandate was blocked. Any subscriptions and pending payments will also be cancelled. |
bank | mandate_ |
sepa_ |
MD01 | A payment under this mandate failed, indicating that the mandate has been cancelled at the customer’s bank. Any subscriptions and pending payments will also be cancelled. |
bank | bank_ |
sepa_ |
MD07 | This mandate has been cancelled because the customer is deceased. |
bank | mandate_ |
betalingsservice | MANDATE_ |
This mandate was cancelled by the customer or their bank. |
bank | mandate_ |
betalingsservice | INFORMATION_ |
This mandate was cancelled by the customer or their bank. |
bank | direct_ |
becs | 2 | The bank account does not support Direct Debit. |
bank | payment_ |
becs | 2 | The payment was stopped by the payer or their bank. |
bank | other | becs | 2 | This mandate has been cancelled because a payment under it failed. |
bank | bank_ |
becs | 3 | The bank account for this mandate has been closed. |
bank | bank_ |
becs | 4 | This bank account has been closed as the customer is deceased. |
bank | authorisation_ |
becs | UDUNAUT | The customer disputes having authorised you to set up a mandate with them. |
bank | mandate_ |
becs | CBC | This mandate was cancelled by the customer or their bank. |
bank | invalid_ |
becs | RC02 | The bank account specified does not exist. |
bank | authorisation_ |
becs | MD01 | The customer disputes having authorised you to set up a mandate with them. |
bank | bank_ |
becs | AC04 | The customer’s account was closed at their bank. |
bank | bank_ |
becs | MD07 | This bank account has been closed as the customer is deceased. |
bank | invalid_ |
becs | AC01 | The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
bank | refer_ |
becs | NARR | There was an internal error processing this mandate. |
bank | mandate_ |
pay_ |
MD16MS02 | This mandate was cancelled by the customer or their bank. |
bank | mandate_ |
pay_ |
MD17 | The mandate was cancelled at your request. |
bank | mandate_ |
pay_ |
MD21 | The mandate has been cancelled due to fraud. |
bank | mandate_ |
pay_ |
MSUCMCFCMCOC | The mandate has been suspended. |
bank | refer_ |
pay_ |
UNKN | This mandate was cancelled by the customer or their bank. |
bank | invalid_ |
pay_ |
AC02 | This mandate was cancelled due to a Notification of Change indicating the customer’s account number or branch number was incorrect, please contact the customer. |
bank | other | pay_ |
AC06 | The account associated with the customer’s mandate is blocked. |
bank | invalid_ |
pay_ |
AC13 | This mandate was cancelled due to a Notification of Change indicating the customer’s selected account type was incorrect, please contact the customer. |
bank | bank_ |
pay_ |
AC04AC05 | The customer’s account was closed at their bank. |
bank | bank_ |
pay_ |
MD07 | This mandate has been cancelled because the customer is deceased. |
bank | other | pay_ |
SL11SL12 | The customer’s account is not permitted to send funds to the beneficiary. |
bank | bank_ |
becs_ |
DISHONOUR-AC04 | The customer’s account was closed at their bank. |
bank | invalid_ |
becs_ |
DISHONOUR-AC05NEGATIVE_ |
The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
bank | bank_ |
pad | PAYMENT_ |
The customer’s account was closed at their bank. |
bank | bank_ |
pad | PAYMENT_ |
This bank account has been closed as the customer is deceased. |
bank | authorisation_ |
pad | PAYMENT_ |
The customer disputes having authorised you to set up a mandate with them. |
bank | mandate_ |
pad | PAYMENT_ |
This mandate was cancelled by the customer or their bank. |
bank | invalid_ |
pad | PAYMENT_ |
The specified bank account does not exist or was closed. |
bank | mandate_ |
faster_ |
PAYER_ |
This mandate was cancelled by the customer or their bank. |
gocardless | mandate_ |
faster_ |
MERCHANT_ |
The mandate was cancelled at your request. |
gocardless | initial_ |
- | - | This mandate has been cancelled because the initial faster payment failed |
failed
The mandate could not be set up, generally because the specified bank account does not accept Direct Debit payments or is closed.
Origin | Cause | Scheme | Reason code | Description |
---|---|---|---|---|
bank | bank_ |
ach | ACH_ |
This bank account has been closed as the customer is deceased. |
bank | refer_ |
ach | ACH_ |
This mandate was cancelled due to a Notification of Change indicating the customer’s account number or branch number was incorrect, please contact the customer. |
bank | refer_ |
ach | ACH_ |
This mandate was cancelled due to a Notification of Change indicating the customer’s selected account type was incorrect, please contact the customer. |
bank | bank_ |
ach | ACH_ |
The bank account for this mandate has been closed. |
bank | mandate_ |
ach | ACH_ |
The mandate was already cancelled. |
bank | authorisation_ |
ach | ACH_ |
The mandate was already cancelled. |
bank | invalid_ |
ach | ACH_ |
The specified bank account does not exist or was closed. |
bank | direct_ |
ach | ACH_ |
The bank account does not support Direct Debit. |
bank | refer_ |
ach | ACH_ |
This mandate has been cancelled because a payment under it failed. |
bank | other | ach | ACH_ |
This mandate has been cancelled because a payment under it failed. |
bank | return_ |
ach | ACH_ |
The mandate has been cancelled because a payment under it was charged back. |
bank | authorisation_ |
ach | ACH_ |
The customer disputes having authorised you to set up a mandate with them. |
bank | invalid_ |
bacs | ARUDD-5ARUDD-YARUDD-E | The specified bank account does not exist or was closed. |
bank | refer_ |
bacs | ARUDD-6 | This mandate has been cancelled because a payment under it failed. |
bank | bank_ |
bacs | AUDDIS-2 | The bank account for this mandate has been closed as the customer is deceased. |
bank | invalid_ |
bacs | AUDDIS-5 | The specified bank account does not exist or was closed. |
bank | bank_ |
bacs | AUDDIS-B | The customer’s account was closed at their bank. |
bank | direct_ |
bacs | AUDDIS-FAUDDIS-GAUDDIS-N | The bank account does not support Direct Debit. |
bank | bank_ |
bacs | AUDDIS-3AUDDIS-C | The customer’s bank account was transferred to a different bank or building society. |
bank | invalid_ |
becs | 15 | The bank account specified does not exist. |
bank | direct_ |
becs | 2 | The bank account does not support Direct Debit. |
bank | payment_ |
becs | 2 | The payment was stopped by the payer or their bank. |
bank | invalid_ |
becs | DEN | The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
bank | other | becs | 789 | There was an internal error processing this mandate. |
bank | invalid_ |
becs | RC02 | The bank account specified does not exist. |
bank | authorisation_ |
becs | MD01 | The customer disputes having authorised you to set up a mandate with them. |
bank | bank_ |
becs | AC04 | The customer’s account was closed at their bank. |
bank | bank_ |
becs | MD07 | This bank account has been closed as the customer is deceased. |
bank | invalid_ |
becs | AC01 | The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
bank | refer_ |
becs | NARR | There was an internal error processing this mandate. |
bank | mandate_ |
pay_ |
MD20 | The mandate has expired. |
bank | refer_ |
pay_ |
NARRUNKN | There was an internal error processing this mandate. |
bank | invalid_ |
becs_ |
DISHONOUR-AC05NEGATIVE_ |
The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
bank | bank_ |
becs_ |
DISHONOUR-AC04 | The customer’s account was closed at their bank. |
bank | invalid_ |
becs_ |
DISHONOUR-AC03 | The customer’s bank account was transferred to a different bank or building society. |
bank | mandate_ |
becs_ |
DISHONOUR-AG01 | This mandate was cancelled by the customer or their bank. |
bank | other | becs_ |
DISHONOUR-BE05 | The customer disputes having authorised you to set up a mandate with them. |
bank | refer_ |
becs_ |
DISHONOUR-AM04DISHONOUR-MS01 | This mandate has been cancelled because a payment under it failed. |
bank | invalid_ |
pad | PAYMENT_ |
The specified bank account does not exist or was closed. |
bank | bank_ |
pad | PAYMENT_ |
The customer’s account was closed at their bank. |
bank | bank_ |
pad | PAYMENT_ |
This bank account has been closed as the customer is deceased. |
bank | refer_ |
pad | PAYMENT_ |
The account holder name may be different than that associated with the electronic transaction to run. |
bank | invalid_ |
sepa_ |
AC01 | The bank account specified does not exist. Any subscriptions and pending payments will also be cancelled. |
transferred
The mandate has been transferred to a different bank account either using a bank switching service (where it is supported) or with help from GoCardless Support when a customer asks to change their bank account (we can make the switch after verifying the details). The event will include links[previous_customer_bank_account]
and links[new_customer_bank_account]
. When using a bank switching service, the mandate may have been submitted again, depending on how the involved banks handled the transfer.
Origin | Cause | Description |
---|---|---|
bank | bank_ |
The customer’s bank account was transferred to a different bank or building society. |
api | mandate_ |
This mandate was transferred to a new bank account through GoCardless. |
expired
No collection attempts were made against the mandate within the dormancy period of your service user number. As a result it has expired, and no further collections can be taken against it. If you wish to continue taking payments from this customer you should request their permission and use the reinstate endpoint.
Origin | Cause | Description |
---|---|---|
gocardless | mandate_ |
The mandate is being marked as expired, because no payments have been collected against it for the dormancy period of your service user number. If you have access to the mandate reinstation API endpoint, you can use this to attempt to set this mandate up again. |
bank | mandate_ |
This mandate was cancelled by the customer or their bank. |
gocardless | mandate_ |
The mandate has expired. |
submitted
The mandate has been submitted to the banks, and should become active in a few days, unless the bank declines the request.
Origin | Cause | Description |
---|---|---|
gocardless | mandate_ |
The mandate has been submitted to the banks. |
bank | bank_ |
The customer’s bank account was transferred to a different bank or building society. |
resubmission_requested
A request to resubmit the mandate was made by the mandate reinstate endpoint.
Origin | Cause | Description |
---|---|---|
api | resubmission_ |
An attempt to reinstate this mandate was requested. |
bank | bank_ |
The customer’s bank account was transferred to a different bank or building society. |
reinstated
The mandate has become active again, after it was cancelled or expired. This can be due to the customer’s bank wishing to undo a cancellation or expiry notice they sent, or because the mandate was successfully reinstated via the reinstate endpoint.
Origin | Cause | Description |
---|---|---|
gocardless | mandate_ |
The time window after submission for the banks to refuse a mandate has ended without any errors being received, so this mandate is now active. |
bank | mandate_ |
A cancelled mandate has been re-instated by the customer’s bank. |
replaced
The mandate has been cancelled and replaced by a new mandate (for example, because the creditor has moved to a new Service User Number). The event will include links[new_mandate]
with the ID of the new mandate.
Origin | Cause | Description |
---|---|---|
gocardless | scheme_ |
The creditor has changed to a different scheme identifier, so this mandate has been cancelled and replaced by a new one. |
consumed
The mandate has been used to create a payment, and has now been consumed. It cannot be used again.
Origin | Cause | Description |
---|---|---|
gocardless | mandate_ |
The mandate has been used to create a payment, and has now been consumed. It cannot be used again. |
blocked
The mandate has been blocked because the customer’s details matched against an entry in either our global blocklist or the blocklist populated by you. This mandate cannot be unblocked and no payments can be created against it. If you still wish to collect payments from this customer, you will need to remove their details from any blocks you have created and ask them to set up a new mandate. If you contacted GoCardless to block the customer’s details, you will need to make a request to unblock them.
Origin | Cause | Description |
---|---|---|
gocardless | mandate_ |
The mandate has been blocked because the customer’s details matched against an entry in the blocklist populated by you. |
gocardless | mandate_ |
The mandate has been blocked because the customer’s details matched against an entry in our global blocklist. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "mandates",
"action": "cancelled",
"details": {
"origin": "bank",
"cause": "bank_account_closed",
"description": "The bank account for this mandate has been closed.",
"scheme": "bacs",
"reason_code": "ADDACS-B"
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"mandate": "MD123"
}
}
}
GET https://api.gocardless.com/events/EV456 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV456",
"created_at": "2014-04-08T17:03:12.000Z",
"resource_type": "mandates",
"action": "cancelled",
"details": {
"origin": "api",
"cause": "mandate_cancelled",
"description": "The mandate was cancelled via an API call."
},
"metadata": {
"cancellor_id": "some_id"
},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"mandate": "MD456"
}
}
}
GET https://api.gocardless.com/events/EV789 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV789",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "mandates",
"action": "transferred",
"details": {
"origin": "bank",
"cause": "bank_account_transferred",
"description": "The customer's bank account was transferred to a different bank or building society.",
"scheme": "bacs",
"reason_code": "AUDDIS-C"
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"mandate": "MD789",
"previous_customer_bank_account": "BA123",
"new_customer_bank_account": "BA456"
}
}
}
Payer Authorisation
This is a list of all the different values for action
completed
PayerAuthorisation is completed. Customer, CustomerBankAccount and Mandate have been created.
Origin | Cause | Description |
---|---|---|
gocardless | payer_ |
PayerAuthorisation is completed. Customer, CustomerBankAccount and Mandate have been created. |
failed
PayerAuthorisation is failed. Customer, CustomerBankAccount and Mandate creation have been failed.
Origin | Cause | Description |
---|---|---|
gocardless | customer_ |
PayerAuthorisation has failed. Customer, CustomerBankAccount and Mandate creation have failed. |
gocardless | customer_ |
PayerAuthorisation has failed. Customer, CustomerBankAccount and Mandate creation have failed. |
gocardless | mandate_ |
PayerAuthorisation has failed. Customer, CustomerBankAccount and Mandate creation have failed. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
Payment
This is a list of all the different values for action
created
The payment has been created.
Origin | Cause | Description |
---|---|---|
api | payment_ |
Payment created via the API. |
gocardless | payment_ |
Payment created by a subscription. |
api | instalment_ |
Payment created by an instalment schedule. |
customer_approval_granted
The payment required additional approval from the customer before it could be submitted, and that approval has been granted.
Origin | Cause | Description |
---|---|---|
customer | customer_ |
The customer granted approval for this payment |
customer_approval_denied
The payment required additional approval from the customer before it could be submitted, and that approval has been denied.
Origin | Cause | Description |
---|---|---|
customer | customer_ |
The customer denied approval for this payment |
submitted
The payment has been submitted to the banks. It will be a few days until it is collected, or fails.
Origin | Cause | Description |
---|---|---|
gocardless | payment_ |
Payment submitted to the banks. As a result, it can no longer be cancelled. |
confirmed
The payment has been collected from the customer’s bank account, and is now being held by GoCardless. It can take up to 5 working days for a payment to be collected, and will then be held for a short time before becoming paid_out
.
Origin | Cause | Description |
---|---|---|
gocardless | payment_ |
Enough time has passed since the payment was submitted for the banks to return an error, so this payment is now confirmed. |
chargeback_cancelled
The customer’s bank has cancelled the chargeback request. This is almost always at the request of the customer.
Origin | Cause | Description |
---|---|---|
bank | payment_ |
The chargeback for this payment was reversed |
gocardless | payment_ |
The chargeback for this payment was reversed |
paid_out
The payment has left GoCardless and has been sent to the creditor’s bank account.
Origin | Cause | Description |
---|---|---|
gocardless | payment_ |
The payment has been paid out by GoCardless. |
late_failure_settled
The payment was a late failure which had already been paid out, and has been debited from a payout.
Origin | Cause | Description |
---|---|---|
gocardless | late_ |
This late failed payment has been settled against a payout. |
chargeback_settled
The payment was charged back, having previously been paid out, and has been debited from a payout.
Origin | Cause | Description |
---|---|---|
gocardless | chargeback_ |
This charged back payment has been settled against a payout. |
surcharge_fee_debited
A surcharge fee has been charged for this payment, because it failed or got charged back.
Origin | Cause | Description |
---|---|---|
gocardless | surcharge_ |
A surcharge fee has been charged for a payment. |
failed
The payment could not be collected, usually because the customer did not have sufficient funds available. GoCardless will automatically retry the payment if event’s will_attempt_retry
field is true. See the intelligent retries section below.
Origin | Cause | Scheme | Reason code | Description |
---|---|---|---|---|
bank | refer_ |
ach | ACH_ |
The customer’s account had insufficient funds to make this payment. |
bank | bank_ |
ach | ACH_ |
This payment failed because the customer is deceased. |
bank | invalid_ |
ach | ACH_ |
The account number was invalid. The mandate will also be cancelled or failed. |
bank | invalid_ |
ach | ACH_ |
The bank account specified does not exist. The mandate will also be cancelled. |
bank | bank_ |
ach | ACH_ |
The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | bank_ |
ach | ACH_ |
This payment has been cancelled because the account has been sold to another financial institution. |
bank | refer_ |
ach | ACH_ |
This payment has been cancelled because the payer’s bank account is frozen. ACH authorization will be cancelled. |
bank | refer_ |
ach | ACH_ |
The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | refer_ |
ach | ACH_ |
The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | refer_ |
ach | ACH_ |
The customer refused to accept this payment. |
bank | authorisation_ |
ach | ACH_ |
The customer claims that they asked you to cancel their mandate before you took the payment. |
bank | return_ |
ach | ACH_ |
This payment was charged back by the customer’s bank, because the customer disputed authorising the transaction. |
bank | authorisation_ |
ach | ACH_ |
This payment has been cancelled because the payer disputes authorising its mandate. |
bank | authorisation_ |
ach | ACH_ |
The payment was charged back. Customer advises an authorization to debit exists, but there is an error or defect in the payment such that the entry does not conform to the terms of the authorization. |
bank | authorisation_ |
ach | ACH_ |
This payment was charged back because the customer disputes having authorised you to set up a mandate with them. |
bank | authorisation_ |
ach | ACH_ |
The customer has placed a stop on this payment and the authorisation has been cancelled. Please contact the customer to set up a new authorisation. |
bank | authorisation_ |
ach | ACH_ |
This payment has been cancelled because the customer disputes authorising its mandate. |
bank | authorisation_ |
ach | ACH_ |
The customer disputes having authorised you to set up a mandate with them. |
bank | other | ach | ACH_ |
There was an internal error processing this payment. |
bank | other | ach | ACH_ |
This payment has been cancelled because the customer’s bank does not support the required payment type or transaction format. |
bank | other | ach | ACH_ |
This payment was cancelled because the return entry was not a duplicate of an entry previously returned by the RDFI. |
bank | other | ach | ACH_ |
This payment was cancelled because the financial institution’s participation has been restricted by a regulatory authority. |
bank | test_ |
sepa_ |
TEST | GoCardless has marked this payment as failed in sandbox to enable testing of payment failure webhooks. |
bank | refer_ |
bacs | ARUDD-0 | The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | mandate_ |
bacs | ARUDD-1 | The customer cancelled the mandate at their bank before the payment could be collected. |
bank | bank_ |
bacs | ARUDD-2 | This payment failed because the customer is deceased. |
bank | bank_ |
bacs | ARUDD-3 | Your customer’s mandate was transferred to a new bank account, but this payment was submitted to the old account. You may wish to retry the payment once you have received a transferred webhook for the corresponding mandate. |
bank | authorisation_ |
bacs | ARUDD-4 | The customer has disputed having been notified of this Direct Debit. |
bank | invalid_ |
bacs | ARUDD-5ARUDD-YARUDD-E | The account number was invalid. The mandate will also be cancelled or failed. |
bank | bank_ |
bacs | ARUDD-B | The customer closed their account before the payment could be taken. The mandate will also be cancelled or failed. |
bank | other | bacs | ARUDD-6 | No mandate was setup for this payment. Some smaller banks require additional time to process mandates, and may not have processed this customer’s mandate yet, so you may wish to retry the payment. |
bank | authorisation_ |
bacs | ARUDD-7 | The customer has disputed that the amount taken differs from the amount they were notified of. |
bank | invalid_ |
sepa_ |
AC01BE06 | The bank account specified does not exist. The mandate will also be cancelled. |
bank | bank_ |
sepa_ |
AC04 | The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | direct_ |
sepa_ |
AG01AC06 | The bank account for this payment does not support SEPA Direct Debit. The mandate will also be cancelled. |
bank | account_ |
sepa_ |
AC06 | This payment failed because the payer’s account was blocked. |
bank | insufficient_ |
sepa_ |
AM04 | The customer’s account had insufficient funds to make this payment. |
bank | mandate_ |
sepa_ |
MD01 | The customer cancelled their mandate at their bank. |
bank | bank_ |
sepa_ |
MD07 | This payment failed because the customer is deceased. |
bank | refer_ |
sepa_ |
MS03RR04 | The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | refer_ |
sepa_ |
MS02 | The customer refused to accept this payment. |
bank | refer_ |
sepa_ |
SL01 | The payment failed due to a restriction on Direct Debit payments from the payer’s bank account. |
bank | other | becs | 9 | The customer’s bank refused to accept this payment, please refer to customer. |
bank | other | becs | 278 | There was an internal error processing this payment. |
bank | payment_ |
becs | 2 | The payment was stopped by the payer or their bank. |
bank | direct_ |
becs | 2789 | The payment failed due to a restriction on Direct Debit payments from the payer’s bank account. |
bank | refer_ |
becs | 6 | The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | invalid_ |
becs | 15 | The account number was invalid. The mandate will also be cancelled or failed. |
bank | bank_ |
becs | 34 | The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | invalid_ |
becs | DEN | The account number was invalid. The mandate will also be cancelled or failed. |
gocardless | other | becs | INT_ |
There was an internal error processing this payment. |
bank | invalid_ |
becs | RC02 | The bank account specified does not exist. The mandate will also be cancelled. |
bank | authorisation_ |
becs | MD01 | The customer disputes having authorised you to set up a mandate with them. |
bank | bank_ |
becs | AC04 | The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | bank_ |
becs | MD07 | This payment failed because the customer is deceased. |
bank | invalid_ |
becs | AC01 | The account number was invalid. The mandate will also be cancelled or failed. |
bank | refer_ |
becs | NARR | The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | other | pay_ |
278 | There was an internal error processing this payment. |
bank | invalid_ |
pay_ |
15 | The account number was invalid. The mandate will also be cancelled or failed. |
bank | bank_ |
pay_ |
34 | The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | invalid_ |
pay_ |
RC02 | The bank account specified does not exist. The mandate will also be cancelled. |
bank | refer_ |
betalingsservice | PAYMENT_ |
The customer refused to accept this payment. |
bank | mandate_ |
betalingsservice | PAYMENT_ |
This payment was canceled because the customer cancelled the mandate at their bank. |
bank | refer_ |
betalingsservice | INFORMATION_ |
The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | other | betalingsservice | INFORMATION_ |
This payment was canceled because the customer cancelled the mandate at their bank. |
bank | invalid_ |
becs_ |
DISHONOUR-AC05NEGATIVE_ |
The bank account specified does not exist. The mandate will also be cancelled. |
bank | bank_ |
becs_ |
DISHONOUR-AC04 | The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | mandate_ |
becs_ |
DISHONOUR-AG01 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | invalid_ |
becs_ |
DISHONOUR-AC03NEGATIVE_ |
The bank account specified does not exist. The mandate will also be cancelled. |
bank | refer_ |
becs_ |
DISHONOUR-AM04NEGATIVE_ |
The customer’s account had insufficient funds to make this payment. |
bank | refer_ |
becs_ |
DISHONOUR-MS01 | The customer refused to accept this payment. |
bank | refer_ |
becs_ |
DISHONOUR-AM02 | The payment failed due to a restriction on Direct Debit payments from the payer’s bank account. |
bank | refer_ |
pad | PAYMENT_ |
The customer’s account had insufficient funds to make this payment. |
bank | invalid_ |
pad | PAYMENT_ |
The account number was invalid. The mandate will also be cancelled or failed. |
bank | bank_ |
pad | PAYMENT_ |
The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | refer_ |
pad | PAYMENT_ |
The payment failed due to a restriction on Direct Debit payments from the payer’s bank account. |
bank | bank_ |
pad | PAYMENT_ |
This payment failed because the customer is deceased. |
bank | refer_ |
pad | PAYMENT_ |
The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | other | pad | PAYMENT_ |
The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | other | becs_ |
DISHONOUR-BE05 | The customer disputes having authorised you to set up a mandate with them. |
bank | other | becs_ |
ACKNOWLEDGEMENT-FAILED | The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | other | faster_ |
FAILED | The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | insufficient_ |
faster_ |
FAILED | The customer’s account had insufficient funds to make this payment. |
bank | bank_ |
faster_ |
FAILED | Payment declined by the bank. |
bank | daily_ |
faster_ |
FAILED | Payment exceeds the daily payment limit for this payer, imposed by the bank. |
bank | insufficient_ |
faster_ |
FAILED | Payment denied due to missing approvals from the bank. |
bank | payment_ |
faster_ |
FAILED | The payment failed due to a violation of the associated mandate consent parameters. |
bank | other | sepa_ |
FAILED | The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | insufficient_ |
sepa_ |
FAILED | The customer’s account had insufficient funds to make this payment. |
bank | other | sepa_ |
FAILED | The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | insufficient_ |
sepa_ |
FAILED | The customer’s account had insufficient funds to make this payment. |
bank | other | pay_ |
FAILED | The payment failed but the reason for the failure was not provided, usually for regulatory reasons. |
bank | insufficient_ |
pay_ |
FAILED | The customer’s account had insufficient funds to make this payment. |
charged_back
The customer asked their bank to refund the payment under the Direct Debit Guarantee, and it has been returned to the customer.
Origin | Cause | Scheme | Reason code | Description |
---|---|---|---|---|
bank | authorisation_ |
ach | ACH_ |
This payment was charged back by the customer’s bank, because the customer disputed authorising the transaction. |
bank | refund_ |
ach | ACH_ |
This payment was charged back by the customer’s bank at the customer’s request within the 8 week cool-off period. |
bank | mandate_ |
ach | ACH_ |
This payment was charged back because the mandate was withdrawn. |
bank | authorisation_ |
ach | ACH_ |
The customer disputes having authorised you to set up a mandate with them. |
bank | return_ |
ach | ACH_ |
This payment was charged back by the customer’s bank, because the customer disputed authorising the transaction. |
bank | authorisation_ |
bacs | DDICA-1 | The customer has disputed that the amount taken differs from the amount they were notified of. |
bank | authorisation_ |
bacs | DDICA-2 | The customer has disputed having been notified of this Direct Debit. |
bank | authorisation_ |
bacs | DDICA-4 | The customer claims that they asked you to cancel their mandate before you took the payment. |
bank | authorisation_ |
bacs | DDICA-5DDICA-6DDICA-8 | The customer disputes having authorised you to set up a mandate with them. |
bank | mandate_ |
sepa_ |
MD01 | This payment was charged back by the customer’s bank, because the customer disputed authorising the transaction. |
bank | refund_ |
sepa_ |
MD06 | This payment was charged back by the customer’s bank at the customer’s request within the 8 week cool-off period. |
bank | refund_ |
betalingsservice | PAYMENT_ |
This payment was charged back by the customer’s bank at the customer’s request within the 8 week cool-off period. |
bank | authorisation_ |
becs | UDUNAUT | The customer disputes having authorised you to set up a mandate with them. |
bank | mandate_ |
becs | CBC | The customer cancelled their mandate at their bank. |
bank | other | becs | UCDUOTHR | The payment was charged back. |
bank | authorisation_ |
becs | MD01 | The customer disputes having authorised you to set up a mandate with them. |
bank | authorisation_ |
pad | PAYMENT_ |
The customer disputes having authorised you to set up a mandate with them. |
bank | other | pad | PAYMENT_ |
The customer has disputed that the amount taken differs from the amount they were notified of. |
bank | other | pad | PAYMENT_ |
The customer has disputed having been notified of this Direct Debit. |
bank | mandate_ |
pad | PAYMENT_ |
This payment was charged back because the mandate was withdrawn. |
cancelled
The payment was cancelled.
Origin | Cause | Scheme | Reason code | Description |
---|---|---|---|---|
bank | bank_ |
ach | ACH_ |
This payment was cancelled because the customer is deceased. |
bank | refer_ |
ach | ACH_ |
This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | bank_ |
ach | ACH_ |
This payment has been cancelled because the bank account it was going to be taken from has been closed. |
bank | invalid_ |
ach | ACH_ |
This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | refer_ |
ach | ACH_ |
This payment has been cancelled because the bank account it was going to be taken from does not support Direct Debit. |
bank | authorisation_ |
ach | ACH_ |
This payment has been cancelled because the payer disputes authorising its mandate. |
bank | refer_ |
ach | ACH_ |
This payment has been cancelled because its mandate was cancelled. |
bank | mandate_ |
ach | ACH_ |
This payment has been cancelled because its mandate was cancelled. |
bank | other | ach | ACH_ |
There was an internal error processing this payment. |
gocardless | instalment_ |
- | - | payment_ |
api | payment_ |
- | - | This payment was cancelled at your request. |
api | mandate_ |
- | - | The mandate for this payment was cancelled at your request. |
api | instalment_ |
- | - | payment_ |
api | bank_ |
- | - | The bank account for this payment was disabled at your request. |
bank | mandate_ |
bacs | ADDACS-0ADDACS-1 | The mandate for this payment was cancelled at a bank branch. |
bank | bank_ |
bacs | ADDACS-2ADDACS-B | The mandate for this payment was cancelled as the customer’s bank account has been closed. |
bank | bank_ |
bacs | ADDACS-3ADDACS-C | The mandate for this payment was cancelled as the customer asked their bank to transfer the mandate to a new account, but the bank has failed to send GoCardless the new bank details. |
bank | authorisation_ |
bacs | ADDACS-D | The customer disputes authorising this mandate. |
bank | bank_ |
bacs | ARUDD-2 | This payment was cancelled because the customer is deceased. |
bank | bank_ |
bacs | ARUDD-B | This payment was cancelled because the customer closed their bank account before it could be collected. |
bank | refer_ |
bacs | ARUDD-6 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | invalid_ |
sepa_ |
AC01BE06 | This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | bank_ |
sepa_ |
AC04MD07 | This payment has been cancelled because the bank account it was going to be taken from has been closed. |
bank | direct_ |
sepa_ |
AG01AC06 | This payment has been cancelled because the bank account it was going to be taken from does not support Direct Debit. |
bank | account_ |
sepa_ |
AC06 | This payment failed because the payer’s account was blocked. |
bank | authorisation_ |
sepa_ |
MD01 | This payment has been cancelled because the payer disputes authorising its mandate. |
bank | mandate_ |
sepa_ |
MD01 | This payment has been cancelled because the payer disputes authorising its mandate. |
bank | authorisation_ |
bacs | DDICA-4DDICA-5DDICA-6 | This payment has been cancelled because the customer disputes authorising its mandate. |
bank | bank_ |
bacs | AUDDIS-2AUDDIS-B | This payment has been cancelled because the bank account it was going to be taken from has been closed. |
bank | invalid_ |
bacs | AUDDIS-5 | This payment has been cancelled because the bank details for its mandate are not valid. |
bank | bank_ |
bacs | AUDDIS-3AUDDIS-C | This payment has been cancelled because the customer requested their bank transfer their Direct Debit to a new account but the bank did not send GoCardless the new bank details. |
bank | direct_ |
bacs | AUDDIS-FAUDDIS-GAUDDIS-N | This payment has been cancelled because the bank account for its mandate does not support Direct Debit. |
bank | invalid_ |
bacs | ARUDD-5ARUDD-EARUDD-Y | This payment has been cancelled because the bank details for its mandate are not valid. |
bank | mandate_ |
bacs | ARUDD-1 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | mandate_ |
betalingsservice | PAYMENT_ |
This payment was canceled because the customer cancelled the mandate at their bank. |
bank | mandate_ |
betalingsservice | MANDATE_ |
This payment was canceled because the customer cancelled the mandate at their bank. |
bank | mandate_ |
betalingsservice | INFORMATION_ |
This payment was canceled because the customer cancelled the mandate at their bank. |
bank | invalid_ |
becs_ |
DISHONOUR-AC03 | This payment has been cancelled because the customer requested their bank transfer their Direct Debit to a new account but the bank did not send GoCardless the new bank details. |
bank | refer_ |
becs_ |
DISHONOUR-MS01 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | bank_ |
becs_ |
DISHONOUR-AC04 | The bank account for this payment has been closed. The mandate will also be cancelled. |
bank | invalid_ |
becs_ |
DISHONOUR-AC05NEGATIVE_ |
The bank account specified does not exist. The mandate will also be cancelled. |
bank | mandate_ |
becs_ |
DISHONOUR-AG01 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | other | becs_ |
DISHONOUR-BE05 | The customer disputes having authorised you to set up a mandate with them. |
bank | invalid_ |
pad | PAYMENT_ |
This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | bank_ |
pad | PAYMENT_ |
This payment has been cancelled because the bank account it was going to be taken from has been closed. |
bank | bank_ |
pad | PAYMENT_ |
This payment was cancelled because the customer is deceased. |
bank | other | pad | PAYMENT_ |
This payment has been cancelled because the customer disputes authorising its mandate. |
bank | authorisation_ |
pad | PAYMENT_ |
This payment has been cancelled because the customer disputes authorising its mandate. |
bank | mandate_ |
pad | PAYMENT_ |
This mandate was cancelled by the customer or their bank. |
bank | invalid_ |
becs | 15 | This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | direct_ |
becs | 2 | This payment has been cancelled because the bank account for its mandate does not support Direct Debit. |
bank | payment_ |
becs | 2 | The payment was stopped by the payer or their bank. |
bank | bank_ |
becs | 3 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | bank_ |
becs | 4 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | invalid_ |
becs | DEN | This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | other | becs | 789 | An error was received from the banks while setting up the mandate for this payment. |
bank | authorisation_ |
becs | UDUNAUT | The customer disputes having authorised you to set up a mandate with them. |
bank | mandate_ |
becs | CBC | This payment has been cancelled because its mandate was cancelled. |
bank | invalid_ |
becs | RC02 | This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | authorisation_ |
becs | MD01 | This payment has been cancelled because the customer disputes authorising its mandate. |
bank | bank_ |
becs | AC04 | This payment has been cancelled because the bank account it was going to be taken from has been closed. |
bank | bank_ |
becs | MD07 | This payment was cancelled because the customer is deceased. |
bank | invalid_ |
becs | AC01 | This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | refer_ |
becs | NARR | The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | invalid_ |
pay_ |
15 | This payment has been cancelled because the bank details for its mandate are incorrect. |
bank | bank_ |
pay_ |
3 | This payment was canceled because the customer cancelled the mandate at their bank. |
bank | invalid_ |
pay_ |
DEN | This payment has been cancelled because the bank details for its mandate are incorrect. |
gocardless | mandate_ |
- | - | The mandate expired before the payment could be collected. |
bank | refer_ |
pad | PAYMENT_ |
The customer’s bank wasn’t able to pay the Direct Debit. This is almost always due to insufficient funds, but is occasionally used as a catch-all for other failures. |
bank | mandate_ |
faster_ |
PAYER_ |
This payment was canceled because the customer cancelled the mandate at their bank. |
bank | mandate_ |
pay_ |
SBP | The mandate for this payment was suspended by the payer. |
gocardless | mandate_ |
faster_ |
MERCHANT_ |
The mandate for this payment was cancelled at your request. |
gocardless | mandate_ |
faster_ |
MANDATE_ |
The mandate expired before the payment could be collected. |
bank | return_ |
ach | ACH_ |
The payment was cancelled because of an ODFI return request. |
bank | refer_ |
ach | ACH_ |
This payment has been cancelled because the payer’s bank account is frozen. ACH authorization will be cancelled. |
gocardless | initial_ |
- | - | This mandate has been cancelled because the initial faster payment failed |
resubmission_requested
A request to resubmit the payment was made by the payment retry endpoint. This can also mean that the payment was automatically scheduled for resubmission by GoCardless, if you have opted in for the intelligent retries feature.
Origin | Cause | Description |
---|---|---|
api | payment_ |
An attempt to retry this payment was requested. |
gocardless | payment_ |
The payment was scheduled for resubmission automatically by GoCardless. |
GET https://api.gocardless.com/events/EV1234 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "failed",
"details": {
"origin": "bank",
"cause": "insufficient_funds",
"description": "The customer's account had insufficient funds to make this payment.",
"scheme": "sepa_core",
"reason_code": "AM04",
"will_attempt_retry": false
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"payment": "PM123"
}
}
}
GET https://api.gocardless.com/events/EV4567 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV4567",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "cancelled",
"details": {
"origin": "bank",
"cause": "mandate_cancelled",
"description": "The mandate for this payment was cancelled as the customer's bank account has been closed.",
"scheme": "bacs",
"reason_code": "ADDACS-B"
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"payment": "PM456",
"parent_event": "EV789"
}
}
}
GET https://api.gocardless.com/events/EV8901 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV8901",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "cancelled",
"details": {
"origin": "api",
"cause": "payment_cancelled",
"description": "Payment cancelled."
},
"metadata": {
"cancellor_id": "some_id"
},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"payment": "PM789"
}
}
}
GET https://api.gocardless.com/events/EV2345 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV2345",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "confirmed",
"details": {
"origin": "gocardless",
"cause": "payment_confirmed",
"description": "Payment confirmed"
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"payment": "PM999"
}
}
}
Payout
This is a list of all the different values for action
paid
GoCardless has transferred the payout to the creditor’s bank account. The details[cause]
will always be payout_paid
, and the details[origin]
will be gocardless
.
Origin | Cause | Description |
---|---|---|
gocardless | payout_ |
GoCardless has transferred the payout to the creditor’s bank account. FX payouts will emit this event but will continue to have a pending status until we emit the payout_ |
fx_rate_confirmed
The exchange rate for the payout has been confirmed and will not change.
Origin | Cause | Description |
---|---|---|
gocardless | payout_ |
The exchange rate for the payout has been confirmed and will not change. Only sent for FX payouts. |
tax_exchange_rates_confirmed
The tax exchange rates for all payout items of the payout have been confirmed. This event will only exist if the payout has a tax_currency
and if its tax_currency
is different from its currency
. It will be created once all fees in the payout are invoiced.
Origin | Cause | Description |
---|---|---|
gocardless | payout_ |
The exchange rates for the taxes (such as VAT) that applied to GoCardless fees deducted from the payout have all been confirmed and will not change. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payouts",
"action": "paid",
"details": {
"origin": "gocardless",
"cause": "payout_paid",
"description": "Payout sent"
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"payout": "PO123"
}
}
}
Refund
This is a list of all the different values for action
created
A refund has been created. The details[cause]
will be payment_refunded
, and the details[origin]
will be api
.
Origin | Cause | Description |
---|---|---|
api | payment_ |
The refund has been created, and will be submitted in the next batch. |
api | refund_ |
The refund has been created, and will be submitted in the next batch. |
failed
The refund did not reach your customer, the funds will be returned to you. The details[cause]
will be refund_failed
, and the details[origin]
will be gocardless
. It is important to note that the ‘failed’ and ‘refund_settled’ events are not associated. A refund can fail even after it’s been settled. If a refund fails, GoCardless has attempted to refund the customer and has already deducted the applicable funds from one of your payouts. The refund has then subsequently failed to reach the customer. If this occurs, the funds will be returned to you.
Origin | Cause | Description |
---|---|---|
gocardless | refund_ |
The refund did not reach your customer, the funds will be returned to you. |
paid
The refund has been paid to your customer. The details[cause]
will be refund_paid
, and the details[origin]
will be gocardless
.
Origin | Cause | Description |
---|---|---|
gocardless | refund_ |
The refund has been paid to your customer. |
refund_settled
The refund has been deducted from a payout. The details[cause]
will be refund_settled
, and the details[origin]
will be gocardless
.
Origin | Cause | Description |
---|---|---|
gocardless | refund_ |
The refund has been deducted from a payout. |
funds_returned
The refund has been credited in a payout. The details[cause]
will be refund_funds_returned
, and the details[origin]
will be gocardless
.
Origin | Cause | Description |
---|---|---|
gocardless | refund_ |
The funds for the refund have been returned to you. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "refunds",
"action": "created",
"details": {
"origin": "api",
"cause": "payment_refunded",
"description": "The refund has been created, and will be submitted in the next batch."
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
},
"links": {
"refund": "RF123"
}
}
}
Scheme Identifier
This is a list of all the different values for action
activated
This scheme identifier has been activated.
Origin | Cause | Description |
---|---|---|
gocardless | scheme_ |
This scheme identifier has been activated. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2023-04-08T17:01:06.000Z",
"resource_type": "scheme_identifiers",
"action": "activated",
"links": {
"scheme_identifier": "SU222",
},
"details": {
"origin": "gocardless",
"cause": "scheme_identifier_activated",
"description": "This scheme identifier has been activated."
},
"metadata": {}
}
}
Subscription
This is a list of all the different values for action
created
The subscription has been created.
Origin | Cause | Description |
---|---|---|
api | subscription_ |
Subscription created via the API. |
customer_approval_granted
The subscription required additional approval from the customer before it could become active, and that approval has been granted.
Origin | Cause | Description |
---|---|---|
customer | customer_ |
The customer granted approval for this subscription |
customer_approval_denied
The subscription required additional approval from the customer before it could become active, and that approval has been denied.
Origin | Cause | Description |
---|---|---|
customer | customer_ |
The customer denied approval for this subscription |
amended
The subscription amount has been changed.
Origin | Cause | Description |
---|---|---|
api | subscription_ |
Subscription amount has been amended. |
payment_created
A payment has been created by this subscription.
Origin | Cause | Description |
---|---|---|
gocardless | payment_ |
Payment created by a subscription. |
cancelled
This subscription has been cancelled. No further payments will be created.
Origin | Cause | Scheme | Reason code | Description |
---|---|---|---|---|
bank | bank_ |
ach | ACH_ |
This subscription was cancelled because the customer is deceased. |
bank | return_ |
ach | ACH_ |
This subscription has been cancelled because its mandate was cancelled. |
bank | refer_ |
ach | ACH_ |
This subscription has been cancelled because the bank details for its mandate are incorrect. |
bank | bank_ |
ach | ACH_ |
This subscription has been cancelled because the bank account it was going to be taken from has been closed. |
bank | mandate_ |
ach | ACH_ |
This subscription was canceled because the customer cancelled the mandate at their bank. |
bank | mandate_ |
ach | ACH_ |
This subscription has been cancelled because the bank details for its mandate are incorrect. |
bank | invalid_ |
ach | ACH_ |
This subscription has been cancelled because the bank details for its mandate are incorrect. |
bank | direct_ |
ach | ACH_ |
This subscription has been cancelled because the bank account it was going to be taken from does not support direct debit. |
bank | refer_ |
ach | ACH_ |
This subscription has been cancelled because its mandate was cancelled. |
bank | authorisation_ |
ach | ACH_ |
This subscription has been cancelled because the customer disputes authorising its mandate. |
api | subscription_ |
- | - | The subscription has been cancelled at your request. |
api | mandate_ |
- | - | The subscription was cancelled because its mandate was cancelled at your request. |
api | bank_ |
- | - | The mandate for this subscription was cancelled at your request. |
gocardless | mandate_ |
- | - | The subscription was cancelled because its mandate has expired. |
bank | mandate_ |
bacs | ADDACS-0ADDACS-1 | The mandate for this subscription was cancelled at a bank branch. |
bank | bank_ |
bacs | ADDACS-2ADDACS-B | The mandate for this subscription was cancelled as the customer’s bank account has been closed. |
bank | bank_ |
bacs | ADDACS-3ADDACS-C | The mandate for this subscription was cancelled as the customer asked their bank to transfer the mandate to a new account, but the bank has failed to send GoCardless the new bank details. |
bank | authorisation_ |
bacs | ADDACS-D | The customer disputes authorising this mandate. |
bank | bank_ |
bacs | ARUDD-2 | This subscription was cancelled because the customer is deceased. |
bank | refer_ |
bacs | ARUDD-6 | An error was received from the banks while setting up the mandate for this subscription. |
bank | bank_ |
bacs | ARUDD-B | This subscription was cancelled because the customer closed their bank account before it could be collected. |
bank | invalid_ |
sepa_ |
AC01BE06 | This subscription has been cancelled because the bank details for its mandate are incorrect. |
bank | bank_ |
sepa_ |
AC04MD07 | This subscription has been cancelled because the bank account it was going to be taken from has been closed. |
bank | direct_ |
sepa_ |
AG01AC06 | This subscription has been cancelled because the bank account it was going to be taken from does not support direct debit. |
bank | account_ |
sepa_ |
AC06 | This subscription has been cancelled because the bank account for its mandate was blocked. |
bank | authorisation_ |
sepa_ |
MD01 | This subscription has been cancelled because the payer disputes authorising its mandate. |
bank | mandate_ |
sepa_ |
MD01 | This subscription has been cancelled because the payer disputes authorising its mandate. |
bank | authorisation_ |
bacs | DDICA-3DDICA-4DDICA-5DDICA-6DDICA-8 | This subscription has been cancelled because the customer disputes authorising its mandate. |
bank | bank_ |
bacs | AUDDIS-2AUDDIS-B | This subscription has been cancelled because the bank account for its mandate has been closed. |
bank | invalid_ |
bacs | AUDDIS-5 | This subscription has been cancelled because the bank details for its mandate are not valid. |
bank | bank_ |
bacs | AUDDIS-3AUDDIS-C | This subscription has been cancelled because the customer has requested for direct debits to be taken from a new account, but their bank did not send GoCardless the new bank details. |
bank | direct_ |
bacs | AUDDIS-FAUDDIS-GAUDDIS-N | This subscription has been cancelled because the bank account for its mandate does not support direct debit. |
bank | invalid_ |
bacs | ARUDD-5ARUDD-YARUDD-E | This subscription has been cancelled because the bank details for its mandate are not valid. |
bank | mandate_ |
bacs | ARUDD-1 | This subscription was canceled because the customer cancelled the mandate at their bank. |
api | plan_ |
- | - | The subscription has been cancelled because the associated plan was cancelled. |
bank | authorisation_ |
becs | UDUNAUT | This subscription has been cancelled because the customer disputes authorising its mandate. |
bank | mandate_ |
becs | CBC | This subscription has been cancelled because its mandate was cancelled. |
bank | direct_ |
becs | 2 | This subscription has been cancelled because the bank account for its mandate does not support direct debit. |
bank | payment_ |
becs | 2 | The subscription was cancelled because the payment was stopped by the payer or their bank. |
bank | bank_ |
becs | 4 | This subscription was cancelled because the customer is deceased. |
bank | invalid_ |
becs | DEN | This subscription has been cancelled because the bank details for its mandate are not valid. |
bank | bank_ |
becs_ |
DISHONOUR-AC04 | This subscription has been cancelled because the bank account it was going to be taken from has been closed. |
bank | invalid_ |
pad | PAYMENT_ |
This subscription has been cancelled because the bank details for its mandate are not valid. |
bank | bank_ |
pad | PAYMENT_ |
This subscription has been cancelled because the bank account for its mandate has been closed. |
bank | direct_ |
pad | PAYMENT_ |
This subscription has been cancelled because the bank account for its mandate does not support direct debit. |
bank | bank_ |
pad | PAYMENT_ |
This subscription was cancelled because the customer is deceased. |
bank | authorisation_ |
pad | PAYMENT_ |
This subscription has been cancelled because the customer disputes authorising its mandate. |
bank | other | pad | PAYMENT_ |
An error was received from the banks while setting up the mandate for this subscription. |
bank | refer_ |
pad | PAYMENT_ |
An error was received from the banks while setting up the mandate for this subscription. |
bank | mandate_ |
pad | PAYMENT_ |
This subscription has been cancelled because its mandate was cancelled. |
bank | mandate_ |
faster_ |
PAYER_ |
This subscription has been cancelled because its mandate was cancelled. |
bank | mandate_ |
pay_ |
SBP | The subscription has been cancelled because its mandate was suspended by payer. |
gocardless | mandate_ |
faster_ |
MERCHANT_ |
The mandate for this subscription was cancelled at your request. |
gocardless | mandate_ |
faster_ |
MANDATE_ |
The subscription was cancelled because its mandate has expired. |
gocardless | initial_ |
- | - | This subscription has been cancelled because its mandate was cancelled. |
finished
This subscription has finished. No further payments will be created.
Origin | Cause | Description |
---|---|---|
gocardless | subscription_ |
The subscription has finished. |
paused
This subscription has been paused.
Origin | Cause | Description |
---|---|---|
api | subscription_ |
The subscription has been paused. |
gocardless | subscription_ |
The subscription has been paused. |
resumed
This subscription was resumed.
Origin | Cause | Description |
---|---|---|
api | subscription_ |
The subscription was resumed. |
gocardless | subscription_ |
The subscription was resumed. |
scheduled_pause
This subscription has been scheduled to be paused at a future date.
Origin | Cause | Description |
---|---|---|
api | scheduled_ |
The subscription has been scheduled to be paused at a future date. |
scheduled_pause_cancelled
An upcoming pause for this subscription has been cancelled.
Origin | Cause | Description |
---|---|---|
api | scheduled_ |
An upcoming pause for this subscription has been cancelled. |
scheduled_resume
This paused subscription has been scheduled to be resumed at a future date.
Origin | Cause | Description |
---|---|---|
api | scheduled_ |
This paused subscription has been scheduled to be resumed at a future date. |
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "subscriptions",
"action": "payment_created",
"links": {
"subscription": "SB123",
"payment": "PM123"
},
"details": {
"origin": "api",
"cause": "payment_created",
"description": "Payment created by a subscription."
},
"metadata": {},
"resource_metadata": {
"order_dispatch_date": "2014-05-22"
}
}
}
Intelligent Retries
Intelligent retries is a feature which automatically retries payments if they fail.
Important: To be able to use intelligent retries, Success+ needs to be enabled in Gocardless Dashboard.
Individual Payments
Creating Payment
When creating a payment set retry_if_possible
to true
This will enable intelligent retries if the payment is considered eligible.
Updating Payment
If a payment has been created with retry_if_possible
set to true, then it can be updated to
false
. This will prevent the payment being automatically retried in the event of a failure.
The API currently only allows the flag to be updated to false
. Hence for a payment which
has been already created it is not allowed to set this flag to true
.
POST https://api.gocardless.com/payments HTTP/1.1
Content-Type: application/json
{
"payments": {
"amount": 100,
"currency": "GBP",
"retry_if_possible": true,
...
}
}
PUT https://api.gocardless.com/payments/PM123 HTTP/1.1
Content-Type: application/json
{
"payments": {
"retry_if_possible": false
}
}
Instalment Schedules
When creating an instalment schedule set retry_if_possible
to true
to ensure that all instalment payments created are automatically retried upon failure.
POST https://api.gocardless.com/instalment_schedules HTTP/1.1
Content-Type: application/json
{
"instalment_schedules": {
"name": "Bike Invoice 271",
"total_amount": "2500",
"currency": "GBP",
"retry_if_possible": true,
...
}
Subscriptions
When creating a subscription set retry_if_possible
to true
to ensure that all payments created for the subscription are retried automatically upon failure.
POST https://api.gocardless.com/subscriptions HTTP/1.1
Content-Type: application/json
{
"subscriptions": {
"amount": "2500",
"currency": "GBP",
"interval_unit": "monthly",
"retry_if_possible": true,
...
}
Handling Failures
On payment failure the failed
event will always be sent. If the payment will be automatically retried the field will_attempt_retry
will be true
.
When a payment is automatically retried it will trigger a resubmission_requested
event just like any other type of retry.
When will_attempt_retry
is true
, GoCardless will automatically retry the payment. Please do not attempt to collect the payment from the customer yourself, as this can lead to them being double charged.
GET https://api.gocardless.com/events/EV123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"events": {
"id": "EV123",
"created_at": "2014-04-08T17:01:06.000Z",
"resource_type": "payments",
"action": "failed",
"details": {
"origin": "bank",
"cause": "insufficient_funds",
"description": "The customer's account had insufficient funds to make this payment.",
"scheme": "sepa_core",
"reason_code": "AM04",
"will_attempt_retry": true
},
"metadata": {},
"links": {
"payment": "PM123"
}
}
}
Retry Rules
The criteria below are subject to change and should not be relied upon.
Use the will_attempt_retry
field above
to know for sure if a payment will be retried.
The retry_if_possible
field does not guarantee the payment will be retried on failure.
A payment will be retried if the following conditions are met:
- Intelligent retries for the scheme has been enabled on the settings page.
- The payment has field
retry_if_possible
set to true. - The payment has failed due to insufficient funds.
- The number of payment failures is lesser than the number of retries configured in the intelligent retries settings page.
- The subsequent retry can be confirmed within the retry window configured in the intelligent retries settings page.
Healthcheck
We expose a health check endpoint which can be used to test connections to our API.
Requests to this endpoint do not require authorization and are not rate limited.
This endpoint will return a 200
response while our API is available.
-
https://api.gocardless.com/health_check
for live -
https://api-sandbox.gocardless.com/health_check
for sandbox
Bank Details Lookups
Look up the name and reachability of a bank account.
Properties
available_
debit_ schemes - Array of schemes supported for this bank account. This will be an empty array if the bank account is not reachable by any schemes.
bank_
name - The name of the bank with which the account is held (if available).
bic
- ISO 9362 SWIFT BIC of the bank with which the account is held.
Even if no BIC is returned for an account, GoCardless may still be able to collect payments from it - you should refer to the
available_debit_schemes
attribute to determine reachability.
Perform a bank details lookup
Performs a bank details lookup. As part of the lookup, a modulus check and reachability check are performed.
For UK-based bank accounts, where an account holder name is provided (and an account number, a sort code or an iban are already present), we verify that the account holder name and bank account number match the details held by the relevant bank.
If your request returns an error or the available_debit_schemes
attribute is an empty array, you will not be able to collect payments from the
specified bank account. GoCardless may be able to collect payments from an account
even if no bic
is returned.
Bank account details may be supplied using local details or an IBAN.
ACH scheme For compliance reasons, an extra validation step is done using a third-party provider to make sure the customer’s bank account can accept Direct Debit. If a bank account is discovered to be closed or invalid, the customer is requested to adjust the account number/routing number and succeed in this check to continue with the flow.
Note: Usage of this endpoint is monitored. If your organisation relies on GoCardless for modulus or reachability checking but not for payment collection, please get in touch.
Relative endpoint: POST /bank_details_lookups
Parameters
account_
holder_ name - The account holder name associated with the account number (if available). If provided and the country code is GB, a payer name verification will be performed.
account_
number - Bank account number - see local details for more information. Alternatively you can provide an
iban
. bank_
code - Bank code - see local details for more information. Alternatively you can provide an
iban
. branch_
code - Branch code - see local details for more information. Alternatively you can provide an
iban
. country_
code - ISO 3166-1 alpha-2 code. Must be provided if specifying local details.
iban
- International Bank Account Number. Alternatively you can provide local details.
POST https://api.gocardless.com/bank_details_lookups HTTP/1.1
Content-Type: application/json
{
"bank_details_lookups": {
"account_number": "55779911",
"branch_code": "200000",
"country_code": "GB"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"bank_details_lookups": {
"available_debit_schemes": ["bacs"],
"bank_name": "BARCLAYS BANK PLC",
"bic": "BARCGB22XXX"
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->bankDetailsLookups()->create([
"params" => ["account_number" => "55779911",
"branch_code" => "200000",
"country_code" => "GB"]
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.bank_details_lookups.create(params={
"account_number": "55779911",
"branch_code": "200000",
"country_code": "GB"
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.bank_details_lookups.create(
params: {
country_code: "GB",
account_number: "55779911",
branch_code: "200000"
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
BankDetailsLookup bankDetailsLookup = client.bankDetailsLookups().create()
.withAccountNumber("55779911")
.withBranchCode("200000")
.withCountryCode("GB")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
const bankDetailsLookup = await client.bankDetailsLookups.create({
account_number: "55779911",
branch_code: "200000",
country_code: "GB"
});
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var bankDetailsRequest = new GoCardless.Services.BankDetailsLookupCreateRequest()
{
AccountNumber = "55779911",
BranchCode = "200000",
CountryCode = "GB"
};
var bankDetailsResponse = await gocardless.BankDetailsLookups.CreateAsync(bankDetailsRequest);
GoCardless.Resources.BankDetailsLookup bankDetails = bankDetailsResponse.BankDetailsLookup;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
bankDetailsLookupCreateParams := gocardless.BankDetailsLookupCreateParams{
AccountNumber: "55779911",
BranchCode: "200000",
CountryCode: "GB",
}
bankDetailsLookup, err := client.BankDetailsLookups.Create(context, bankAuthorisationCreateParams)
}
Mandate PDFs
Mandate PDFs allow you to easily display scheme-rules compliant Direct Debit mandates to your customers.
Properties
expires_
at - The date and time at which the
url
will expire (10 minutes after the original request). url
- The URL at which this mandate PDF can be viewed until it expires at the date and time specified by
expires_at
. You should not store this URL or rely on its structure remaining the same.
Create a mandate PDF
Generates a PDF mandate and returns its temporary URL.
Customer and bank account details can be left blank (for a blank mandate), provided manually, or inferred from the ID of an existing mandate.
By default, we’ll generate PDF mandates in English.
To generate a PDF mandate in another language, set the Accept-Language
header when creating the PDF mandate to the relevant ISO 639-1 language code supported for the scheme.
Scheme | Supported languages |
---|---|
ACH | English (en) |
Autogiro | English (en), Swedish (sv) |
Bacs | English (en) |
BECS | English (en) |
BECS NZ | English (en) |
Betalingsservice | Danish (da), English (en) |
PAD | English (en) |
SEPA Core | Danish (da), Dutch (nl), English (en), French (fr), German (de), Italian (it), Portuguese (pt), Spanish (es), Swedish (sv) |
Relative endpoint: POST /mandate_pdfs
Parameters
account_
holder_ name - Name of the account holder, as known by the bank. Usually this matches the name of the customer. This field cannot exceed 18 characters.
account_
number - Bank account number - see local details for more information. Alternatively you can provide an
iban
. account_
type - Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See local details for more information.
address_
line1 - The first line of the customer’s address.
address_
line2 - The second line of the customer’s address.
address_
line3 - The third line of the customer’s address.
bank_
code - Bank code - see local details for more information. Alternatively you can provide an
iban
. bic
- SWIFT BIC. Will be derived automatically if a valid
iban
or local details are provided. branch_
code - Branch code - see local details for more information. Alternatively you can provide an
iban
. city
- The city of the customer’s address.
company_
name - The customer’s company name. Used to populate the “Customer Name or Company name” field on the PDF.
country_
code - ISO 3166-1 alpha-2 code. Required if providing local details.
danish_
identity_ number - For Danish customers only. The civic/company number (CPR or CVR) of the customer. Should only be supplied for Betalingsservice mandates.
family_
name - The customer’s family name (i.e. last name). Used to populate the “Customer Name or Company name” field on the PDF. Ignored if
company_name
is provided. given_
name - The customer’s given name (i.e. first name). Used to populate the “Customer Name or Company name” field on the PDF. Ignored if
company_name
is provided. iban
- International Bank Account Number. Alternatively you can provide local details. IBANs cannot be provided for Autogiro mandates.
mandate_
reference - Unique 6 to 18 character reference. This may be left blank at the point of signing.
payer_
ip_ address - For American customers only. IP address of the computer used by the customer to set up the mandate. This is required in order to create compliant Mandate PDFs according to the ACH scheme rules.
phone_
number - The customer phone number. Should only be provided for BECS NZ mandates.
postal_
code - The customer’s postal code.
region
- The customer’s address region, county or department. For US customers a 2 letter ISO3166-2:US state code is required (e.g.
CA
for California). scheme
- Direct Debit scheme. Can be supplied or automatically detected from the bank account details provided. If you do not provide a scheme, you must provide either a mandate, an
iban
, or local details including acountry_code
. signature_
date - If provided, a form will be generated with this date and no signature field.
subscription_
amount - For American customers only. Subscription amount being authorised by the mandate. In the lowest denomination for the currency (cents in USD). Is required if
subscription_frequency
has been provided. subscription_
frequency - For American customers only. Frequency of the subscription being authorised by the mandate. One of
weekly
,monthly
oryearly
. Is required ifsubscription_amount
has been provided. swedish_
identity_ number - For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Should only be supplied for Autogiro mandates.
links
[creditor] - ID of an existing creditor. Only required if your account manages multiple creditors.
links
[mandate] - ID of an existing mandate to build the PDF from. The customer’s bank details will be censored in the generated PDF. No other parameters may be provided alongside this.
POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
{
"mandate_pdfs": {
"links": {
"mandate": "MD123"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_pdfs": {
"url": "https://mandate-previews.gocardless.com/?token=lhulxcPEbT9v3W0QUpBOxhlGUSYEayQQ4VVrpO7YnUKRYynP5",
"expires_at": "2014-05-08T17:01:06.000Z"
}
}
POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
{
"mandate_pdfs": {
"account_number": "44779911",
"branch_code": "200000",
"country_code": "GB"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_pdfs": {
"url": "https://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5",
"expires_at": "2014-05-08T17:01:06.000Z"
}
}
POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
Accept-Language: fr
{
"mandate_pdfs": {
"iban": "FR14BARC20000055779911"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"mandate_pdfs": {
"url": "https://mandate-previews.gocardless.com/?token=vlaPBHzSvm1OPwDNatZYWJCM7XZcCUuLPn7m5XV5",
"expires_at": "2014-05-08T17:01:06.000Z"
}
}
POST https://api.gocardless.com/mandate_pdfs HTTP/1.1
Content-Type: application/json
{
"mandate_pdfs": {
"account_number": "44779911",
"branch_code": "200000",
"country_code": "GB",
"links": {
"mandate": "MD123"
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": {
"message": "Cannot provide both a mandate and other details",
"documentation_url": "https://developer.gocardless.com/api-reference#validation_failed",
"type": "validation_failed",
"request_id": "bd271b37-a2f5-47c8-b461-040dfe0e9cb1",
"code": 422,
"errors": [
{
"reason": "validation_failed",
"message": "Cannot provide both a mandate and other details"
}
]
}
}
$client = new \GoCardlessPro\Client([
'access_token' => 'your_access_token_here',
'environment' => \GoCardlessPro\Environment::SANDBOX
]);
$client->mandatePdfs()->create([
"params" => ["links" => ["mandate" => "MD123"]]
]);
$client->mandate_pdfs()->create([
"params" => ["account_number" => "44779911",
"branch_code" => "200000",
"country_code" => "GB"]
]);
$client->mandatePdfs()->create([
"params" => ["iban" => "FR14BARC20000055779911"],
"headers" => ['accept-language' => 'fr']
]);
import gocardless_pro
client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')
client.mandate_pdfs.create(params={
"links": {"mandate": "MD123"}
})
client.mandate_pdfs.create(params={
"account_number": "44779911",
"branch_code": "200000",
"country_code": "GB"
})
client.mandate_pdfs.create(params={
"iban": "FR14BARC20000055779911"
}, headers={
"Accept-Language": "fr"
})
@client = GoCardlessPro::Client.new(
access_token: "your_access_token",
environment: :sandbox
)
@client.mandate_pdfs.create(
params: {
links: { mandate: "MD123" }
}
)
@client.mandate_pdfs.create(
params: {
account_number: "55779911",
branch_code: "200000",
country_code: "GB"
}
)
@client.mandate_pdfs.create(
params: {
iban: "FR14BARC20000055779911",
},
headers: {
"Accept-Language" => "fr"
}
)
import static com.gocardless.GoCardlessClient.Environment.SANDBOX;
String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
.newBuilder(accessToken)
.withEnvironment(SANDBOX)
.build();
MandatePdf mandatePdfForMandate = client.mandatePdfs().create()
.withLinksMandate("MD123")
.execute();
MandatePdf mandatePdfForBankDetails = client.mandatePdfs.create()
.withAccountNumber("44779911")
.withBranchCode("200000")
.withCountryCode("GB")
.execute();
MandatePdf mandatePdfInFrench = client.mandatePdfs.create()
.withIban("FR14BARC20000055779911")
.withHeader("Accept-Language", "fr")
.execute();
const constants = require('gocardless-nodejs/constants');
const gocardless = require('gocardless-nodejs');
const client = gocardless('your_access_token_here', constants.Environments.Sandbox);
await client.mandatePdfs.create({
links: {
mandate: "MD123"
}
});
await client.mandatePdfs.create(
{
links: {
mandate: "MD123"
}
},
"mandate_pdfs_idempotency_key"
);
await client.mandatePdfs.create(
{
account_number: "44779911",
branch_code: "200000",
country_code: "GB"
},
"",
{ "Accept-Language": "fr" }
);
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
var mandatePdfRequest = new GoCardless.Services.MandatePdfsCreateRequest()
{
AccountNumber = "55779911",
BranchCode = "200000",
CountryCode = "GB"
};
var mandatePdfResponse = await Gocardless.MandatePdfs.CreateAsync(mandatePdfRequest);
GoCardless.Resources.MandatePdf mandatePdf = mandatePdfResponse.MandatePdf;
var mandatePdfRequest = new GoCardless.Services.MandatePdfsCreateRequest()
{
Iban = "FR14BARC20000055779911"
};
var requestSettings = new GoCardless.Internals.RequestSettings
{
CustomiseRequestMessage = msg => msg.Headers.Add("Accept-Language", "fr")
};
var mandatePdfResponse = await GoCardless.MandatePdfs.CreateAsync(mandatePdfRequest, requestSettings);
GoCardless.Resources.MandatePdf mandatePdf = mandatePdfResponse.MandatePdf;
package main
import (
gocardless "github.com/gocardless/gocardless-pro-go/v2"
)
func main() {
accessToken := "your_access_token_here"
config, err := gocardless.NewConfig(accessToken, gocardless.WithEndpoint(gocardless.SandboxEndpoint))
if err != nil {
fmt.Printf("got err in initialising config: %s", err.Error())
return
}
client, err := gocardless.New(config)
if err != nil {
fmt.Println("error in initialisating client: %s", err.Error())
return
}
mandatePdfCreateParams := gocardless.MandatePdfCreateParams{
Links: &gocardless.MandatePdfCreateParamsLinks{
Mandate: "MD123",
},
}
mandatePdf, err := client.MandatePdfs.Create(context, mandatePdfCreateParams)
requestOption := gocardless.WithIdempotencyKey("mandate_pdfs_idempotency_key")
mandatePdf, err = client.MandatePdfs.Create(context, mandatePdfCreateParams, requestOption)
headers := map[string]string{"Accept-Language": "fr"}
requestOption = gocardless.WithHeaders(headers)
mandatePdf, err = client.MandatePdfs.Create(context, mandatePdfCreateParams, requestOption)
}
Appendix
Webhooks
Check out our getting started guide for a step-by-step introduction to handling webhooks, with PHP, Ruby, Python and Java code samples
Overview
A webhook is a HTTP request containing a list of GoCardless events. Webhooks notify you of new events, e.g. when the bank informs us that one of your payments has failed.
You can enable webhooks by creating a Webhook Endpoint
in your GoCardless dashboard.
When an event occurs in your GoCardless account, we’ll batch that (and any
other undelivered events) up into a single webhook and send it to every enabled webhook
endpoint as a POST
request.
There are a few things to note when using webhooks:
-
Webhooks may arrive out of order, or the same one may be delivered multiple times. Each event may be included in one or more webhooks. We can only guarantee that we’ll try to deliver each event at least once.
-
When deciding what actions to take in response to Webhook events, we recommend you switch on the
details[cause]
field. Other fields, such asdetails[reason_code]
, are payment scheme-specific and can be inconsistent between banks, whereas thedetails[cause]
field is our simplified and predictable key indicating what triggered the event. -
Webhooks with an invalid signature must return a
498 Token Invalid
error. -
Webhooks about unknown events should be ignored, and return
204 No Content
. GoCardless may add new events to the API without considering this a backwards incompatible change. -
You must use
SSL/TLS
for webhook URLs. Unsecured webhook URLs are only allowed in the sandbox environment. Your server must respond with the full certificate chain including intermediate certificates. You can test this with a tool like Qualys SSL labs -
Webhooks include an
Origin
header indicating what GoCardless environment they were sent from. This will behttps://api.gocardless.com
for live, andhttps://api-sandbox.gocardless.com
for sandbox. -
All the webhooks you’ve ever been sent are viewable in your GoCardless dashboard in the “Developers” area.
-
The webhook ID included under the
meta
key should not be used for deduplication: it is only included to help with debugging. Searching for this ID in the GoCardless dashboard will show you the information on the most recent delivery attempt for this webhook.
Our webhooks platform will only wait 10 seconds for a response from your server, before
terminating the request - we suggest you store the webhook body and execute
any work that needs doing asynchronously to avoid issues.
The Webhook’s response_code
will be null
when this happens.
Status codes
Your webhook handler should return a response with a 2xx status code,
e.g. 200 OK
, or 204 No Content
. If the webhook signature is invalid, you should return
a 498 Invalid Token
Errors & Retries
In the event we fail to deliver the webhook, or you respond with a non 2xx status code, we will attempt to resend the webhook up to 8 times at increasing time intervals, including the initial attempt this will be a total of 9 attempts.
You can view webhooks we’ve sent you in your GoCardless dashboard, and can retry them if required.
Approved IP addresses
We send webhooks from the following IP addresses which you may wish to add to your firewalls approved list:
- 35.204.73.47
- 35.204.191.250
- 35.204.214.181
We will provide advance notification by email at least two weeks before we make any changes to these addresses.
You can set the email we will contact you at from your Dashboard - simply click “Settings” in the top-right hand corner, then “Contact preferences”, and then edit your developer contact.
Signing Webhooks
We sign the body of the POST request with an HMAC SHA256 hex digest, using the secret of the webhook endpoint for which this webhook is being sent. This is done using an additional header:
Webhook-Signature
- The HMAC SHA256 hex digest of the request body.
You must check that the webhook has a valid signature before processing it. Here’s how you could do that in Ruby:
# request_signature - the signature sent in Webhook-Signature
# request_body - the JSON body of the webhook request
# secret - the secret for the webhook endpoint
require "openssl"
digest = OpenSSL::Digest.new("sha256")
calculated_signature = OpenSSL::HMAC.hexdigest(digest, secret, request_body)
if calculated_signature == request_signature
# Signature ok!
else
# Invalid signature. Ignore the webhook and return 498 Token Invalid
end
Examples
Payments
In this example, you have set up two customers, and each has a mandate. You
created a payment for each customer, called “Test Payment” and “Test Payment 2”
respectively. A few days later, these have been collected, and this has generated
a payment update event for those payments. You have created a webhook endpoint, with id
WE123
, secret 123ABC456DEF
, and url https://example.com/webhooks
.
We will send a POST
request, like the one on the right, to
https://example.com/webhooks
. To process it, you should:
- Store the contents of the webhook in durable storage e.g a database or queue.
- Check the signature
- Return 204 No Content
- Process the content of the webhook asynchronously by
- Checking that you have not already processed the events contained in the webhook.
- Fetching the updated resources, using the ID’s supplied, and check that they have not changed further since the webhook was sent (since webhooks may arrive out of order)
- Acting on the events, e.g. shipping goods, extending subscription
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Origin: https://api-sandbox.gocardless.com
Content-Type: application/json
Webhook-Signature: 8d625e2359a8a2f9161e0ec9a534a9f75c47aa7b305b18685929ad58f08d2efc
{
"events": [
{
"id": "EV123",
"created_at": "2014-08-03T12:00:00.000Z",
"action": "confirmed",
"resource_type": "payments",
"links": {
"payment": "PM123"
},
"details": {
"origin": "gocardless",
"cause": "payment_confirmed",
"description": "Payment was confirmed as collected"
}
},
{
"id": "EV456",
"created_at": "2014-08-03T12:00:00.000Z",
"action": "failed",
"resource_type": "payments",
"links": {
"payment": "PM456"
},
"details": {
"origin": "bank",
"cause": "mandate_cancelled",
"description": "Customer cancelled the mandate at their bank branch.",
"scheme": "bacs",
"reason_code": "ARUDD-1"
}
}
],
"meta": { "webhook_id": "WB123" }
}
Mandates
In this example a customer has two mandates, and has just closed their bank account. Both mandates were cancelled by their bank, and this is being passed on through GoCardless via a webhook, using the same webhook endpoint as in the previous example. Once again, you should:
- Store the contents of the webhook in durable storage e.g a database or queue.
- Check the signature
- Return 204 No Content
- Process the content of the webhook asynchronously by
- Checking that you have not already processed the events contained in the webhook.
- Fetching the updated resources, using the ID’s supplied, and check that they have not changed further since the webhook was sent (since webhooks may arrive out of order)
- Acting on the events, e.g. shipping goods, extending subscription
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Origin: https://api-sandbox.gocardless.com
Content-Type: application/json
Webhook-Signature: c1ec421b5f7a1f06172ee1c50d013fe9a91f0db899718f88f9d4a32a4e2180e5
{
"events": [
{
"id": "EV123",
"created_at": "2014-08-04T12:00:00.000Z",
"action": "cancelled",
"resource_type": "mandates",
"links": {
"mandate": "MD123"
},
"details": {
"origin": "bank",
"cause": "bank_account_disabled",
"description": "Your customer closed their bank account.",
"scheme": "bacs",
"reason_code": "ADDACS-B"
}
},
{
"id": "EV456",
"created_at": "2014-08-04T12:00:00.000Z",
"action": "expired",
"resource_type": "mandates",
"links": {
"mandate": "MD456"
},
"details": {
"origin": "gocardless",
"cause": "mandate_expired",
"description": "The mandate expired due to inactivity."
}
}
],
"meta": { "webhook_id": "WB123" }
}
Payouts
In this example, your payments have been collected by GoCardless, and are now ready to be paid out into the associated creditor bank account. This payout has just been generated, which triggers a webhook using the same webhook endpoint as in the previous examples. Once again you should:
- Store the contents of the webhook in durable storage e.g a database or queue.
- Check the signature
- Return 204 No Content
- Process the content of the webhook asynchronously by
- Checking that you have not already processed the events contained in the webhook.
- Fetching the updated resources, using the ID’s supplied, and check that they have not changed further since the webhook was sent (since webhooks may arrive out of order)
- Acting on the events, e.g. shipping goods, extending subscription
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Origin: https://api-sandbox.gocardless.com
Content-Type: application/json
Webhook-Signature: 42aa2860ecb559d16f9ecbe7e590ffeee2a992a03008be1deca22d97865693a7
{
"events": [
{
"id": "EV123",
"created_at": "2014-08-04T12:00:00.000Z",
"action": "paid",
"resource_type": "payouts",
"links": {
"payout": "PO123"
}
}
],
"meta": { "webhook_id": "WB123" }
}
Subscriptions
In this example a subscription has just raised a payment, which triggers a webhook using the same webhook endpoint as in the previous examples. Once again you should:
- Store the contents of the webhook in durable storage e.g a database or queue.
- Check the signature
- Return 204 No Content
- Process the content of the webhook asynchronously by
- Checking that you have not already processed the events contained in the webhook.
- Fetching the updated resources, using the ID’s supplied, and check that they have not changed further since the webhook was sent (since webhooks may arrive out of order)
- Acting on the events, e.g. shipping goods, extending subscription
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Origin: https://api-sandbox.gocardless.com
Content-Type: application/json
Webhook-Signature: da7db0aa5e63b77b3890e7ca85c129a8b317f7605f7d6e43466751a70ff4afe7
{
"events": [
{
"id": "EV123",
"created_at": "2014-08-04T12:00:00.000Z",
"action": "payment_created",
"resource_type": "subscriptions",
"links": {
"subscription": "SB123",
"payment": "PM123"
}
}
],
"meta": { "webhook_id": "WB123" }
}
JavaScript Flow
You can use our JavaScript flow to create custom payment pages. Our JavaScript library will send sensitive bank details to our servers directly and return a token that can be used to create a customer bank account.
The API allows you to create and show your customer bank account tokens.
Restricted: the JavaScript Flow is restricted to GoCardless Pro & Enterprise accounts with approved payment pages. To instead use the GoCardless hosted payment pages, see the redirect flows endpoint.
Customer Bank Account Tokens
Customer bank account tokens can only be used once. Attempting to create a second customer bank account from the same customer bank account token will result in a customer_bank_account_token_used
error.
Properties
id
- Unique identifier, beginning with “AT”.
created_
at - Fixed timestamp of when the customer bank account token was originally created.
links
[customer_ bank_ account] - ID of customer bank account that was created from this token.
Note: this property will only be present if this token has been used to create a customer bank account.
Create a customer bank account token
Creates a new customer bank account token object.
Relative endpoint: POST /customer_bank_account_tokens
Note: The customer bank account token API is currently in beta and will change.
We may not honour the usual backwards compatibility practice, however we will do our best to inform you of upcoming changes.
GoCardless performs modulus checks on all bank details. For testing purposes, check the test bank details section for a list of scheme specific set of bank details you can use.
The overall flow is:
-
You render a payment form with a publishable access token embedded on the page.
-
Your customer supplies their bank account details and submits the form. The form submission needs to be intercepted in JavaScript and submitted using our JavaScript library; on success you should inject the created token into the form and complete the submission to your server.
-
You create a customer bank account passing in the token in place of bank account details.
Intercepting form submission with the JavaScript library
Parameters
Bank account details may either be supplied using the IBAN (international bank account number), or local details. For more information on the different fields required in each country, please see the local bank details section.
publishable_
access_ token -
required can only be sent as a top level parameter. This token will be sent through
in the
Authorization
header when the request is made. account_
number - Bank account number.
bank_
code - Bank identifying code.
branch_
code - Branch identifying code.
iban
- Valid international bank account number.
account_
type - Bank account type. Only required for USD denominated bank accounts - see local details for more information.
country_
code -
ISO 3166-1 alpha-2 code. Defaults to the country code of the
iban
if supplied, otherwise is required. currency
-
ISO 4217 currency code, defaults to national currency of
country_code
. account_
holder_ name - required Name of the account holder, as it appears with the bank. This may not be more than 18 characters.
<!DOCTYPE html>
<html>
<body>
<script src="https://pay-sandbox.gocardless.com/js/beta"></script>
<!-- For the live environment, use https://pay.gocardless.com/js/beta -->
<form id="form"
action="/complete"
method="post"
onsubmit="onSubmit(event)">
<input name="publishable_access_token" id="publishable_access_token" type="hidden"
value="JF00001078YEW7VHAH0RA4Z73J7PYBYN">
<input name="given_name" id="given_name" type="text">
<input name="family_name" id="family_name" type="text">
<input name="address_line1" id="address_line1" type="text">
<input name="city" id="city" type="text">
<input name="region" id="region" type="text">
<input name="postal_code" id="postal_code" type="text">
<input name="country_code" id="country_code" type="text">
<input id="account_number" type="text">
<input id="account_type" type="text">
<input id="bank_code" type="text">
<input id="branch_code" type="text">
<input id="iban" type="text">
<input id="account_holder_name" type="text">
<input id="bank_accounts_country_code" type="text">
<input type="submit" value="Continue">
<h1 id="error"></h1>
</form>
<script>
function onSubmit(event) {
var form = event.target;
var publishableAccessToken = document.getElementById('publishable_access_token').value;
GoCardless.customerBankAccountTokens.create({
publishable_access_token: publishableAccessToken,
customer_bank_account_tokens: {
account_number: document.getElementById('account_number').value,
bank_code: document.getElementById('bank_code').value,
branch_code: document.getElementById('branch_code').value,
iban: document.getElementById('iban').value,
account_holder_name: document.getElementById('account_holder_name').value,
country_code: document.getElementById('bank_accounts_country_code').value
}
}, function(response) {
if (response.error) {
document.getElementById('error')
.textContent = 'Error: ' + response.error.message;
} else {
var input = document.createElement('input');
input.type = 'hidden';
input.value = response.customer_bank_account_tokens.id;
input.name = 'customer_bank_account_token';
form.appendChild(input);
form.submit();
}
});
// Prevent form submission
event.preventDefault();
}
</script>
</body>
</html>
Creating a customer bank account after the form is submitted.
require "gocardless_pro"
require "sinatra"
post "/complete" do
client = GoCardlessPro::Client.new(access_token: "access_token")
# You can also pass in environment as :sandbox to make requests to the sandbox environment rather than production
customer_params = {
email: params[:email],
given_name: params[:given_name],
family_name: params[:family_name],
address_line1: params[:address_line1],
city: params[:city],
postal_code: params[:postal_code],
country_code: params[:country_code],
}
customer = client.customers.create(params: customer_params)
customer_bank_account_params = {
links: {
customer: customer.id,
customer_bank_account_token: params[:customer_bank_account_token]
}
}
customer_bank_account = client.customer_bank_accounts.create(
params: customer_bank_account_params
)
new_mandate = client.mandates.create(params: {
links: {
customer_bank_account: customer_bank_account.id
}
})
puts new_mandate.inspect
"Thanks!"
end
Get a single customer bank account token
Retrieves the details of an existing customer bank account token.
Relative endpoint: GET /customer_bank_account_tokens/AT123
GET https://api.gocardless.com/customer_bank_account_tokens/AT123 HTTP/1.1
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"customer_bank_account_tokens": {
"id": "AT123",
"created_at": "2014-05-08T17:01:06.000Z",
"links": {
"customer_bank_account": "BA123"
}
}
}
OAuth
Check out our getting started guide for a step-by-step introduction to building an OAuth integration, with PHP, Ruby, Python and Java code samples
OAuth allows you to work with other users’ GoCardless accounts. Once a user approves you, you can use the GoCardless API on their behalf and receive their webhooks.
The GoCardless OAuth API conforms to the OAuth spec, and can be used with OAuth client libraries available in most languages.
The base URLs for the GoCardless OAuth API are:
-
https://connect.gocardless.com
for live -
https://connect-sandbox.gocardless.com
for sandbox
The OAuth flow
The flow to link a GoCardless account to your app is as follows:
- The user clicks a link on your site to the GoCardless OAuth flow. The link includes details of your app as well as a
scope
which defines the level of access you want the user to authorise. - On the GoCardless OAuth page, the user logs in to their GoCardless account, or creates a new one, and agrees to connect their account to your app.
- The user, having agreed that they’d like to connect to your app, is redirected back to your site with a
code
. - Your site exchanges the
code
for a permanentaccess_token
which can be stored and used to make requests to the API on the user’s behalf. - You can then make API requests using the user’s access token and receive webhooks relating to their account.
You can try the process for yourself by connecting your sandbox account to our example app. The source code, written in Ruby, is available here - it provides a good introduction to creating your own OAuth app.
Creating an OAuth app
To get started, you’ll need a GoCardless account. If you haven’t already, you can sign up here to get one. Once you’re logged into your account, you can create apps from the developer section of your dashboard
When you do this, you’ll be issued a client_id
and client_secret
, each 64
characters long, which you’ll use to identify your integration when requesting
access to other users’ GoCardless accounts.
Building an authorisation link
An authorisation link takes your user to the GoCardless OAuth flow, where they may agree to connect their GoCardless account to your app. It includes details of your app and the level of access requested.
To construct an authorisation link, take the relevant OAuth base URL plus the relative endpoint /oauth/authorize
with the following querystring parameters. You should redirect your user to this link using a GET
request.
Parameters
response_
type -
required The kind of OAuth request you’re making - only
code
is supported. client_
id -
required The
client_id
of your app. scope
-
required The level of access you want to your users’ GoCardless accounts - this may either be
read_write
orread_only
. redirect_
uri -
required The URL to send your users to once they’ve agreed to connect their account to GoCardless (as well if they deny authorisation or something goes wrong, in which case we’ll pass you details of the error). This must exactly match one of the
redirect_uris
stored on your app. state
- An optional string of your choice. Any value you pass in here will be included as a querystring parameter when we redirect back to your redirect URL. Please note that this value can be tampered with by your user, and so shouldn’t be trusted implicitly. We recommend using this parameter for a CSRF token.
prefill
[email] - Your user’s email address. We will pre-fill this on the login or signup forms to make it quicker and easier for them to complete the flow.
prefill
[given_ name] - Your user’s given (first) name. We will pre-fill this on the signup form.
prefill
[family_ name] - Your user’s family (last) name. We will pre-fill this on the signup form.
prefill
[organisation_ name] - The name of the user’s organisation (e.g. Acme Widget plc, 2nd Upminster Scout Group or Tim Rogers). We will pre-fill this on the signup form.
prefill
[country_ code] - The country code of the users’ organisation in ISO 3166-1 alpha-2 code format. We will pre-fill this on the signup form.
language
- The language that the login/signup form should be in, in ISO 639-1 format. If the language specified is supported, we will use it. Otherwise, we will fall back to the most appropriate available language for the user, based on factors like their browser settings and location.
initial_
view - An optional parameter, set to either
signup
orlogin
to specify which view we should show when your user enters the OAuth flow. By default, they will see the login view if you’re requestingread_only
access and the signup view if requestingread_write
.
GET https://connect.gocardless.com/oauth/authorize HTTP/1.1
response_type=code&
client_id=sx6WHUAVMUrinkJNJn8DotVFm&
scope=read_write&
redirect_uri=http%3A%2F%2Flocalhost%2Fcallback&
state=q8wEr9yMohTP&
prefill[email]=tim%40gocardless.com,
prefill[given_name]=Tim,
prefill[family_name]=Rogers,
prefill[organisation_name]=Tim%27s%20Fishing%20Store
prefill[country_code]=GB
Handling the redirect back to you
Once the user has connected their GoCardless account to your app, they’ll be redirected to your redirect_uri
.
In the querystring, you will be passed a code
, which you must exchange for a long-lived access token within 5 minutes. If you provided a state
in the original redirect to GoCardless, this will be passed back to you.
Errors
If the user denies your request to connect, or some other kind of error occurs (for example you specify an invalid scope
or response_type
is missing), the user will be redirected back to you with an error
and error_description
, per the OAuth spec.
error
will be set to one of the following, and there will be a human-readable error_description
which you may wish to store to refer to in case of errors:
invalid_
request - You failed to provide either a
scope
or aresponse_type
. invalid_
scope - You provided a
scope
other thanread_only
orread_write
. unsupported_
response_ type - You provided a
response_type
other thancode
. access_
denied - The user chose not to connect their account to your app.
GET https://localhost/callback HTTP/1.1
code=6NJiqXzT7HcgEGsAZXUmaBfB&
state=q8wEr9yMohTP
GET https://localhost/callback HTTP/1.1
error=access_denied&
error_description=The%20user%20cancelled%20the%20authorisation%20process.
Exchanging an authorisation code for an access token
Exchanges the authorisation code passed to you in the redirect for an access token which you may store and use to make future requests on the user’s behalf. Note that if the user has previously authorised with you, we will still generate a new access token and will disable any existing tokens for that user.
Relative endpoint: POST /oauth/access_token
Parameters
grant_
type -
required The kind of OAuth grant you’ve received - this will be
authorization_code
. code
-
required The authorisation code that resulted from the user agreeing to connect their account to your app, passed to you in the querystring as
code
. This will expire after 5 minutes, so you should exchange it for an access token immediately. redirect_
uri -
required One of the
redirect_uris
set on your app, and which you provided when sending your user to the OAuth flow. client_
id -
required The
client_id
for your registered app. client_
secret -
required The
client_secret
for your registered app.
Response
Following the OAuth spec, this endpoint responds with JSON including an access_token
if successful.
access_
token - Your permanent access token for authenticating on behalf of the user. You should store this for future use.
scope
- The
scope
of the access token, as originally requested (eitherread_write
orread_only
). token_
type - The type of token you’ve been issued - this will be
bearer
. organisation_
id - The ID of the GoCardless account to which you have been connected. You should store this for future use, as you will need it to identify to which of your users a webhook relates.
email
- A contact email for the GoCardless account to which you have been connected.
Errors
In case of an error, the endpoint responds with JSON including an error
and human-readable error_description
. error
may contain one of the following:
invalid_
request - You have not provided at least one of the required parameters (
grant_type
,code
,redirect_uri
,client_id
andclient_secret
), or one of your parameters is of the wrong type. unsupported_
grant_ type - You provided a
grant_type
other thanauthorization_code
. invalid_
client - The
client_id
andclient_secret
you provided to authenticate as your app were invalid or refer to a disabled app. invalid_
grant - The
code
you provided has already been used, has expired, or theredirect_uri
you provided does not match the one originally provided when passing the user to GoCardless.
POST https://connect.gocardless.com/oauth/access_token HTTP/1.1
grant_type=authorization_code&
code=6NJiqXzT7HcgEGsAZXUmaBfB&
redirect_uri=http%3A%2F%2Flocalhost%2Fcallback&
client_id=sx6WHUAVMUrinkJNJn8DotVFm&
client_secret=exaxerfrWrPdxADDUBWVqGbPbF
HTTP/1.1 200 (OK)
Content-Type: application/json
{
"access_token": "e72e16c7e42f292c6912e7710c123347ae178b4a",
"scope": "read_write",
"token_type": "bearer",
"email": "accounts@acme.com",
"organisation_id": "OR123"
}
POST https://connect.gocardless.com/oauth/access_token HTTP/1.1
grant_type=authorization_code&
code=goQcmyY8MebbAuKy8L&
redirect_uri=http%3A%2F%2Flocalhost%2Fcallback&
client_id=sx6WHUAVMUrinkJNJn8DotVFm&
client_secret=exaxerfrWrPdxADDUBWVqGbPbF
HTTP/1.1 400 (Bad Request)
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "code has already been used"
}
Making requests
You can now make standard API requests using the access token you received in exchange for the authorisation code. This will allow you to view and manipulate (depending on the scope
you requested) the user’s data.
As with elsewhere in the API, the access token must be provided in an Authorization
request header, using the bearer authentication scheme.
Authorization: Bearer e72e16c7e42f292c6912e7710c123347ae178b4a
Any errors generated by requests using your users’ access tokens will follow the usual structure of errors in the GoCardless API, as opposed to the OAuth-specific errors above.
If the access token provided is invalid, you will receive a 401 Unauthorized
response. The response body will include a reason, which will be either:
-
access_token_not_found
(the access token was not recognised); or -
access_token_revoked
(the user has revoked your access to their account); or -
access_token_not_active
(the access token is inactive for another reason)
Users will need to go through the authorisation flow again in order for you to obtain a new access token.
If you receive an unexpected 403 Forbidden
response for an endpoint your app is authorised to access (see below), this may indicate that your user’s account is under review. The user will have been informed by GoCardless that they need to provide additional information to re-enable their account.
Restricted: You will not be able to access the following API endpoints on behalf of organisations connected to your app:
- Creditor (create and update)
- Creditor Bank Account (all endpoints)
Unless your app’s payment pages that have been approved as scheme rules compliant by our sponsor bank you must use GoCardless’ hosted payment pages (via the Redirect Flow API). As such, the following endpoints will also be restricted by default:
- Mandate (create and reinstate)
- Customer (create)
- Customer bank account (create)
POST https://api.gocardless.com/customers/ HTTP/1.1
Authorization: Bearer e72e16c7e42f292c6912e7710c123347ae178b4a
HTTP/1.1 200 (OK)
GET https://api.gocardless.com/payments/ HTTP/1.1
Authorization: Bearer access_token_which_has_been_revoked
HTTP/1.1 401 (Unauthorized)
Content-Type: application/json
{
"error": {
"code": 401,
"type": "invalid_api_usage",
"errors": [
{
"message": "The access token you provided has been revoked",
"reason": "access_token_revoked"
}
],
"documentation_url": "https://developer.gocardless.com/api-reference/#access_token_revoked",
"message": "The access token you provided has been revoked",
"request_id": "dd50eaaf-8213-48fe-90d6-5466872efbc4"
}
}
Receiving webhooks
If you’ve provided a webhook URL for your app, we’ll notify you of new events relating to the GoCardless accounts of your users. For details on how webhooks work and how to process them, see the guide.
The events we send you will be identical to those described, but with an additional links[organisation]
attribute allowing you to identify which of your users a webhook relates to.
The organisation ID is provided when exchanging an authorisation code for an access token and when looking up an access token. If you expect to handle webhooks, you should store it for future reference.
POST https://example.com/webhooks HTTP/1.1
User-Agent: gocardless-webhook-service/1.1
Content-Type: application/json
Webhook-Signature: 86f8bb84a4de63cff4af48f22b64b20970b415b066e3d21459ea515052860514
{
"events": [
{
"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"
}
},
{
"id": "EV456",
"created_at": "2014-08-03T12:00:00.000Z",
"action": "failed",
"resource_type": "payments",
"links": {
"payment": "PM456",
"organisation": "OR456"
},
"details": {
"origin": "bank",
"cause": "mandate_cancelled",
"description": "Customer cancelled the mandate at their bank branch.",
"scheme": "bacs",
"reason_code": "ARUDD-1"
}
}
]
}
App Fees
If your OAuth app is creating payments on behalf of your users you may wish to add on a fee in addition to the fee that GoCardless charges.
When an OAuth app creates a payment or a subscription, it can specify an app_fee
. This is an amount in pence or cents that will be deducted from the amount that the user receives. A fee charged by an app must be no more than 50% of the total payment amount.
App fees will be collated in a payout and paid out. App fee payouts are created and paid out daily, as with other payouts.
POST https://api.gocardless.com/payments HTTP/1.1
Content-Type: application/json
{
"payments": {
"app_fee": 10,
"amount": 100,
"currency": "GBP",
"links": {
"mandate": "MD123"
}
}
}
POST https://api.gocardless.com/subscriptions HTTP/1.1
Content-Type: application/json
{
"subscriptions": {
"app_fee": 10,
"amount": 2500,
"currency": "GBP",
"name": "Monthly Magazine",
"interval_unit": "monthly",
"day_of_month": "1",
"links": {
"mandate": "MA123"
}
}
}
Looking up an access token
Using the API you can query an access token to check if it is valid, and if so, to find out more about it (for example if you’re not sure what scope the token has, or what organisation ID it relates to).
Relative endpoint: POST /oauth/introspect
Parameters
token
- required The access token you want to look up.
client_
id -
required The
client_id
for your registered app. client_
secret -
required The
client_secret
for your registered app.
Response
Following the OAuth token introspection spec, this endpoint responds with JSON as follows:
active
- A boolean representing whether the provided access token is a valid, active access token attached to your app
scope
- The
scope
of the access token, as originally requested (eitherread_write
orread_only
). Only returned if the token is active. token_
type - The type of token you’ve been issued - this will be
bearer
. Only returned if the token is active. organisation_
id - The ID of the GoCardless account which this token gives you access to. You should store this for future use, as you will need it to identify to which of your users a webhook relates. Only returned if the token is active.
email
- A contact email for the GoCardless account which this token gives you access to. Only returned if the token is active.
Errors
In case of an error, the endpoint responds with JSON including an error
and
human-readable error_description
. error
may contain one of the following:
invalid_
request - You have not provided at least one of the required parameters (
client_id
,client_secret
andtoken
), or one of your parameters is of the wrong type. invalid_
client - The
client_id
andclient_secret
you provided to authenticate as your app were invalid or refer to a disabled app.
POST https://connect.gocardless.com/oauth/introspect HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=jBo8XCUJLN01Mzya9vYS-7X5D&client_secret=hzBBiZTWnx8glPLwvJoVIJa1&token=live_y7VPTOdgFZtFaAS9V8HT3
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"scope": "read_write",
"token_type": "bearer",
"email": "accounts@acme.com",
"organisation_id": "OR123"
}
POST https://connect.gocardless.com/oauth/introspect HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=jBo8XCUJLN01Mzya9vYS-7X5D&client_secret=hzBBiZTWnx8glPLwvJoVIJa1&token=non_existent_or_inactive_token
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": false
}
Disconnecting a user from your app
If a user no longer wishes to use your app, they can revoke your access from their GoCardless Dashboard, or you can revoke (i.e. invalidate) their access token yourself using the API.
Relative endpoint: POST /oauth/revoke
Parameters
token
- required The access token you want to revoke.
client_
id -
required The
client_id
for your registered app. client_
secret -
required The
client_secret
for your registered app.
Response
Following the OAuth token revocation spec,
providing you successfully authenticate using your client_id
and client_secret
, this
API will always respond with a 200 OK
and no body, whether a token was successfully
revoked or not.
Errors
In case of an error, the endpoint responds with JSON including an error
and
human-readable error_description
. error
may contain one of the following:
invalid_
request - You have not provided at least one of the required parameters (
client_id
,client_secret
andtoken
), or one of your parameters is of the wrong type. invalid_
client - The
client_id
andclient_secret
you provided to authenticate as your app were invalid or refer to a disabled app.
POST https://connect.gocardless.com/oauth/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=jBo8XCUJLN01Mzya9vYS-7X5D&client_secret=hzBBiZTWnx8glPLwvJoVIJa1&token=live_y7VPTOdgFZtFaAS9V8HT3
HTTP/1.1 200 OK
Content-Length: 0
Compliance Requirements
When building a Direct Debit integration your payment pages and notifications need to comply with scheme-level rules. To help you design compliant pages quickly we have a series of guides:
Payment pages:
- ACH requirements (standard)
- ACH requirements (advanced)
- Autogiro requirements
- Bacs requirements
- BECS requirements
- BECS NZ requirements
- PAD requirements
- SEPA requirements
Customer notifications:
- ACH requirements
- Autogiro requirements
- Bacs requirements
- BECS requirements
- BECS NZ requirements
- PAD requirements
- SEPA requirements
Before your account can be set to “live” our sponsor bank will need to sign off your compliance in the above areas.
Alternatively, you may wish to use the Redirect Flow API,
which enables you to use payment pages hosted by GoCardless, and / or to have
GoCardless send compliant, generic notification emails on your behalf.
You can see our hosted payment pages and an example of the emails we send by
testing out the payment flow here.
Local Bank Details
Creditor bank accounts, customer bank accounts, and customer bank account tokens can all be created with local or international bank details. This section lists the different local bank detail formats, and how they should be used with the GoCardless API.
IBAN
When supplying an IBAN (international bank account number), the country_code
field is
optional, but must match the country code of the IBAN (its first two characters) if
supplied.
If currency
is not supplied we use the default currency based on the
provided or derived country_code
. For example if the IBAN of an account
begins with GB
but you want to collect Euros from the account using SEPA you
must specify the currency
as EUR
.
IBANs are not supported for Australian bank accounts denominated in AUD and Swedish bank accounts denominated in SEK - you must supply local bank details.
{
"customer_bank_accounts": {
"iban": "GB60 BARC 2000 0055 7799 11",
...
}
}
UK
For the UK, a 6-8 digit account_number
and a 6 digit branch_code
(sort code)
should be supplied.
{
"customer_bank_accounts": {
"country_code": "GB",
"account_number": "55779911",
"branch_code": "200000",
...
}
}
Australia
For Australia, an account_number
and a branch_code
(BSB number)
should be supplied. The account number is 5-9 digits, and the BSB number is 6 digits.
IBANs are not supported for Australian bank accounts denominated in AUD - you must supply local bank details.
{
"customer_bank_accounts": {
"country_code": "AU",
"account_number": "0123456789",
"branch_code": "012345",
...
}
}
Austria
For Austria, an account_number
(Kontonummer, Kto.) and bank_code
(Bankleitzahl, BLZ)
should be supplied. The Kontonummer is 4-11 digits, and the Bankleitzahl is 5 digits.
{
"customer_bank_accounts": {
"country_code": "AT",
"account_number": "234573201",
"bank_code": "19043",
...
}
}
Belgium
For Belgium, only an account_number
(Rekeningnummer/Numéro de compte) should be
supplied. The first three digits of this are a bank identifier, but are usually considered
part of the account number.
{
"customer_bank_accounts": {
"country_code": "BE",
"account_number": "539-0075470-34",
...
}
}
Canada
For Canada, use a 2-3 digit bank_code
(Financial Institution number), a 5
digit branch_code
(Branch Transit number) and a 7-12 digit account_number
.
{
"customer_bank_accounts": {
"country_code": "CA",
"account_number": "1234567",
"bank_code": "0003",
"branch_code": "00006",
...
}
}
Cyprus
For Cyprus, a 3 digit bank_code
(Kodikos Trapezas) and 7-16 digit account_number
(Arithmos Logariasmou) must be supplied, and a 5 digit branch_code
(Kodikos Katastimatos)
can also be supplied.
The bank and branch code (Kodikos Trapezas and Kodikos Katastimatos) are frequently
supplied together as a single number, so it is also allowed to supply just an 8-digit
bank_code
containing both the Kodikos Trapezas and the Kodikos Katastimatos.
{
"customer_bank_accounts": {
"country_code": "CY",
"account_number": "1200527600",
"bank_code": "002",
"branch_code": "00128",
...
}
}
Denmark
For Denmark, a 2-4 digit bank_code
(registreringsnummer) and a 9-10 digit
account_number
(kontonummer) must be supplied.
Alternatively, the bank code and branch code can be provided as part of the
account_number
field separated by a -
(e.g. 123-123-1234
), or a
13-14-digit account_number
(including bank code) can be provided where values
are separated by a space (e.g. 1234 1234567890
).
{
"customer_bank_accounts": {
"country_code": "DK",
"account_number": "3179681",
"bank_code": "345",
...
}
}
Estonia
All local account numbers were replaced with IBANs in February 2014, however some payers
may prefer using the old account numbers. These are up to 14 digits, and can be supplied
as the account_number
.
{
"customer_bank_accounts": {
"country_code": "EE",
"account_number": "221020145685",
...
}
}
Finland
As of August 2014, Finnish banks are required to use IBANs rather than the old “tilinumeron
rakenne”, however GoCardless still supports the older format. This is a 6 digit bank_code
,
and up to 8 digit account_number
.
The Åland Islands use the same banking details as Finland, and can be submitted
using their ISO 3166-1 country code AX
.
{
"customer_bank_accounts": {
"country_code": "FI",
"account_number": "456",
"bank_code": "500015",
...
}
}
France
There are four parts to French bank details:
- Code banque: 5 digit
bank_code
- Code guichet: 5 digit
branch_code
- Numéro de compte: up to 11 digit account number
- Clé RIB: 2 check digits
The check digits are frequently written at the end of the account number, and this is how
they should be included in the account_number
field.
French DOMs and TOMs use the same details as above, and can be submitted using their ISO 3166-1 country codes:
- French Guiana:
GF
- Guadeloupe:
GP
- Martinique:
MQ
- Mayotte:
YT
- Réunion:
RE
- Saint Barthélemy:
BL
- Saint Martin (French part):
MF
- Saint Pierre and Miquelon:
PM
{
"customer_bank_accounts": {
"country_code": "FR",
"account_number": "0500013M026 06",
"bank_code": "20041",
"branch_code": "01005",
...
}
}
Germany
For Germany, a 1-10 digit account_number
(Kontonummer) and 8 digit bank_code
(Bankleitzahl) are required.
{
"customer_bank_accounts": {
"country_code": "DE",
"account_number": "532013000",
"bank_code": "37040044",
...
}
}
Greece
In Greece most customers know their IBANs, but GoCardless also supports passing
full local bank details. If local bank details are provided, a 3 digit bank_code
(Kodikos Trapezas), a 5 digit branch_code
(Kodikos Katastimatos), and a 16 digit
account_number
(Arithmos Logariasmou) must be supplied.
{
"customer_bank_accounts": {
"country_code": "GR",
"account_number": "0000000012300695",
"bank_code": "011",
"branch_code": "0125",
...
}
}
Ireland
Ireland uses a 6-digit branch_code
(sort code), and 6-8 digit account_number
.
{
"customer_bank_accounts": {
"country_code": "IE",
"account_number": "29823529",
"branch_code": "90-21-27",
...
}
}
Italy
Most Italian payers will be familiar with the IBAN format in addition to the local format, and more correctness checks can be applied to the IBAN, so it is recommended to ask users to input their IBAN rather than local details. However, it is possible to use:
- Codice ABI: 5 digit
bank_code
- CAB: 5 digit
branch_code
- Numero di conto: up to 12 digit
account_number
{
"customer_bank_accounts": {
"country_code": "IT",
"account_number": "123456",
"bank_code": "05428",
"branch_code": "11101",
...
}
}
Latvia
Latvia replaced bank details with IBANs in 2005, so most Latvian payers are unlikely to
know their bank code and account number, however GoCardless continues to accept them. The
bank_code
should be 4 characters, and the account_number
should be 13 digits.
{
"customer_bank_accounts": {
"country_code": "LV",
"account_number": "0000435195001",
"bank_code": "LACB",
...
}
}
Lithuania
Lithuania replaced bank details with IBANs in 2004, so most Lithuanian payers are unlikely
to know their bank code and account number, however GoCardless continues to accept them.
The bank_code
should be 5 digits, and the account_number
should be 11 digits.
{
"customer_bank_accounts": {
"country_code": "LT",
"account_number": "11101001000",
"bank_code": "10000",
...
}
}
Luxembourg
Luxembourg replaced bank details with IBANs in 2002, so most Luxembourgian payers are
unlikely to know their bank code and account number, however GoCardless continues to
accept them. The bank_code
should be 3 digits, and the account_number
should be 13
digits.
{
"customer_bank_accounts": {
"country_code": "LU",
"account_number": "9400644750000",
"bank_code": "001",
...
}
}
Malta
Malta uses a 5-digit branch_code
(sort code) and an up to 18-digit
account_number
(numru tal‑kont bankarju).
{
"customer_bank_accounts": {
"country_code": "MT",
"account_number": "9027293051",
"branch_code": "44093",
...
}
}
Monaco
Monaco uses the same local bank details as France. That is:
- Code banque: 5 digit
bank_code
- Code guichet: 5 digit
branch_code
- Numéro de compte: up to 11 digit account number
- Clé RIB: 2 check digits
The check digits are frequently written at the end of the account number, and this is how
they should be included in the account_number
field.
{
"customer_bank_accounts": {
"country_code": "MC",
"account_number": "0500013M026 06",
"bank_code": "20041",
"branch_code": "01005",
...
}
}
Netherlands
The Netherlands have replaced local bank details with IBANs, so most Dutch
payers are unlikely to know their bank code and Rekeningnummer, however
GoCardless continues to accept them. The bank_code
should be 4 characters, and
the account_number
(Rekeningnummer) up to 10 digits.
{
"customer_bank_accounts": {
"country_code": "NL",
"account_number": "0417164300",
"bank_code": "ABNA",
...
}
}
New Zealand
New Zealand bank details have 4 components:
- Bank Number: 2 digit
bank_code
- Branch Number: 4 digit
branch_code
- Account Number: 7 digits
- Account Suffix: 2/3 digits
The account number and account suffix should be concatenated with a -
for the account_number
field.
IBANs are not supported for New Zealand bank accounts denominated in NZD - you must supply local bank details.
{
"customer_bank_accounts": {
"country_code": "NZ",
"account_number": "0123456-89",
"branch_code": "0123",
"bank_code": "01",
...
}
}
Portugal
Portuguese bank details have 4 components:
- Código de Banco: 4 digit
bank_code
- Código de Balcão: 4 digit
branch_code
- Número de conta: 11 digit account number
- Dígitos de controlo: 2 check digits
The account number and check digits should be concatenated for the account_number
field.
{
"customer_bank_accounts": {
"country_code": "PT",
"account_number": "1234567890154 50",
"bank_code": "0002",
"branch_code": "0123",
...
}
}
San Marino
San Marino uses the same bank details formats as Italy. As with Italy, payers will be familiar with the IBAN format in addition to the local format, and more correctness checks can be applied to the IBAN, so it is recommended to ask users to input their IBAN rather than local details. However, it is possible to use:
- Codice ABI: 5 digit
bank_code
- CAB: 5 digit
branch_code
- Numero di conto: up to 12 digit
account_number
{
"customer_bank_accounts": {
"country_code": "SM",
"account_number": "123456",
"bank_code": "05428",
"branch_code": "11101",
...
}
}
Slovak Republic
There are three parts to Slovak bank details:
- Předčíslí: up to 6 digit account number prefix
- Číslo účtu: up to 8 digit account number
- Kód banky: 4 digit bank code
These are often written as pppppp-aaaaaaaaaa/bbbb. When creating a bank account using
Slovak bank details, the předčíslí and číslo účtu should be concatenated for the
account_number
field, and the kód banky should be used for the bank_code
field.
{
"customer_bank_accounts": {
"country_code": "SK",
"account_number": "198742637541",
"bank_code": "1200",
...
}
}
Slovenia
Slovenia uses a 5 digit bank_code
and up to 10 digit account_number
.
{
"customer_bank_accounts": {
"country_code": "SI",
"account_number": "123438",
"bank_code": "19100",
...
}
}
Spain
There are four parts to Spanish bank details, the 4 digit código de entidad (bank code), 4 digit código de oficina (branch code), 2 dígitos de control (check digits), and 10 digit número de cuenta.
These can either be supplied as separate bank_code
, branch_code
, and account_number
(with the check digits at the start of the account number), or all in the account_number
field. In the latter case, this is known locally as the Código Cuenta Cliente.
{
"customer_bank_accounts": {
"country_code": "ES",
"account_number": "45 0200051332",
"bank_code": "2100",
"branch_code": "0418",
...
}
}
Sweden
Sweden uses a 4- or 5-digit branch_code
(clearingnummer), and up to 10-digit account_number
(kontonummer).
IBANs are not supported for Swedish bank accounts denominated in SEK - you must supply local bank details.
{
"customer_bank_accounts": {
"country_code": "SE",
"account_number": "1234512",
"branch_code": "5527"
...
}
}
United States
United States uses a 9-digit bank_code
(routing number), and up to 17-digit account_number
(account number). Additionally, account_type
must be provided (either checking
or savings
).
IBANs are not supported for American bank accounts denominated in USD - you must supply local bank details.
{
"customer_bank_accounts": {
"country_code": "US",
"account_number": "2715500356",
"bank_code": "026073150",
"account_type": "checking",
...
}
}
Character Sets
Different schemes allow different sets of characters to be used in payment and mandate references. All schemes allow alphanumeric characters (A-Z, 0-9) and some also allow a selection of special characters (subject to change). Any references provided to us containing characters not permitted by the scheme will cause an error, we will include the characters that caused the error in the message.
The exact way that references are displayed also varies by bank (e.g. some truncate references, some do not show them at all). GoCardless will always format payment and mandate references to appear as accurately as possible for the given bank and scheme.
Public Certificate Policy
GoCardless forces HTTPS for all services, using TLS. Our client libraries also use TLS and verify the certificates to ensure security.
Currently our certificates are provided by Google (Google GTS Root R1 CA
).
This can be verified using the openssl
library:
$ openssl s_client -connect api.gocardless.com:443 <<< ""
CONNECTED(00000005)
depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1
verify return:1
depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1P5
verify return:1
depth=0 CN = api.gocardless.com
verify return:1
---
Certificate chain
0 s:CN = api.gocardless.com
i:C = US, O = Google Trust Services LLC, CN = GTS CA 1P5
a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
v:NotBefore: Jun 15 13:55:41 2023 GMT; NotAfter: Sep 13 13:55:40 2023 GMT
1 s:C = US, O = Google Trust Services LLC, CN = GTS CA 1P5
i:C = US, O = Google Trust Services LLC, CN = GTS Root R1
a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
v:NotBefore: Aug 13 00:00:42 2020 GMT; NotAfter: Sep 30 00:00:42 2027 GMT
2 s:C = US, O = Google Trust Services LLC, CN = GTS Root R1
i:C = BE, O = GlobalSign nv-sa, OU = Root CA, CN = GlobalSign Root CA
a:PKEY: rsaEncryption, 4096 (bit); sigalg: RSA-SHA256
v:NotBefore: Jun 19 00:00:42 2020 GMT; NotAfter: Jan 28 00:00:42 2028 GMT
---
Our client libraries currently don’t offer any form of certificate pinning, and we don’t intend to support this feature in the future. We reserve the right to change our Certificate Authority (CA), which will break your integration if you’ve implemented certificate pinning..
For any future changes to the API certificate authority, we will place a scheduled maintenance notice on our status page, with at least 2 weeks advance warning. If your integration does depend on a specific TLS chain of trust, then we advise that you subscribe to updates on this page.
Approving our IP Addresses
Please be aware that adding our IPv4 addresses to an approved list is not a supported scenario for using our API. The IP address may change as part of our normal operations and should not be relied upon to remain static. This is inline with best practices for highly-available services.
As a result we recommend that you do not add our IPv4 addresses to your approved lists in the future.
Approving our IP addresses for receiving webhooks is still a valid practice. Please visit the webhooks appendix for more details.
Alternative to IP approved lists
We recommend relying on the stronger security provided by Transport Layer Security (TLS). This should be used to validate our identity whilst communicating with our API as part of the normal checking of certificates. Please note that certificate revocation should also be checked for all parts of the certificate chain in the certificate we provide you.
For more information on how to implement this change, or for help with any questions, please contact our team on api@gocardless.com.
Tax Rates
GoCardless has been instructed by the relevant authorities to charge tax on its fees.
GoCardless currently applies tax to transaction and surcharge fees for merchants operating in the UK and France.
Who does this impact?
At this time, this change will impact any creditors who have a country_code
of “GB” or “FR”. It is possible that we may have to start charging VAT (or equivalent) in other areas that we operate in the future.
In the onboarding flow we request that creditor to select the appropriate jurisdiction for their country, which we use to apply the correct tax to the merchant.
Best practices for integrating
For best practices see our partner guides for handling tax.
Definitions of jurisdiction
jurisdiction
for countries or overseas territories will be an ISO 3166-1 alpha-2 code, e.g FR
for France & GP
for Guadeloupe
For areas with unique tax rates that do not have ISO-3166-1 codes, we will use the ISO 3166-2 subdivision codes for that country. e.g Corsica is FR-COR
.
Tax Tables
Tax for British territories
id | jurisdiction | type | description | percentage |
---|---|---|---|---|
GB_ |
GB | VAT | VAT for Mainland Great Britain | 20 |
JE_ |
JE | GST | GST for Jersey | 0 |
GI_ |
GI | VAT | VAT for Gibraltar | 0 |
GG_ |
GG | VAT | VAT for Guernsey | 0 |
Tax for French territories
id | jurisdiction | type | description | percentage |
---|---|---|---|---|
FR_ |
FR | VAT | VAT for Mainland France | 20 |
GP_ |
GP | VAT | VAT for Guadeloupe | 8.5 |
MQ_ |
MQ | VAT | VAT for Martinique | 8.5 |
RE_ |
RE | VAT | VAT for Reunion Island | 8.5 |
FR-COR_ |
FR-COR | VAT | VAT for Corsica | 20 |
The ids for tax rates are shared between the environments.
Security Requirements
Updated Bank Details
There are certain security requirements which apply to GoCardless when providing the Updated Bank Details feature, and to you (the user) when using the Updated Bank Details feature.
GoCardless’ responsibilities:
- Implement procedures and technical controls that ensure secure storage and transmission of personal data using industry-standard encryption mechanisms and strong cipher suites
- Implement technical controls to ensure that any data sent to, and received from, intended recipients is protected against eavesdropping, modification and loss in transit
- Apply access controls to ensure that only Authorised Users gain access to information systems that process and store key material
- Maintain and monitor audit logs on the use of the Updated Bank Details feature
- Have policies and procedures to detect and respond to security incidents, including procedures to monitor systems, mitigate effects, and document incidents and their outcomes
- Maintain Developer Documentation concerning the use, creation, management and revocation of encryption keys, access tokens and digital certificates
- Keep a backup of encryption key material and related business-critical data and have appropriate recovery and continuity procedures
Your responsibilities:
- Implement and maintain procedures and technical controls to ensure that only Authorised Users access systems that are used to manage and store key material that is shared with GoCardless
- Manage key material by implementing the creation, storage, rotation, revocation and disposal requirements set in GoCardless’ Developer Documentation
- Generate RSA keys at least 2048-bit in length with SHA256
- Rotate keys at least annually
- Use industry-standard encryption mechanisms to transmit and store encryption data used in the Updated Bank Details feature and GoCardless’ services
- Establish and maintain procedures to back up your key material, detect when backup failures occur, and take corrective action for recovery as required