Connect GoCardless to Claude: Manage Payments, Payouts, and Refunds

If your team uses ChatGPT, check out our guide on /connect-gocardless-to-chatgpt-automate-mandates-and-subscriptions/ or explore our broader architectural overview on /connect-gocardless-to-ai-agents-handle-billing-and-outbound-flows/.

If you need to connect GoCardless to Claude to automate failed payment recovery, issue partial refunds, manage customer direct debit mandates, or reconcile payout batches, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM function calling and the GoCardless REST API.

You can either build and maintain this infrastructure in-house - dealing with OAuth refreshes, schema mapping, and infrastructure maintenance - or you can use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

Giving a Large Language Model (LLM) read and write access to a financial system like GoCardless is an engineering challenge with severe consequences for failure. You have to map massive JSON schemas to MCP tool definitions, deal with asynchronous banking states, and handle strict rate limits.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for GoCardless, connect it natively to Claude Desktop, and execute complex billing workflows using natural language.

The Engineering Reality of the GoCardless API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized financial APIs is painful. GoCardless manages asynchronous banking rails like Bacs, SEPA, and ACH. Its API reflects the slow, delayed nature of global banking networks.

If you decide to build a custom GoCardless MCP server, here are the specific integration challenges you will face:

Asynchronous State Machines and Mandate Delays Unlike a credit card API where a charge succeeds or fails in milliseconds, GoCardless relies on direct bank debiting. When you instruct an LLM to create a mandate or a payment, the initial API call simply returns a pending_submission state. It can take days for the mandate to become active or the payment to be confirmed. Your agent needs the context to understand that a successful HTTP 201 response does not mean the money has moved. The LLM must be equipped to query the payment status later or rely on webhook parsing to close the loop.

The Shift to Billing Requests GoCardless has evolved its API architecture. Historically, integrations used redirect flows to set up mandates. Now, GoCardless strictly recommends "Billing Requests." A Billing Request is a complex, nested object that can handle both mandate creation and immediate payment execution (e.g., via Open Banking). To use this, an LLM must assemble highly specific nested payloads containing payment_request, mandate_request, and multi-step actions. Manually defining these complex schemas for an LLM tool requires constant maintenance.

Rate Limits and 429 Responses When dealing with rate limits, it is critical to understand the boundaries of the integration layer. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream GoCardless API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (or the agent framework) is completely responsible for handling retry and exponential backoff logic. Truto does not automatically absorb rate limit errors.

Generating the GoCardless MCP Server

Truto dynamically generates MCP tools based on the GoCardless API documentation. It derives the schema directly from the integration's resource definitions. A tool only appears if it has a corresponding documentation entry, acting as a quality gate to ensure Claude only sees well-described endpoints.

Each MCP server is scoped to a single integrated account (a connected GoCardless instance for a specific tenant). The server URL contains a cryptographically hashed token that authenticates the request and enforces your security configurations.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For internal tooling or quick agent setup, you can grab the MCP URL directly from your dashboard:

1. Navigate to the integrated account page for your GoCardless connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods, tags, and expiry date).
5. Copy the generated MCP server URL. It will look like this: https://api.truto.one/mcp/a1b2c3d4e5f6...

Method 2: Via the API

If you are building a multi-tenant AI application and need to programmatically provision MCP servers for your end-users, you can hit the Truto REST API.

The API validates that the integration has tools available, generates a secure token, stores it in distributed KV storage, and returns the ready-to-use URL.

Endpoint: POST /integrated-account/:id/mcp

// Example using Node.js to provision a GoCardless MCP server
const createMcpServer = async (integratedAccountId) => {
  const response = await fetch(`https://api.truto.one/integrated-account/${integratedAccountId}/mcp`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TRUTO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Claude Financial Ops Agent",
      config: {
        methods: ["read", "write", "custom"] // Allow all operations
      },
      expires_at: "2026-12-31T23:59:59Z"
    })
  });
 
  const data = await response.json();
  console.log("Your MCP Server URL:", data.url);
  return data.url;
}

When a client calls a tool on this server, Truto handles the flat input namespace - receiving a single flat object of arguments and automatically mapping them into the required query parameters and request body fields for GoCardless.

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude is a matter of configuration. The MCP server operates entirely over HTTP POST using JSON-RPC 2.0 messages. You do not need to install any GoCardless specific SDKs or manage local server processes.

Method A: Via the Claude UI

If you are using Claude's web interface or enterprise workspace, you can add the server directly via the interface:

1. Copy the MCP server URL from Truto.
2. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
3. Paste the URL into the server configuration field.
4. Click Add.

Claude will immediately handshake with the initialize endpoint, execute a tools/list request, and populate its context with the available GoCardless operations.

Method B: Via Manual Configuration File

If you are using Claude Desktop or integrating into a local development environment, you can configure the MCP connection using the open-source Server-Sent Events (SSE) transport wrapper provided by the MCP project.

