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
- 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.
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.
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 or standing for ACH scheme. And single, recurring and sporadic for PAD scheme.
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.
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
-
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
[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.
Create a Billing Request
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.
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. -
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. 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
. 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("