GoCardless Getting Started: Account Setup & First API Call (2026)

Getting started overview

Integrating with GoCardless allows developers to automate the collection of bank payments, including Direct Debits and Instant Bank Pay, directly from their applications. This guide provides a structured approach to initiate that integration, covering account creation, API key management, and the execution of a foundational API request. The process is designed to enable quick setup for testing in a sandbox environment before deploying to production. GoCardless primarily supports recurring payments and subscription management, offering tools to reduce payment failures and streamline invoice collection GoCardless homepage.

Before making your first API call, you will need to complete the following steps:

1. Create a GoCardless account: This is the initial step to gain access to the GoCardless dashboard and sandbox environment.
2. Obtain API keys: Securely generate and retrieve the necessary API credentials (access token) for authentication.
3. Set up your development environment: Choose an SDK or prepare to make direct HTTP requests.
4. Make your first request: Execute a simple API call to confirm your setup is working.

Quick Reference Table

Create an account and get keys

To begin using the GoCardless API, you need to set up a new account. GoCardless provides a sandbox environment that allows developers to test integrations without affecting live payments GoCardless going live guide. This environment is crucial for development and debugging.

1. Sign up for a GoCardless account

Navigate to the GoCardless signup page and follow the prompts to create your account. During the signup process, you will be asked to provide basic business information. Ensure you select the option to start in the sandbox environment if you intend to test your integration without live financial transactions.

2. Access your API keys

Once your account is created and you've logged into the GoCardless dashboard, follow these steps to retrieve your API access token:

1. From the dashboard, navigate to Developers in the left-hand menu.
2. Select API Access.
3. Under the 'Access Tokens' section, you can generate a new token. It's recommended to create a separate token for your sandbox environment and another for your live environment when you are ready to go live.
4. Copy the generated access token. This token acts as your authentication credential and should be kept secure. You will use this token in the Authorization header of your API requests, typically prefixed with Bearer.

GoCardless API tokens are distinct from traditional API keys in that they are typically bearer tokens, providing access based on their presence in the HTTP header. This method is common across many modern APIs, including those from Stripe and Twilio, which use similar token-based authentication mechanisms Stripe API authentication guide.

Your first request

With your account set up and API access token obtained, you are ready to make your first API request. This example demonstrates how to create a new customer in the GoCardless sandbox environment. Creating a customer is a foundational step before you can create mandates or payments.

Prerequisites

• Your GoCardless access token (from the sandbox environment).
• A tool for making HTTP requests (e.g., cURL, Postman, or one of the GoCardless SDKs).

Using cURL to create a customer

This cURL command creates a new customer. Replace YOUR_ACCESS_TOKEN with the token you generated.

curl -X POST \
  https://api-sandbox.gocardless.com/customers \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'GoCardless-Version: 2015-07-06' \
  -d '{ "customers": { "email": "[email protected]", "given_name": "John", "family_name": "Doe", "address_line1": "10 Downing Street", "city": "London", "postal_code": "SW1A 2AA", "country_code": "GB" } }'

Expected Response (Status 201 Created)

{
  "customers": {
    "id": "CU12345678",
    "created_at": "2023-01-01T12:00:00.000Z",
    "email": "[email protected]",
    "given_name": "John",
    "family_name": "Doe",
    "address_line1": "10 Downing Street",
    "city": "London",
    "postal_code": "SW1A 2AA",
    "country_code": "GB",
    "metadata": {},
    "bank_account_requires_approval": false,
    "mandates": []
  }
}

A successful response will include a 201 Created status code and a JSON object representing the newly created customer, including a unique id. This id is essential for subsequent operations, such as creating a bank account or a mandate for the customer.

Using an SDK (Python example)

GoCardless provides SDKs for several popular languages, including Python, Ruby, PHP, Java, and Node.js GoCardless SDK documentation. Using an SDK simplifies API interactions by handling HTTP requests, authentication, and response parsing.

Python Example: Install and Create Customer

First, install the GoCardless Python SDK:

pip install gocardless-pro

Then, use the following Python code to create a customer:

import gocardless_pro
from gocardless_pro.services import customers

# Replace with your actual sandbox access token
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

client = gocardless_pro.Client(
    access_token=ACCESS_TOKEN,
    environment='sandbox' # or 'live' for production
)

try:
    customer = client.customers.create(
        params={
            "email": "[email protected]",
            "given_name": "Jane",
            "family_name": "Doe",
            "address_line1": "20 Baker Street",
            "city": "London",
            "postal_code": "NW1 6XE",
            "country_code": "GB"
        }
    )
    print(f"Customer created successfully: {customer.id}")
    print(customer)
except gocardless_pro.errors.APIError as e:
    print(f"Error creating customer: {e.errors}")
    print(f"Request ID: {e.request_id}")

This Python snippet initializes the client with your access token and sandbox environment, then calls the customers.create method with the required customer details. Error handling is included to catch potential API-specific issues.

Common next steps

After successfully making your first API call to create a customer, you can proceed with more advanced integrations:

1. Create a Customer Bank Account: Link a customer to a bank account. This is a prerequisite for creating mandates and payments. You will need to collect bank account details (e.g., account number, sort code for UK) from your user securely.
2. Set up a Mandate: A mandate (or authorization) grants GoCardless permission to collect payments from a customer's bank account. This requires customer consent, often obtained through a secure online flow provided by GoCardless or a partner. Mandates are essential for recurring payments via Direct Debit GoCardless Mandates API reference.
3. Create Payments: Once a mandate is active, you can create one-off or recurring payments against it. GoCardless supports various payment types, including one-off Direct Debits, Instant Bank Pay, and subscriptions.
4. Handle Webhooks: GoCardless uses webhooks to notify your application of event changes (e.g., payment success, failure, mandate cancellation). Implementing a webhook receiver is critical for real-time updates and maintaining the state of payments and mandates. Securing your webhooks is important to ensure incoming notifications are legitimate GoCardless webhook documentation.
5. Go Live: When your integration is thoroughly tested in the sandbox, GoCardless provides a process to move to the live environment, requiring a separate set of API keys.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check your API Access Token: Ensure your token is correct and hasn't expired. Verify it's prefixed with Bearer in the Authorization header. If you suspect an issue, generate a new token in the GoCardless dashboard.
• Verify Environment: Confirm you are using the sandbox endpoint (https://api-sandbox.gocardless.com) with a sandbox access token, or the live endpoint (https://api.gocardless.com) with a live token. Mixing these will result in authentication errors.
• Review Request Body: Double-check the JSON structure and data types in your request body against the GoCardless API reference. Common errors include missing required fields or incorrect data formats.
• Inspect HTTP Status Codes:
  • 401 Unauthorized: Typically indicates an issue with your access token (missing, invalid, or expired).
  • 403 Forbidden: Your token might lack the necessary permissions for the requested action.
  • 400 Bad Request or 422 Unprocessable Entity: Often signals an issue with the request body, such as invalid parameters or missing required data. The response body will usually contain specific error messages.
  • 5xx Server Error: Indicates an issue on GoCardless's side. If this persists, check the GoCardless status page or contact support.
• GoCardless-Version Header: Ensure the GoCardless-Version header is present and set to a valid API version, such as 2015-07-06. This helps ensure compatibility and prevents unexpected behavior due to API changes. For more context on API versioning, refer to general API design principles MDN Web Docs on API Versioning.
• Check GoCardless Dashboard Logs: The GoCardless dashboard provides API logs under the Developers section. These logs can offer detailed insights into your API requests and their responses, including any errors encountered by the GoCardless platform.