Update your claude_desktop_config.json file (typically located in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "gocardless-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The agent will read the config, spin up the SSE transport, and connect to the Truto endpoint.

Security and Access Control

Giving an AI agent access to payment infrastructure requires extreme isolation. Truto provides four distinct security levers on every MCP token:

• Method Filtering (config.methods): Restrict the server to specific operation types. Set ["read"] to allow only get and list tools (safe for reporting agents), or specify exact actions like ["create"].
• Tag Filtering (config.tags): Filter the tool list by functional area. If you only want the agent to touch refunds, you can restrict it to resources tagged with refunds.
• Expiration (expires_at): Set a strict time-to-live. Truto uses distributed alarms to automatically destroy the token and flush it from KV storage the second the expiration hits.
• Secondary Authentication (require_api_token_auth): When enabled, possession of the URL is not enough. The client must also send a valid Truto API token in the Authorization header, preventing leaked URLs from being exploited.

Hero Tools for GoCardless

Here are some of the most powerful tools available to Claude when connected to GoCardless via Truto. We derive these tools directly from the GoCardless resource documentation.

Create a GoCardless Customer

create_a_go_cardless_customer

This tool allows the agent to provision a new customer profile. It is the prerequisite for establishing mandates and collecting payments. The schema expects standard contact details and an email address.

"We just signed Acme Corp. Create a new GoCardless customer record for Jane Doe at jane.doe@acme.example.com. Add a metadata tag that says 'source: enterprise_sales'."

Create a Billing Request

create_a_go_cardless_billing_request

This is the modern method for setting up direct debit collections. It replaces the legacy redirect flows. The agent can construct a complex payload to initiate a mandate request or a one-off payment request.

"Generate a billing request to set up a new Bacs mandate for the customer ID I just created. Return the URL so I can send it to the client for authorization."

Retry a Failed Payment

go_cardless_payments_retry

If a direct debit fails (e.g., due to insufficient funds), this custom operation resubmits the payment against the active mandate. GoCardless limits retries to a maximum of 3 per payment.

"Look up the failed payment PM123456. If it failed due to insufficient funds, attempt to retry it now using the go_cardless_payments_retry tool."

Cancel a Subscription

go_cardless_subscriptions_cancel

Immediately stops all future recurring payments under a specific subscription. This is a highly destructive action that updates the subscription status to cancelled.

"The customer with subscription SB987655 requested a cancellation. Execute the cancellation tool and confirm the final status in the response."

List Payouts

list_all_go_cardless_payouts

Retrieves a cursor-paginated list of all transfers of collected payments sent to the merchant's bank account. This tool is heavily used by AI agents performing daily financial reconciliation.

"Fetch all payouts processed in the last 7 days. Summarize the total deducted fees and the arrival dates for each batch."

Issue a Refund

create_a_go_cardless_refund

Creates a partial or full refund against a specific collected payment. The agent must specify the exact amount in the lowest currency denomination (e.g., pence or cents).

"The client requested a 50% refund on their last payment of £100. Issue a refund for 5000 pence against payment ID PM999888."

To see the complete tool inventory, including mandate imports, webhook management, and bank authorization endpoints, visit the GoCardless integration page.

Workflows in Action

With the MCP server connected, Claude can sequence multiple tools together to perform multi-step operations that would traditionally require a human logging into the GoCardless dashboard.

Scenario 1: Recovering a Failed Payment

Support teams often handle tickets related to failed direct debits. An AI agent can automatically triage these requests, check the payment status, and initiate a retry without leaving the support interface.

User: "Can you check why the last payment for customer CU_123 failed and retry it if it's safe to do so?"

How Claude executes this:

1. Calls list_all_go_cardless_payments filtering by the customer ID to find the recent payment with a failed status.
2. Analyzes the API response, noting the failure cause (e.g., insufficient_funds).
3. Calls go_cardless_payments_retry passing the exact payment ID.
4. Returns a natural language summary to the user confirming the retry is now pending submission to the banking network.

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant GoCardless as GoCardless API

    User->>Claude: "Check failed payment for CU_123..."
    Claude->>Truto: call list_all_go_cardless_payments (customer: CU_123)
    Truto->>GoCardless: GET /payments?customer=CU_123
    GoCardless-->>Truto: { payments: [{ id: "PM_123", status: "failed" }] }
    Truto-->>Claude: JSON-RPC Result
    Claude->>Truto: call go_cardless_payments_retry (payment_id: PM_123)
    Truto->>GoCardless: POST /payments/PM_123/actions/retry
    GoCardless-->>Truto: { payments: { id: "PM_123", status: "pending_submission" } }
    Truto-->>Claude: JSON-RPC Result
    Claude-->>User: "Payment retry initiated successfully."

Scenario 2: Canceling a Subscription and Issuing a Prorated Refund

When a customer churns mid-cycle, revenue operations must manually cancel the subscription, calculate the prorated amount, and issue a refund against the last payment. An AI agent handles the entire sequence.

User: "Cancel subscription SB_456 and issue a partial refund of $20.00 against their most recent payment."

How Claude executes this:

1. Calls go_cardless_subscriptions_cancel using the provided subscription ID.
2. Calls get_single_go_cardless_subscription_by_id to retrieve the links.mandate or recent payment history associated with that subscription.
3. Calls list_all_go_cardless_payments scoped to that mandate to find the last confirmed payment ID.
4. Calls create_a_go_cardless_refund with the payment ID and the amount 2000 (cents).
5. Verifies the refund object returned by the API and reports the success back to the operator.

flowchart TD
    A["User Prompt<br>Cancel SB_456 and refund $20"] --> B["Tool Call<br>go_cardless_subscriptions_cancel"]
    B --> C["Tool Call<br>list_all_go_cardless_payments<br>Filter by Subscription Mandate"]
    C --> D["Extract last successful payment ID"]
    D --> E["Tool Call<br>create_a_go_cardless_refund<br>Amount: 2000"]
    E --> F["Return success confirmation to User"]

Stop Building Custom Tool Proxies

Integrating conversational AI with financial infrastructure requires absolute precision. Hand-coding an MCP server for GoCardless forces your team to maintain authentication states, track schema changes, and manually write JSON-RPC protocol handlers.

By leveraging Truto's dynamically generated MCP servers, your AI agents get immediate, curated access to GoCardless endpoints based directly on the integration's native documentation. You manage the security filters and token lifecycles; Truto handles the protocol translation and execution.