Registry / payments / gocardless-pro

gocardless-pro

JSON →
library3.4.1pypypi✓ verified 84d ago

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.

pip install gocardless-pro
INSTALL
IMPORT
SIG · GOCARDLESS-PRO
G
gocardless-pro
paymentspythonv3.4.1
Install
2.2s avg
Import
742ms
Disk
22MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.777s · 23.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.707s · 24MB
22MB installed
● package 22MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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}")
Debug
Known issues
breakingVersion 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.
affects: >=3.0.0
breakingAs 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.
affects: >=3.1.0
deprecatedVersion 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.
affects: >=3.2.0
gotchaUsing 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.
affects: All versions
Errors
Common errors & fixes
gocardless_pro.errors.InvalidApiUsageException: [400] Validation Failed
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
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.
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.
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.
Upgrade
Version history
3.4.1latest on PyPI · released May 27, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
32 hits · last 30 days
node
28
OpenAI (training)
1
Resources
gocardless-pro — pip install gocardless-pro · libregistry