At a glance
- Availability: Experimental (how to enable).
- Auth: API key.
- Connection: The key from
GOCARDLESS_ACCESS_TOKENis sent as theBearerprefixedAuthorizationheader. - Docs: https://developer.gocardless.com/api-reference/
Credentials
Set these per environment. See Connect an integration.| Variable | Required | Description |
|---|---|---|
GOCARDLESS_ACCESS_TOKEN | Yes | GoCardless API access token created in the dashboard under Developers. Use a sandbox token (from manage-sandbox.gocardless.com) for testing or a live token for production. Docs. |
Setup
- Create a sandbox account for testing: Sign up for a free GoCardless sandbox at https://manage-sandbox.gocardless.com/signup. The sandbox lets you create test customers, mandates, and payments without moving real money. Sandbox API requests go to https://api-sandbox.gocardless.com instead of https://api.gocardless.com.
- Create an access token: In the dashboard (https://manage.gocardless.com for live, https://manage-sandbox.gocardless.com for sandbox), go to Developers, then Create and choose Access token. Give it read-write access if you want to create payments.
- Store the token: Add GOCARDLESS_ACCESS_TOKEN=<your token> to your .env file. The token is sent as a Bearer token in the Authorization header.
- Verify access: Run the List Customers tool. Every request also sends the GoCardless-Version header (2015-07-06 by default), which the API requires.
- Tools call the live API at https://api.gocardless.com; for sandbox testing, point requests at https://api-sandbox.gocardless.com with a sandbox token
- Amounts are integers in the smallest currency unit (pence/cents), and payments can only be created against mandates in an active or pending state
- Every API request must include the GoCardless-Version header; each tool sends 2015-07-06 by default
Tools
| Tool | Access | Description |
|---|---|---|
| List Customers | Read | List GoCardless customers to find customer IDs and contact details |
| List Payments | Read | List GoCardless payments with optional status, customer, or mandate filtering |
| Get Payment | Read | Get a single GoCardless payment by ID to check its status, amount, and linked mandate |
| List Mandates | Read | List Direct Debit mandates to find an active mandate before collecting a payment |
| Create Payment | Write | Collect a one-off payment against an existing active Direct Debit mandate |
| Create Subscription | Write | Set up a recurring payment collection against an existing active Direct Debit mandate |
| Retry Payment | Write | Retry a failed payment if its mandate is still active; a payment can be retried at most three times |
| List Events | Read | List GoCardless events (status changes such as payment failures, chargebacks, and mandate cancellations) for monitoring and audit workflows |
Example prompts
- List my most recent GoCardless payments and summarize their statuses, flagging any failed or charged-back payments.
- List my GoCardless mandates and report which are active versus cancelled, failed, or expired.
- Find the active GoCardless mandate for a customer I specify and collect a payment of the amount I provide.