GoCardless Pro Python Client Library

3.3.0 · active · verified Thu Apr 16

A client library for the GoCardless Pro API. It simplifies integration with the GoCardless platform, handling API requests, authentication, and error handling. As of version 3.3.0, it is actively maintained with regular updates, supporting Python 3.9, 3.10, 3.11, and 3.12.

Common errors

```
gocardless_pro.errors.InvalidApiUsageException: [400] Validation Failed
```
cause This error typically occurs when the parameters sent in an API request do not meet the GoCardless API's validation rules (e.g., missing required fields, invalid format, or incorrect values).

fix Review the API documentation for the specific endpoint you are calling and ensure all required parameters are present and correctly formatted. Check for typos in field names or data types.
```
gocardless_pro.errors.GoCardlessProError: [401] Authentication Failed
```
cause The provided `access_token` is either missing, invalid, expired, or does not have the necessary permissions for the requested action.

fix Verify that your `GOCARDLESS_ACCESS_TOKEN` environment variable or client initialization directly uses a valid, active access token for the correct environment (sandbox/live). Generate a new token if necessary from your GoCardless dashboard.
```
gocardless_pro.errors.ApiConnectionException: Network error.
```
cause This exception indicates an underlying network issue, such as a timeout, DNS resolution failure, or inability to connect to the GoCardless API servers. The library automatically retries requests up to 3 times before raising this.

fix Check your network connectivity. If the issue persists, review any firewall rules or proxy settings that might be blocking outbound connections to `https://api.gocardless.com` or `https://api-sandbox.gocardless.com`. Implement robust retry logic with exponential backoff in your application.
```
gocardless_pro.errors.MalformedResponseException: Unexpected non-JSON response.
```
cause The GoCardless API returned a response that could not be parsed as valid JSON, possibly due to an intermediary error (e.g., a load balancer returning an HTML error page) or a corrupted response.

fix This often indicates a transient issue outside of your direct control. Retry the request after a short delay. If it persists, check the GoCardless status page for API outages or contact GoCardless support with the `request_id` if available.

Warnings

breaking Version 3.0.0 introduced breaking changes to the `POST billing_requests/create_with_actions` endpoint. Integrators using this endpoint should review the API reference for updated parameters and behavior.
Fix: Consult the official GoCardless API reference for the `create_with_actions` endpoint and update your implementation to match the new request body and response structure.
breaking As of v3.1.0, the `constraints[max_amount_per_payment]` field became required when creating Billing Requests that include a PayTo `mandate_request`.
Fix: Ensure that your Billing Request creation logic includes `constraints` with a `max_amount_per_payment` field when initiating PayTo `mandate_request`s.
deprecated Version 3.2.0 stopped exposing the API for creating negative balance limits.
Fix: Remove any calls or references to the negative balance limit creation API. Functionality related to managing negative balances should be handled through other GoCardless mechanisms.
gotcha Using the older `gocardless` library for new integrations will connect to the legacy API, which is not compatible with GoCardless Pro.
Fix: Always use `gocardless-pro` for new integrations. If you see documentation referring to `gocardless.Client` or `gocardless.set_details()`, you are likely looking at legacy API documentation.

Install

pip install gocardless-pro Install stable version

Imports

Client
wrong:
```
import gocardless
```
correct:
```
from gocardless_pro import Client
```
The `gocardless` library is for the legacy GoCardless API and should not be used for new integrations with the Pro API.

Quickstart

Initializes the GoCardless Pro client using an access token and environment, then demonstrates creating a customer and listing existing payments. Remember to set `GOCARDLESS_ACCESS_TOKEN` and `GOCARDLESS_ENVIRONMENT` (e.g., 'sandbox' or 'live') in your environment variables.

import os
from gocardless_pro import Client

# Ensure ACCESS_TOKEN and ENVIRONMENT are set in your environment variables
access_token = os.environ.get('GOCARDLESS_ACCESS_TOKEN', 'YOUR_GOCARDLESS_ACCESS_TOKEN')
environment = os.environ.get('GOCARDLESS_ENVIRONMENT', 'sandbox') # or 'live'

if not access_token or access_token == 'YOUR_GOCARDLESS_ACCESS_TOKEN':
    raise ValueError("Please set the GOCARDLESS_ACCESS_TOKEN environment variable or replace the placeholder.")

client = Client(access_token=access_token, environment=environment)

try:
    # Create a new customer
    customer = client.customers.create(
        params={'email': 'jane.doe@example.com', 'given_name': 'Jane', 'family_name': 'Doe'}
    )
    print(f"Created customer: {customer.id} - {customer.email}")

    # List payments (demonstrates fetching data)
    payments_list = client.payments.list()
    print(f"\nFirst 5 payments (total: {len(payments_list.records)}):")
    for i, payment in enumerate(payments_list.records[:5]):
        print(f"  - Payment ID: {payment.id}, Amount: {payment.amount}, Currency: {payment.currency}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →