A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The GoCardless API is how an app or AI agent collects bank payments: creating a customer, setting up a mandate to take Direct Debit, charging a payment, or running recurring billing through subscriptions. Access is granted through an access token, and the token is created as read-only or read-write, so its level decides whether a call can only look or can also make changes. GoCardless versions its API by date, and it pushes events when a resource changes so an integration learns about activity without polling.
How an app or AI agent connects to GoCardless determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes GoCardless to agents, and each is governed by the access token behind it and the level that token was given when it was created.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a cursor, at https://api.gocardless.com for live and https://api-sandbox.gocardless.com for sandbox. Every call sends an access token in an Authorization Bearer header and names the dated API version in a GoCardless-Version header. Updates use PUT, not PATCH, which is not allowed.
A hosted Model Context Protocol server at https://mcp.gocardless.com, announced 18 February 2026, exposes GoCardless to AI agents and LLM clients. It gives a model structured knowledge of the API and integration patterns, and lets it query a live GoCardless account in natural language, like asking how many payments are overdue today.
GoCardless POSTs events to an HTTPS endpoint registered in the dashboard or via the API. The body is signed with an HMAC SHA256 hex digest of the request body, using the endpoint's secret, supplied in a Webhook-Signature header. The receiver recomputes and compares the digest before processing, so a forged webhook is rejected.
An access token is created in the GoCardless dashboard and sent in an Authorization header using the Bearer scheme. It is created as read-only or read-write, and that level applies to every resource the token can reach; there are no finer per-resource scopes. A token must never be exposed in client code.
A publishable access token is used by the GoCardless JavaScript Flow, which collects bank account details in the browser. It is limited to the client-safe operations that flow needs and is safe to use in front-end code, unlike a standard access token.
A partner integration acting for many merchants uses OAuth: a merchant authorises the partner app, the partner exchanges the resulting code for an access token tied to that merchant's account, and an introspect API checks a token's validity. The rate limit then applies per merchant.
The GoCardless API is split into areas an agent can act on, like customers, mandates, payments, subscriptions, payouts, and refunds. Each area has its own methods, and writes in some areas set up or collect real bank payments.
Methods for working with customers, the people an integration collects from.
Methods for working with the bank accounts a mandate debits.
Methods for working with mandates, the authorisation to debit a customer.
Methods for working with payments collected against a mandate.
Methods for working with subscriptions, recurring payments on a mandate.
Methods for reading payouts sent from GoCardless to the creditor's bank.
Methods for working with refunds returned to a customer.
Methods for reading the events that record what happened to resources.
Methods for working with creditors, the entities that collect payments.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CustomersMethods for working with customers, the people an integration collects from.5 | ||||||
| POST | /customers | Create a customer, the person an integration will collect payments from. | write | read-write | Current | |
Needs a read-write token. Restricted in live unless payment pages are scheme-compliant; otherwise use the Billing Requests API. Acts oncustomer Permission (capability) read-writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customers/:id | Retrieve a single customer by id. | read | read-only | Current | |
Readable with a read-only token. Acts oncustomer Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customers | List customers, cursor-paginated and filterable. | read | read-only | Current | |
Readable with a read-only token. Acts oncustomer Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /customers/:id | Update a customer's details. GoCardless uses PUT for updates; PATCH is not allowed. | write | read-write | Current | |
Needs a read-write token. Acts oncustomer Permission (capability) read-writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /customers/:id | Remove a customer, which also cancels their mandates and subscriptions. | write | read-write | Current | |
Needs a read-write token; cancels related mandates and subscriptions. Acts oncustomer Permission (capability) read-writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Customer bank accountsMethods for working with the bank accounts a mandate debits.4 | ||||||
| POST | /customer_bank_accounts | Create a customer bank account that a mandate can later debit. | write | read-write | Current | |
Needs a read-write token. Restricted in live unless payment pages are scheme-compliant; otherwise use the Billing Requests API. Acts oncustomer_bank_account Permission (capability) read-writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customer_bank_accounts/:id | Retrieve a single customer bank account by id. | read | read-only | Current | |
Readable with a read-only token; account numbers are returned masked. Acts oncustomer_bank_account Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customer_bank_accounts | List customer bank accounts, cursor-paginated and filterable. | read | read-only | Current | |
Readable with a read-only token. Acts oncustomer_bank_account Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /customer_bank_accounts/:id/actions/disable | Disable a customer bank account so it can no longer be used. | write | read-write | Current | |
Needs a read-write token; once disabled the account cannot be re-enabled. Acts oncustomer_bank_account Permission (capability) read-writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MandatesMethods for working with mandates, the authorisation to debit a customer.4 | ||||||
| POST | /mandates | Create a mandate, the customer's authorisation to debit their bank account. | write | read-write | Current | |
Needs a read-write token. Restricted in live unless payment pages are scheme-compliant; otherwise use the Billing Requests API. Acts onmandate Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event mandates-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /mandates/:id | Retrieve a single mandate by id. | read | read-only | Current | |
Readable with a read-only token. Acts onmandate Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /mandates | List mandates, cursor-paginated and filterable by customer, status, or creditor. | read | read-only | Current | |
Readable with a read-only token. Acts onmandate Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /mandates/:id/actions/cancel | Cancel a mandate so no further payments can be collected against it. | write | read-write | Current | |
Needs a read-write token; ends authority to debit the customer. Acts onmandate Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event mandates-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PaymentsMethods for working with payments collected against a mandate.5 | ||||||
| POST | /payments | Create a payment to collect money against an active mandate. | write | read-write | Current | |
Needs a read-write token; collects real money. Send an Idempotency-Key to avoid a double charge on retry. Acts onpayment Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event payments-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payments/:id | Retrieve a single payment by id, including its status. | read | read-only | Current | |
Readable with a read-only token. Acts onpayment Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payments | List payments, cursor-paginated and filterable by mandate, customer, creditor, or status. | read | read-only | Current | |
Readable with a read-only token. Acts onpayment Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payments/:id/actions/cancel | Cancel a payment that has not yet been submitted to the banks. | write | read-write | Current | |
Needs a read-write token; only works before the payment is submitted. Acts onpayment Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event payments-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /payments/:id/actions/retry | Retry a failed payment, reattempting collection against the mandate. | write | read-write | Current | |
Needs a read-write token; only valid for a failed payment. Acts onpayment Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event payments-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsMethods for working with subscriptions, recurring payments on a mandate.2 | ||||||
| POST | /subscriptions | Create a subscription to collect recurring payments on a mandate. | write | read-write | Current | |
Needs a read-write token; schedules recurring collection. Acts onsubscription Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event subscriptions-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/:id/actions/cancel | Cancel a subscription so no further payments are scheduled. | write | read-write | Current | |
Needs a read-write token; the mandate stays active for other payments. Acts onsubscription Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event subscriptions-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PayoutsMethods for reading payouts sent from GoCardless to the creditor's bank.2 | ||||||
| GET | /payouts/:id | Retrieve a single payout sent from GoCardless to the creditor's bank account. | read | read-only | Current | |
Readable with a read-only token. Acts onpayout Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payouts | List payouts, cursor-paginated and filterable by creditor, status, or reference. | read | read-only | Current | |
Readable with a read-only token. Acts onpayout Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsMethods for working with refunds returned to a customer.2 | ||||||
| POST | /refunds | Create a refund to return money to a customer for a payment. | write | read-write | Current | |
Needs a read-write token; refunds are only available once the creditor has the can_create_refunds flag set. Acts onrefund Permission (capability) read-writeVersionAvailable since the API’s base version Webhook event refunds-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /refunds | List refunds, cursor-paginated and filterable by payment, mandate, or refund type. | read | read-only | Current | |
Readable with a read-only token. Acts onrefund Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsMethods for reading the events that record what happened to resources.2 | ||||||
| GET | /events/:id | Retrieve a single event recording something that happened to a resource. | read | read-only | Current | |
Readable with a read-only token. Acts onevent Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /events | List events, cursor-paginated and filterable by resource type, action, or parent event, for reconciliation or replay. | read | read-only | Current | |
Readable with a read-only token; the same events are pushed by webhook. Acts onevent Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CreditorsMethods for working with creditors, the entities that collect payments.2 | ||||||
| GET | /creditors/:id | Retrieve a single creditor, the entity that collects payments. | read | read-only | Current | |
Readable with a read-only token. Acts oncreditor Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /creditors | List creditors on the account, cursor-paginated. | read | read-only | Current | |
Readable with a read-only token. Acts oncreditor Permission (capability) read-onlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GoCardless can notify an app when something happens to a resource, like a payment being confirmed or a mandate being cancelled. It sends events describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
payments | An event on a payment, like it being confirmed, paid out, failed, cancelled, or charged back. The action field names what happened. | /payments/payments/:id/actions/cancel/payments/:id/actions/retry |
mandates | An event on a mandate, like it being created, becoming active, being cancelled, failing, or expiring. The action field names what happened. | /mandates/mandates/:id/actions/cancel |
subscriptions | An event on a subscription, like it being created, payment being created on schedule, being cancelled, or finishing. | /subscriptions/subscriptions/:id/actions/cancel |
refunds | An event on a refund, like it being created, paid, or failing. | /refunds |
payouts | An event on a payout, like it being paid into the creditor's bank account. | In-app only |
GoCardless limits how fast an app can call, by a request rate measured per minute, and it pages through long lists with a cursor.
GoCardless applies a single rate limit across all API requests, currently 1000 requests per minute. For a partner integration making calls on behalf of a merchant, the limit is 1000 requests per minute per merchant. The current ceiling is returned in the ratelimit-limit response header, with ratelimit-remaining and ratelimit-reset showing how many calls are left in the window and when it resets. Going over returns HTTP 429 with a rate_limit_exceeded error, and those requests can be safely retried.
Lists are cursor-paginated. A request pages with after, the id of the object immediately following the page, or before, the id of the object immediately preceding it, and limit sets the page size. The response carries a meta.cursors object holding the after and before values to fetch the next or previous page, so an integration walks a list without offsets.
The limit parameter defaults to 50, with a maximum of 500 and a minimum of 1. Custom metadata allows up to 3 key-value pairs, with key names up to 50 characters and values up to 500 characters.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_api_usage | Bad Request. The request could not be understood, usually due to malformed syntax. An invalid_api_usage error covers using the API incorrectly, like a missing required header or a malformed body. | Read the errors array in the response body, fix the request, and resend. Alert the dev team; do not retry unchanged. |
| 401 | unauthorized | The request did not provide a valid Authorization header, or the user making it has been disabled. | Confirm a valid access token is being sent, and rotate it if it is compromised. |
| 403 | forbidden | The token is valid but lacks permission for this resource, for example a read-only token calling a write method. | Use a read-write token for write calls, or scope the action out of the agent's allowed set. |
| 404 | not_found | The requested resource was not found, or the authenticated user cannot access it. | Verify the resource id and confirm the token's account can see it. |
| 409 | idempotent_creation_conflict | A create reused an Idempotency-Key that already succeeded, or the resource already exists. The error carries links.conflicting_resource_id. | Treat the conflicting resource as the result, or use a fresh idempotency key per distinct operation. |
| 422 | validation_failed | The request was well formed but invalid. Each error in the response names a field and a message describing what is wrong. invalid_state covers a request that conflicts with the resource's current state. | For validation_failed, correct the named fields and resend. For invalid_state, alert the end user and do not retry. |
| 429 | rate_limit_exceeded | Too many requests arrived in the current window. The ratelimit-remaining and ratelimit-reset headers explain the limit. | Back off until the window resets, then retry. These requests can be safely retried. |
| 500 | internal_server_error | An error occurred within GoCardless while processing the request. It is rare and may also appear as request_timed_out. | Retry the request, and report it to GoCardless support with the request_id if it persists. |
GoCardless versions its API by date. A request names the version it expects in a header, and a new dated version is only minted for a breaking change.
GoCardless versions its API by date, sent in the GoCardless-Version header on every request, and only mints a new dated version for a breaking change. 2015-07-06 is the latest released version. It made resource structure and date handling consistent across the API.
The dated version immediately before 2015-07-06. GoCardless kept it available through to 6 January 2016 to give integrations a migration window.
Pin the dated version a request sends and move up deliberately when a new one ships.
GoCardless API changelog ↗Bollard AI sits between a team's AI agents and GoCardless. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.