GoCardless
Number of APIs: 173
Documentation for how to use this collection, including a Quickstart guide, is available on the GoCardless Developer Docs. Detailed documentation for GoCardless API endpoints is at the GoCardless API reference guide. Before you begin, set up your free GoCardless Sandbox account. Here, you can create an access token to add to your forked Qodex collection. 1. Create a GoCardless Sandbox account here: the sandbox is our dedicated testing environment where you can build and test your integration without touching real money. 2. Go to Developers > Create > Access Token to generate an API access token. Give it a memorable name, with read-write access. 3. [Fork] the collection into Qodex to synchronize with future updates. 4. Set up a [Qodex Environment] for the GoCardless API collection by navigating to Environments and selecting the + icon to create a new environment. 5. Navigate to an API call you'd like to test to save your key into the collection:š Introduction
š Prerequisites
š Getting Started
Authorization
Save authorization to collection
with the linkThings to Note
1. š Getting Started-Step 1 - Taking a first instant payment with mandate set up - Initiate your Billing Request
POST {{url}}/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: Instant First Payment + Direct Debit mandate creation for how-toās, explanations and tutorials.
2. š Getting Started-Step 1 - Taking a first instant payment with mandate set up - Create a Billing Request Flow
POST {{url}}/billing_request_flows
Creates a new billing request flow.
3. š Getting Started-Step 2 - Collecting payments against a mandate - Retrieve a fulfilled Billing Request
GET {{url}}/billing_requests/{{billing_request}}
Retrieves the details of a single billing request.
4. š Getting Started-Step 2 - Collecting payments against a mandate - Create a Direct Debit Payment
POST {{url}}/payments
Creates a new payment object.
This fails with a mandateisinactive error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pendingcustomerapproval, pending_submission, submitted, and active.
5. š Getting Started-Step 3 - Monitor Webhooks - List Events
GET {{url}}/events
Returns a cursor-paginated list of your events.
6. š Getting Started-Next steps-Explore global payment journeys - š¦šŗ PayTo Mandate
POST {{url}}/billing_requests
PayTo is a new, efficient way to initiate real-time payments from customersā bank accounts in Australia. GoCardless has implemented PayTo within Billing Requests to enable two key payments use cases:
- Setting up an open mandate with your customer
- Taking one-off real-time payments
A note on definitions: PayTo uses the term āagreementā to refer to the contract between the GoCardless customer and the end-customer. This concept matches that of the āmandateā so, for consistency, we use this term in the API and documentation instead. Please be aware that the terms are synonymous and that the end-customer will see the term āagreementā in the payment flow.
Constraints
start_date- the date from which the consent will be valid. It will be shown to a payer to confirm and hence should be considered in the payer timezone. This date cannot be older than the date when the payer authorises the consent. Therefore if you want to specify it, make sure that it is not in the past and that the payer has enough time to complete the flow before the date will come.end_date- the date after which we will not be able to collect payments, as the consent stops being valid. It will be shown to a payer to confirm and hence should be considered in the payer timezone. This date cannot be in the past or older than the start date.max_amount_per_payment- maximum amount that can be charged for a single payment.periodic_limits- frequency configurationperiod- repeating time frame presented asyear
,month
,week
orday
.max_total_amount- maximum total amount that can be charged for all payments in the period.max_payments- maximum amount of payments that can be taken within a periodalignment- Specifies whether the period starts when the mandate is created or lines up with a calendar date. When the period alignment is calendar based, the first payment is pro-rated to the number of remaining days from the start of the period. By default, this is set to mandatecreation_date.
See Billing Requests: PayTo Agreements and Payments for how-toās, explanations and tutorials.
7. š Getting Started-Next steps-Custom Payment Pages-Direct Debit - Create a Billing Request (Mandate)
POST {{url}}/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.
8. š Getting Started-Next steps-Custom Payment Pages-Direct Debit - Collect Customer Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_customer_details
If the billing request has a pending collectcustomerdetails 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.
Note: the region field should be uncommented for US customer addresses.
9. š Getting Started-Next steps-Custom Payment Pages-Direct Debit - Collect Bank Account Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_bank_account
If the billing request has a pending collectbankaccount 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.
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
10. š Getting Started-Next steps-Custom Payment Pages-Direct Debit - Confirm Customer & Bank Account Details
POST {{url}}/billing_requests/{{billing_request}}/actions/confirm_payer_details
This is needed when you have mandate_request. As a scheme compliance rule we are required to allow the payer to crosscheck the details entered by them and confirm it.
11. š Getting Started-Next steps-Custom Payment Pages-Direct Debit - Fulfill a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/fulfil
If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment.
12. š Getting Started-Next steps-Custom Payment Pages-Direct Debit - Create a Payment
POST {{url}}/payments
Creates a new payment object.
This fails with a mandateisinactive error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pendingcustomerapproval, pending_submission, submitted, and active.
13. š Getting Started-Next steps-Custom Payment Pages-Open Banking - Instant Bank Pay - Create an Instant Payment Billing Request
POST {{url}}/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 Request (Instant Bank Pay feature) for how-toās, explanations and tutorials.
14. š Getting Started-Next steps-Custom Payment Pages-Open Banking - Instant Bank Pay - Collect Customer Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_customer_details
If the billing request has a pending collectcustomerdetails 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.
Note: the region field should be uncommented for US customer addresses.
15. š Getting Started-Next steps-Custom Payment Pages-Open Banking - Instant Bank Pay - List Institutions for Billing Request
GET {{url}}/billing_requests/{{billing_request}}/institutions?country_code=GB
Returns all institutions valid for a Billing Request.
This endpoint is currently supported only for FasterPayments.
16. š Getting Started-Next steps-Custom Payment Pages-Open Banking - Instant Bank Pay - Select Institution for a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/select_institution
Creates an Institution object and attaches it to the Billing Request
17. š Getting Started-Next steps-Custom Payment Pages-Open Banking - Instant Bank Pay - Create a Bank Authorisation
POST {{url}}/bank_authorisations
Create a Bank Authorisation.
18. š Getting Started-Next steps-Custom Payment Pages-Open Banking - Instant Bank Pay - Get a Billing Request
GET {{url}}/billing_requests/{{billing_request}}
Retrieves the details of a single billing request.
19. Billing Requests-Billing Requests-Billing Request Examples - PayTo Mandate and Payment
POST {{url}}/billing_requests
PayTo is a new, efficient way to initiate real-time payments from customersā bank accounts in Australia. GoCardless has implemented PayTo within Billing Requests to enable two key payments use cases:
- Setting up an open mandate with your customer
- Taking one-off real-time payments
A note on definitions: PayTo uses the term āagreementā to refer to the contract between the GoCardless customer and the end-customer. This concept matches that of the āmandateā so, for consistency, we use this term in the API and documentation instead. Please be aware that the terms are synonymous and that the end-customer will see the term āagreementā in the payment flow.
Constraints
start_date- the date from which the consent will be valid. It will be shown to a payer to confirm and hence should be considered in the payer timezone. This date cannot be older than the date when the payer authorises the consent. Therefore if you want to specify it, make sure that it is not in the past and that the payer has enough time to complete the flow before the date will come.end_date- the date after which we will not be able to collect payments, as the consent stops being valid. It will be shown to a payer to confirm and hence should be considered in the payer timezone. This date cannot be in the past or older than the start date.max_amount_per_payment- maximum amount that can be charged for a single payment.periodic_limits- frequency configurationperiod- repeating time frame presented asyear
,month
,week
orday
.max_total_amount- maximum total amount that can be charged for all payments in the period.max_payments- maximum amount of payments that can be taken within a periodalignment- Specifies whether the period starts when the mandate is created or lines up with a calendar date. When the period alignment is calendar based, the first payment is pro-rated to the number of remaining days from the start of the period. By default, this is set to mandatecreation_date.
See Billing Requests: PayTo Agreements and Payments for how-toās, explanations and tutorials.
20. Billing Requests-Billing Requests - Create a Billing Request
POST {{url}}/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.
21. Billing Requests-Billing Requests - Collect Customer Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_customer_details
If the billing request has a pending collectcustomerdetails 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.
Note: the region field should be uncommented for US customer addresses.
22. Billing Requests-Billing Requests - Collect Bank Account Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_bank_account
If the billing request has a pending collectbankaccount 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.
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
23. Billing Requests-Billing Requests - Confirm Customer & Bank Account Details
POST {{url}}/billing_requests/{{billing_request}}/actions/confirm_payer_details
If the billing request has a pending collectbankaccount 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.
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
24. Billing Requests-Billing Requests - Select Institution for a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/select_institution
Creates an Institution object and attaches it to the Billing Request
25. Billing Requests-Billing Requests - Fulfill a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/fulfil
If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment.
26. Billing Requests-Billing Requests - Cancel a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/cancel
Immediately cancels a billing request, causing all billing request flows to expire.
27. Billing Requests-Billing Requests - Trigger Fallback
POST {{url}}/billing_requests/{{billing_request}}/actions/fallback
Triggers a fallback from the open-banking flow to direct debit. Note, the billing request must have fallback enabled.
28. Billing Requests-Billing Requests - Change Currency for a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/choose_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, it will not support payments requests or plans
29. Billing Requests-Billing Requests - Notify Customer of Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/notify
Notifies the customer linked to the billing request, asking them to authorise it. Currently, the customer can only be notified by email.
30. Billing Requests-Billing Requests - List Billing Requests
GET {{url}}/billing_requests
Returns a cursor-paginated list of your billing_requests.
31. Billing Requests-Billing Requests - Get a Billing Request
GET {{url}}/billing_requests/{{billing_request}}
Retrieves the details of a single billing request.
32. Billing Requests-Billing Request Flows - Create a Billing Request Flow
POST {{url}}/billing_request_flows
Creates a new billing request flow.
33. Billing Requests-Billing Request Flows - Initialise a Billing Request Flow
POST {{url}}/billing_request_flows/{{billing_request_flow}}/actions/initialise
Returns the flow having generated a fresh session token which can be used to power integrations that manipulate the flow.
34. Billing Requests-Bank Authorisations - Create a Bank Authorisation
POST {{url}}/bank_authorisations
Create a Bank Authorisation.
35. Billing Requests-Bank Authorisations - Get Bank Authorisation
GET {{url}}/bank_authorisations/{{bank_authorisation}}
Fetches a bank authorisation.
36. Billing Requests-Billing Request Templates - Create a Billing Request Template
POST {{url}}/billing_request_templates
37. Billing Requests-Billing Request Templates - Update a Billing Request Template
PUT {{url}}/billing_request_templates/{{billing_request_template}}
38. Billing Requests-Billing Request Templates - Get a Billing Request Template
GET {{url}}/billing_request_templates/{{billing_request_template}}
39. Billing Requests-Billing Request Templates - List Billing Request Templates
GET {{url}}/billing_request_templates
40. Billing Requests-Institutions - List Institutions for Billing Request
GET {{url}}/billing_requests/{{billing_request}}/institutions?country_code=GB
Returns all institutions valid for a Billing Request.
This endpoint is currently supported only for FasterPayments.
41. Core Endpoints-Block - Create a Block
POST {{url}}/blocks
Creates a new Block of a given type. By default it will be active.
42. Core Endpoints-Block - Create Blocks by Reference
POST {{url}}/blocks/block_by_ref
Retrieves the details of an existing block.
43. Core Endpoints-Block - Disable a Block
POST {{url}}/blocks/{{block}}/actions/disable
Disables a block so that it no longer will prevent mandate creation.
https://developer.gocardless.com/api-reference/#blocks-disable-a-block
44. Core Endpoints-Block - Enable a Block
POST {{url}}/blocks/{{block}}/actions/enable
Enables a previously disabled block so that it will prevent mandate creation
https://developer.gocardless.com/api-reference/#blocks-enable-a-block
45. Core Endpoints-Block - Get a Block
GET {{url}}/blocks/{{block}}
Retrieves the details of an existing block.
https://developer.gocardless.com/api-reference/#blocks-get-a-single-block
46. Core Endpoints-Block - List Blocks
GET {{url}}/blocks
Returns a cursor-paginated list of your blocks.
https://developer.gocardless.com/api-reference/#blocks-list-multiple-blocks
47. Core Endpoints-Creditors - Create a Creditor
POST {{url}}/creditors
Creates a new creditor.
Restricted: This endpoint is restricted to customers using the GoCardless Embed product. Partners should instead manage multiple merchant accounts by building aĀ partner integration.
48. Core Endpoints-Creditors - Update a Creditor
PUT {{url}}/creditors/{{creditor}}
Updates a creditor object. Supports all of the fields supported when creating a creditor.
Update a Creditor API Docs
49. Core Endpoints-Creditors - List Creditors
GET {{url}}/creditors
Returns a cursor-paginated list of your creditors.
List Creditors API Docs
50. Core Endpoints-Creditors - Get a single Creditor
GET {{url}}/creditors/{{creditor}}
Retrieves the details of an existing creditor.
List Creditors API Docs
51. Core Endpoints-Customer Bank Accounts - Create a Customer Bank Account
POST {{url}}/customer_bank_accounts
Please consider using the Billing Requests API instead of Customer Bank Accounts for any future integrations.
Creates a new customer bank account object.
There are three different ways to supply bank account details:
- Local details
- IBAN
- Customer Bank Account Tokens
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
52. Core Endpoints-Customer Bank Accounts - Update a Customer Bank Account
PUT {{url}}/customer_bank_accounts/{{customer_bank_acct}}
Updates a customer bank account object. Only the metadata parameter is allowed.
53. Core Endpoints-Customer Bank Accounts - List Customer Bank Accounts
GET {{url}}/customer_bank_accounts
Returns a cursor-paginated list of your bank accounts.
54. Core Endpoints-Customer Bank Accounts - Get a single Customer Bank Account
GET {{url}}/customer_bank_accounts/{{customer_bank_acct}}
Retrieves the details of an existing bank account.
55. Core Endpoints-Customer Bank Accounts - Disable a Customer Bank Account
POST {{url}}/customer_bank_accounts/{{customer_bank_acct}}/actions/disable
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.
56. Core Endpoints-Currency Exchange Rates - List Currency Exchange
GET {{url}}/currency_exchange_rates?source=GBP&target=EUR
Returns a cursor-paginated list of all exchange rates from our foreign exchange provider.
57. Core Endpoints-Customers - Create a Customer
POST {{url}}/customers
Please consider using the Billing Requests API instead of Customers for any future integrations.
Creates a new customer object.
Note: the region field should be uncommented for US customer addresses.
58. Core Endpoints-Customers - Update a Customer
PUT {{url}}/customers/{{customer}}
Updates a customer object. Supports all of the fields supported when creating a customer.
59. Core Endpoints-Customers - List Customers
GET {{url}}/customers
Returns a cursor-paginated list of your customers.
60. Core Endpoints-Customers - Get a single Customer
GET {{url}}/customers/{{customer}}
Retrieves the details of an existing customer.
61. Core Endpoints-Customers - Remove a Customer
DELETE {{url}}/customers/{{customer}}
Please consider using Billing Requests to build any future integrations.
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.
62. Core Endpoints-Creditors Bank Accounts - Create a Creditor Bank Account
POST {{url}}/creditor_bank_accounts
Creates a new creditor bank account object.
Note: Creditor bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
63. Core Endpoints-Creditors Bank Accounts - List Creditor Bank Accounts
GET {{url}}/creditor_bank_accounts
Returns a cursor-paginated list of your creditor bank accounts.
64. Core Endpoints-Creditors Bank Accounts - Get a single Creditor Bank Account
GET {{url}}/creditor_bank_accounts/{{creditor_bank_account}}
Retrieves the details of an existing creditor bank account.
65. Core Endpoints-Creditors Bank Accounts - Disable a Creditor Bank Account
POST {{url}}/creditor_bank_accounts/{{creditor_bank_account}}/actions/disable
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.
66. Core Endpoints-Customer Notifications - Handle a notification
POST {{url}}/customer_notifications/{{customer_notification}}/actions/handle
ā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.
67. Core Endpoints-Events - List Events
GET {{url}}/events
Returns a cursor-paginated list of your events.
68. Core Endpoints-Events - Get a single Event
GET {{url}}/events/{{event}}
Retrieves the details of a single event.
69. Core Endpoints-Instalment Schedules - Create Instalment Schedules (with schedule)
POST {{url}}/instalment_schedules
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.
70. Core Endpoints-Instalment Schedules - List Instalment Schedules
GET {{url}}/instalment_schedules
Returns a cursor-paginated list of your instalment schedules.
71. Core Endpoints-Instalment Schedules - Get a Single Instalment Schedules
GET {{url}}/instalment_schedules/{{instalment_schedule}}
Retrieves the details of an existing instalment schedule.
72. Core Endpoints-Instalment Schedules - Update an Instalment Schedule
PUT {{url}}/instalment_schedules/{{instalment_schedule}}
Updates an instalment schedule. This accepts only the metadata parameter.
73. Core Endpoints-Instalment Schedules - Cancel an Instalment Schedule
POST {{url}}/instalment_schedules/{{instalment_schedule}}/actions/cancel
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.
74. Core Endpoints-Mandates - Create a Mandate
POST {{url}}/mandates
Please consider using the Billing Requests API instead of Mandates for any future integrations.
Creates a new mandate object.
Restricted: this endpoint is restricted to GoCardless Pro and GoCardless Enterprise accounts with approved payment pages.
75. Core Endpoints-Mandates - Update a Mandate
PUT {{url}}/mandates/{{mandate}}
Updates a mandate object. This accepts only the metadata parameter.
76. Core Endpoints-Mandates - List Mandates
GET {{url}}/mandates
Returns a cursor-paginated list of your mandates.
77. Core Endpoints-Mandates - Get a single Mandate
GET {{url}}/mandates/{{mandate}}
Retrieves the details of an existing mandate.
78. Core Endpoints-Mandates - Cancel a Mandate
POST {{url}}/mandates/{{mandate}}/actions/cancel
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.
79. Core Endpoints-Mandates - Reinstate a Mandate
POST {{url}}/mandates/{{mandate}}/actions/reinstate
Reinstates a cancelled or expired mandate to the banks. You will receive a resubmissionrequested webhook, but after that reinstating the mandate follows the same process as its initial creation, so you will receive a submitted webhook, followed by a reinstated or failed webhook up to two working days later. Any metadata supplied to this endpoint will be stored on the resubmissionrequested event it causes.
This will fail with a mandatenotinactive error if the mandate is already being submitted, or is active.
Mandates can be resubmitted up to 10 times.
80. Core Endpoints-Mandate Imports - Create New Mandate Import
POST {{url}}/mandate_imports
Mandate imports are first created, before mandates are added one-at-a-time, so this endpoint merely signals the start of the import process. Once youāve finished adding entries to an import, you should submit it.
81. Core Endpoints-Mandate Imports - Submit Mandate Import
POST {{url}}/mandate_imports/{{mandate_import}}/actions/submit
Submits the mandate import, which allows it to be processed by a member of the GoCardless team. Once the import has been submitted, it can no longer have entries added to it.
In our sandbox environment, to aid development, we automatically process mandate imports approximately 10 seconds after they are submitted. This will allow you to test both the āsubmittedā response and wait for the webhook to confirm the processing has begun.
82. Core Endpoints-Mandate Imports - Cancel Mandate Import
POST {{url}}/mandate_imports/{{mandate_import}}/actions/cancel
Cancels the mandate import, which aborts the import process and stops the mandates being set up in GoCardless. Once the import has been cancelled, it can no longer have entries added to it. Mandate imports which have already been submitted or processed cannot be cancelled.
83. Core Endpoints-Mandate Imports - Get a Single Mandate import
GET {{url}}/mandate_imports/{{mandate_import}}
Returns a single mandate import.
84. Core Endpoints-Mandate Import Entries - Add Mandate import Entry
POST {{url}}/mandate_import_entries
For an existing mandate import, this endpoint can be used to add individual mandates to be imported into GoCardless.
You can add no more than 30,000 rows to a single mandate import. If you attempt to go over this limit, the API will return a recordlimitexceeded error.
85. Core Endpoints-Mandate Import Entries - List All Mandate Import Entries
GET {{url}}/mandate_import_entries?mandate_import={{mandate_import}}
For an existing mandate import, this endpoint lists all of the entries attached.
After a mandate import has been submitted, you can use this endpoint to associate records in your system (using the record_identifier that you provided when creating the mandate import).
86. Core Endpoints-Payer Authorisations (deprecated) - Create a Payer Authorisation
POST {{url}}/payer_authorisations
Payer Authorisations is deprecated in favour of Billing Requests. Please consider using Billing Requests to build any future integrations.
Creates a Payer Authorisation. The resource is saved to the database even if incomplete. An empty array of incomplete_fields means that the resource is valid. The ID of the resource is used for the other actions. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such as a multi-step form.
Note: the region field should be uncommented for US customer addresses.
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
87. Core Endpoints-Payer Authorisations (deprecated) - Update a Payer Authorisation
PUT {{url}}/payer_authorisations/{{payer_authorisation}}
Payer Authorisations is deprecated in favour of Billing Requests. Please consider using Billing Requests to build any future integrations.
Updates a Payer Authorisation. Updates the Payer Authorisation with the request data. Can be invoked as many times as needed. Only fields present in the request will be modified. An empty array of incomplete_fields means that the resource is valid. This endpoint has been designed this way so you do not need to save any payer data on your servers or the browser while still being able to implement a progressive solution, such a multi-step form.
Note: the region field should be uncommented for US customer addresses.
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
88. Core Endpoints-Payer Authorisations (deprecated) - Submit a Payer Authorisation
POST {{url}}/payer_authorisations/{{payer_authorisation}}/actions/submit
Payer Authorisations is deprecated in favour of Billing Requests. Please consider using Billing Requests to build any future integrations.
Submits all the data previously pushed to this PayerAuthorisation for verification. This time, a 200 HTTP status is returned if the resource is valid and a 422 error response in case of validation errors. After it is successfully submitted, the Payer Authorisation can no longer be edited.
89. Core Endpoints-Payer Authorisations (deprecated) - Confirm a Payer Authorisation
POST {{url}}/payer_authorisations/{{payer_authorisation}}/actions/confirm
Payer Authorisations is deprecated in favour of Billing Requests. Please consider using Billing Requests to build any future integrations.
Confirms the Payer Authorisation, indicating that the resources are ready to be created. A Payer Authorisation cannot be confirmed if it hasnāt been submitted yet.
90. Core Endpoints-Payer Authorisations (deprecated) - Get a Payer Authorisation
GET {{url}}/payer_authorisations/{{payer_authorisation}}
Payer Authorisations is deprecated in favour of Billing Requests. Please consider using Billing Requests to build any future integrations.
Retrieves the details of a single existing Payer Authorisation. It can be used for polling the status of a Payer Authorisation.
91. Core Endpoints-Payments - Create a Payment
POST {{url}}/payments
Creates a new payment object.
This fails with a mandateisinactive error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pendingcustomerapproval, pending_submission, submitted, and active.
92. Core Endpoints-Payments - Update a Payment
PUT {{url}}/payments/{{payment}}
Updates a payment object. This accepts only the metadata parameter.
93. Core Endpoints-Payments - List Payments
GET {{url}}/payments
Returns a cursor-paginated list of your payments.
94. Core Endpoints-Payments - Get a single Payment
GET {{url}}/payments/{{payment}}
Retrieves the details of a single existing payment.
95. Core Endpoints-Payments - Retry Payment
POST {{url}}/payments/{{payment}}/actions/retry
Retries a failed payment if the underlying mandate is active. You will receive a resubmission_requested webhook, but after that retrying the payment follows the same process as its initial creation, so you will receive a submitted webhook, followed by a confirmed or failed event. Any metadata supplied to this endpoint will be stored against the payment submission event it causes.
This will return a retry_failed error if the payment has not failed.
Payments can be retried up to 3 times.
96. Core Endpoints-Payments - Cancel a Payment
POST {{url}}/payments/{{payment}}/actions/cancel
Cancels the payment if it has not already been submitted to the banks. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.
This will fail with a cancellationfailed error unless the paymentās status is pendingsubmission.
97. Core Endpoints-Payouts - List Payouts
GET {{url}}/payouts
Returns a cursor-paginated list of your payouts.
98. Core Endpoints-Payouts - Get a single Payout
GET {{url}}/payouts/{{payout}}
Retrieves the details of a single payout. For an example of how to reconcile the transactions in a payout, see this guide.
99. Core Endpoints-Payouts - Update a Payout
PUT {{url}}/payouts/{{payout}}
Updates a payout object. This accepts only the metadata parameter.
100. Core Endpoints-Payout Items - List All Payout Items
GET {{url}}/payout_items?payout={{payout}}
Returns a cursor-paginated list of items in the payout.
101. Core Endpoints-Redirect Flows - Create a Redirect Flow
POST {{url}}/redirect_flows
Please consider using the Billing Requests API instead of Redirect Flows for any future integrations.
Creates a redirect flow object which can then be used to redirect your customer to the GoCardless hosted payment pages.
102. Core Endpoints-Redirect Flows - Complete a single Redirect Flow
POST {{url}}/redirect_flows/{{redirect_flow}}/actions/complete
Please consider using the Billing Requests API instead of Redirect Flows for any future integrations.
This creates a customer, customer bank account, and mandate using the details supplied by your customer and returns the ID of the created mandate.
This will return a redirectflowincomplete error if your customer has not yet been redirected back to your site, and a redirectflowalreadycompleted error if your integration has already completed this flow. It will return a badrequest error if the session_token differs to the one supplied when the redirect flow was created.
103. Core Endpoints-Redirect Flows - Get a single Redirect Flow
GET {{url}}/redirect_flows/{{redirect_flow}}
Please consider using the Billing Requests API instead of Redirect Flows for any future integrations.
Returns all details about a single redirect flow
104. Core Endpoints-Refunds - Create a Refund
POST {{url}}/refunds
Creates a new refund object.
105. Core Endpoints-Refunds - Update a Refund
PUT {{url}}/refunds/{{refund}}
Updates a refund object.
106. Core Endpoints-Refunds - List Refunds
GET {{url}}/refunds
Returns a cursor-paginated list of your refunds.
107. Core Endpoints-Refunds - Get a single Refund
GET {{url}}/refunds/{{refund}}
Retrieves all details for a single refund
108. Core Endpoints-Scenario Simulators - Billing Request Fulfilled Scenario
POST {{url}}/scenario_simulators/billing_request_fulfilled/actions/run
109. Core Endpoints-Scenario Simulators - Billing Request Fulfilled & Payment Paid Out Scenario
POST {{url}}/scenario_simulators/billing_request_fulfilled_and_payment_paid_out/actions/run
110. Core Endpoints-Scenario Simulators - Billing Request Fulfilled & Payment Failed Scenario
POST {{url}}/scenario_simulators/billing_request_fulfilled_and_payment_failed/actions/run
111. Core Endpoints-Scenario Simulators - Payment Submitted Scenario
POST {{url}}/scenario_simulators/payment_submitted/actions/run
112. Core Endpoints-Scenario Simulators - Payment Confirmed Scenario
POST {{url}}/scenario_simulators/payment_confirmed/actions/run
113. Core Endpoints-Scenario Simulators - Payment Paid Out Scenario
POST {{url}}/scenario_simulators/payment_paid_out/actions/run
114. Core Endpoints-Scenario Simulators - Payment Failed Scenario
POST {{url}}/scenario_simulators/payment_failed/actions/run
115. Core Endpoints-Scenario Simulators - Payment Charged Back Scenario
POST {{url}}/scenario_simulators/payment_charged_back/actions/run
116. Core Endpoints-Scenario Simulators - Payment Charged Back Settled Scenario
POST {{url}}/scenario_simulators/payment_chargeback_settled/actions/run
117. Core Endpoints-Scenario Simulators - Payment Late Failure Scenario
POST {{url}}/scenario_simulators/payment_late_failure/actions/run
118. Core Endpoints-Scenario Simulators - Payment Late Failure Settled Scenario
POST {{url}}/scenario_simulators/payment_late_failure_settled/actions/run
119. Core Endpoints-Scenario Simulators - Mandate Activated Scenario
POST {{url}}/scenario_simulators/mandate_activated/actions/run
120. Core Endpoints-Scenario Simulators - Mandate Failed Scenario
POST {{url}}/scenario_simulators/mandate_failed/actions/run
121. Core Endpoints-Scenario Simulators - Mandate Expired Scenario
POST {{url}}/scenario_simulators/mandate_expired/actions/run
122. Core Endpoints-Scenario Simulators - Mandate Customer Approval Granted Scenario
POST {{url}}/scenario_simulators/mandate_customer_approval_granted/actions/run
123. Core Endpoints-Scenario Simulators - Mandate Customer Approval Skipped Scenario
POST {{url}}/scenario_simulators/mandate_customer_approval_skipped/actions/run
124. Core Endpoints-Scenario Simulators - Mandate Transferred Scenario
POST {{url}}/scenario_simulators/mandate_transferred/actions/run
125. Core Endpoints-Scenario Simulators - Mandate Transferred with Resubmission Scenario
POST {{url}}/scenario_simulators/mandate_transferred_with_resubmission/actions/run
126. Core Endpoints-Scenario Simulators - Refund Paid Scenario
POST {{url}}/scenario_simulators/refund_paid/actions/run
127. Core Endpoints-Scenario Simulators - Refund Settled Scenario
POST {{url}}/scenario_simulators/refund_settled/actions/run
128. Core Endpoints-Scenario Simulators - Refund Bounced Scenario
POST {{url}}/scenario_simulators/refund_bounced/actions/run
129. Core Endpoints-Scenario Simulators - Refund Returned Scenario
POST {{url}}/scenario_simulators/refund_returned/actions/run
130. Core Endpoints-Scenario Simulators - Payout Bounced Scenario
POST {{url}}/scenario_simulators/payout_bounced/actions/run
131. Core Endpoints-Scenario Simulators - Creditor Verification Status Action Required Scenario
POST {{url}}/scenario_simulators/creditor_verification_status_action_required/actions/run
132. Core Endpoints-Scenario Simulators - Creditor Verification Status in Review Scenario
POST {{url}}/scenario_simulators/creditor_verification_status_in_review/actions/run
133. Core Endpoints-Scenario Simulators - Creditor Verification Status Successful Scenario
POST {{url}}/scenario_simulators/creditor_verification_status_successful/actions/run
134. Core Endpoints-Scheme Identifiers - Create a Scheme Identifier
POST {{url}}/scheme_identifiers
Creates a new scheme identifier. The scheme identifier must beĀ applied to a creditorĀ before payments are taken using it. The scheme identifier must also have theĀ statusĀ of active before it can be used. For some schemes e.g. faster_payments this will happen instantly. For other schemes e.g. bacs this can take several days.
Relative endpoint:Ā POST /scheme_identifiers
135. Core Endpoints-Scheme Identifiers - List Scheme Identifiers
GET {{url}}/scheme_identifiers
Returns a cursor-paginated list of your scheme identifiers.
136. Core Endpoints-Scheme Identifiers - Get a Scheme Identifier
GET {{url}}/scheme_identifiers/{{scheme_identifier}}
Retrieves the details of an existing scheme identifier.
137. Core Endpoints-Subscriptions - Create a Subscripton
POST {{url}}/subscriptions
Creates a new subscription object
138. Core Endpoints-Subscriptions - Update a Subscription
PUT {{url}}/subscriptions/{{subscription}}
Updates a subscription object.
139. Core Endpoints-Subscriptions - List Subscriptions
GET {{url}}/subscriptions
Returns a cursor-paginated list of your subscriptions.
140. Core Endpoints-Subscriptions - Get a single Subscription
GET {{url}}/subscriptions/{{subscription}}
Retrieves the details of a single subscription.
141. Core Endpoints-Subscriptions - Pause a Subscription
POST {{url}}/subscriptions/{{subscription}}/actions/pause
Pause a subscription object. No payments will be created until it is resumed.
This can only be used when a subscription is collecting a fixed number of payments (created using count), when they continue forever (created without count or end_date) or the subscription is already paused for a number of cycles.
142. Core Endpoints-Subscriptions - Cancel a Subscription
POST {{url}}/subscriptions/{{subscription}}/actions/cancel
Immediately cancels a subscription; no more payments will be created under it. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.
This will fail with a cancellation_failed error if the subscription is already cancelled or finished.
143. Core Endpoints-Subscriptions - Resume a Subscription
POST {{url}}/subscriptions/{{subscription}}/actions/resume
Resume a subscription object. Payments will start to be created again based on the subscriptions recurrence rules. The chargedate on the next payment will be the same as the subscriptions earliestchargedateafter_resume
144. Core Endpoints-Tax Rates - List Tax Rates
GET {{url}}/tax_rates
145. Core Endpoints-Tax Rates - Get a Single Tax Rate
GET {{url}}/tax_rates/{{tax_rate}}
146. Core Endpoints-Transferred Mandates - Get updated customer bank details
GET {{url}}/transferred_mandates/{{mandate}}
Returns new customer bank details for a mandate thatās been recently transferred
Note: See ourĀ Security RequirementsĀ before using this feature
Restricted: This endpoint is restricted to organisations with the Transfer Bank Accounts upgrade
147. Core Endpoints-Webhooks - List Webhooks
GET {{url}}/webhooks
Returns a cursor-paginated list of your webhooks.
https://developer.gocardless.com/api-reference/#webhooks-list-webhooks
148. Core Endpoints-Webhooks - Get a Webhook
GET {{url}}/webhooks/{{webhook}}
Retrieves the details of an existing webhook.
https://developer.gocardless.com/api-reference/#webhooks-get-a-single-webhook
149. Core Endpoints-Webhooks - Retry a Webhook
POST {{url}}/webhooks/{{webhook}}/actions/retry
Requests for a previous webhook to be sent again
https://developer.gocardless.com/api-reference/#webhooks-retry-a-webhook
150. Helper Endpoints - Create a Mandate PDF
POST {{url}}/mandate_pdfs
Mandate PDFs allow you to easily display scheme-rules compliant Direct Debit mandates to your customers.
Generates a PDF mandate and returns its temporary URL.
151. Helper Endpoints - Bank Details Lookup
POST {{url}}/bank_details_lookups
Look up the name and reachability of a bank account.
Note: bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
152. Helper Endpoints - Healthcheck
GET {{url}}/health_check
We expose a health check endpoint which can be used to test connections to our API. Requests to this endpoint do not require authorization and are not rate limited. This endpoint will return a 200 response while our API is available.
https://api.gocardless.com/health_checkfor livehttps://api-sandbox.gocardless.com/health_checkfor sandbox
153. Embed Flow-1. Creditors - Create a Creditor
POST {{url}}/creditors
Creates a new creditor.
Restricted: This endpoint is restricted to customers using the GoCardless Embed product. Partners should instead manage multiple merchant accounts by building aĀ partner integration.
154. Embed Flow-1. Creditors - List Creditors
GET {{url}}/creditors
Returns a cursor-paginated list of your creditors.
List Creditors API Docs
155. Embed Flow-1. Creditors - Get a single Creditor
GET {{url}}/creditors/{{creditor}}
Retrieves the details of an existing creditor.
List Creditors API Docs
156. Embed Flow-1. Creditors - Update a Creditor
PUT {{url}}/creditors/{{creditor}}
Updates a creditor object. Supports all of the fields supported when creating a creditor.
Update a Creditor API Docs
157. Embed Flow-2. (Optional) Creditors Bank Accounts - Create a Creditor Bank Account
POST {{url}}/creditor_bank_accounts
Creates a new creditor bank account object.
Note: Creditor bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
158. Embed Flow-2. (Optional) Creditors Bank Accounts - List Creditor Bank Accounts
GET {{url}}/creditor_bank_accounts
Returns a cursor-paginated list of your creditor bank accounts.
159. Embed Flow-2. (Optional) Creditors Bank Accounts - Get a single Creditor Bank Account
GET {{url}}/creditor_bank_accounts/{{creditor_bank_account}}
Retrieves the details of an existing creditor bank account.
160. Embed Flow-2. (Optional) Creditors Bank Accounts - Disable a Creditor Bank Account
POST {{url}}/creditor_bank_accounts/{{creditor_bank_account}}/actions/disable
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.
161. Embed Flow-3. (Optional) Scheme Identifiers - Create a Scheme Identifier
POST {{url}}/scheme_identifiers
Creates a new scheme identifier. The scheme identifier must beĀ applied to a creditorĀ before payments are taken using it. The scheme identifier must also have theĀ statusĀ of active before it can be used. For some schemes e.g. faster_payments this will happen instantly. For other schemes e.g. bacs this can take several days.
Relative endpoint:Ā POST /scheme_identifiers
162. Embed Flow-3. (Optional) Scheme Identifiers - List Scheme Identifiers
GET {{url}}/scheme_identifiers
Returns a cursor-paginated list of your scheme identifiers.
163. Embed Flow-3. (Optional) Scheme Identifiers - Get a Scheme Identifier
GET {{url}}/scheme_identifiers/{{scheme_identifier}}
Retrieves the details of an existing scheme identifier.
164. Embed Flow-4. Create Mandate & Payment - 4.1 Create a Billing Request (Mandate)
POST {{url}}/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.
165. Embed Flow-4. Create Mandate & Payment - 4.2 Collect Customer Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_customer_details
If the billing request has a pending collectcustomerdetails 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.
Note: the region field should be uncommented for US customer addresses.
166. Embed Flow-4. Create Mandate & Payment - 4.3 Collect Bank Account Details
POST {{url}}/billing_requests/{{billing_request}}/actions/collect_bank_account
If the billing request has a pending collectbankaccount 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.
Note: Customer bank accounts can be created with local or international bank details. You can find the different local bank detail formats, and how they should be used with the GoCardless API here.
167. Embed Flow-4. Create Mandate & Payment - 4.4 Confirm Customer & Bank Account Details
POST {{url}}/billing_requests/{{billing_request}}/actions/confirm_payer_details
This is needed when you have mandate_request. As a scheme compliance rule we are required to allow the payer to crosscheck the details entered by them and confirm it.
168. Embed Flow-4. Create Mandate & Payment - 4.5 Fulfill a Billing Request
POST {{url}}/billing_requests/{{billing_request}}/actions/fulfil
If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment.
169. Embed Flow-4. Create Mandate & Payment - 4.6 Create a Payment
POST {{url}}/payments
Creates a new payment object.
This fails with a mandateisinactive error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pendingcustomerapproval, pending_submission, submitted, and active.
170. Embed Flow-Branding-Logos - Create a logo
POST {{url}}/branding/logos
Creates a new logo for the creditor
171. Embed Flow-Branding-PayerThemes - Create a Payer theme
POST {{url}}/branding/payer_themes
Creates a new Payer theme for the creditor
172. Embed Flow-Exports - List Exports
GET {{url}}/exports
173. Embed Flow-Exports - Get Export
GET {{url}}/exports/{{export}}
ENDPOINTS