{"id":8200,"library":"gocardless-pro","title":"GoCardless Pro Python Client Library","description":"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.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/gocardless/gocardless-pro-python","tags":["payment gateway","fintech","api client","gocardless","direct debit"],"install":[{"cmd":"pip install gocardless-pro","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The `gocardless` library is for the legacy GoCardless API and should not be used for new integrations with the Pro API.","wrong":"import gocardless","symbol":"Client","correct":"from gocardless_pro import Client"}],"quickstart":{"code":"import os\nfrom gocardless_pro import Client\n\n# Ensure ACCESS_TOKEN and ENVIRONMENT are set in your environment variables\naccess_token = os.environ.get('GOCARDLESS_ACCESS_TOKEN', 'YOUR_GOCARDLESS_ACCESS_TOKEN')\nenvironment = os.environ.get('GOCARDLESS_ENVIRONMENT', 'sandbox') # or 'live'\n\nif not access_token or access_token == 'YOUR_GOCARDLESS_ACCESS_TOKEN':\n    raise ValueError(\"Please set the GOCARDLESS_ACCESS_TOKEN environment variable or replace the placeholder.\")\n\nclient = Client(access_token=access_token, environment=environment)\n\ntry:\n    # Create a new customer\n    customer = client.customers.create(\n        params={'email': 'jane.doe@example.com', 'given_name': 'Jane', 'family_name': 'Doe'}\n    )\n    print(f\"Created customer: {customer.id} - {customer.email}\")\n\n    # List payments (demonstrates fetching data)\n    payments_list = client.payments.list()\n    print(f\"\\nFirst 5 payments (total: {len(payments_list.records)}):\")\n    for i, payment in enumerate(payments_list.records[:5]):\n        print(f\"  - Payment ID: {payment.id}, Amount: {payment.amount}, Currency: {payment.currency}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure that your Billing Request creation logic includes `constraints` with a `max_amount_per_payment` field when initiating PayTo `mandate_request`s.","message":"As of v3.1.0, the `constraints[max_amount_per_payment]` field became required when creating Billing Requests that include a PayTo `mandate_request`.","severity":"breaking","affected_versions":">=3.1.0"},{"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.","message":"Version 3.2.0 stopped exposing the API for creating negative balance limits.","severity":"deprecated","affected_versions":">=3.2.0"},{"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.","message":"Using the older `gocardless` library for new integrations will connect to the legacy API, which is not compatible with GoCardless Pro.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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).","error":"gocardless_pro.errors.InvalidApiUsageException: [400] Validation Failed"},{"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.","cause":"The provided `access_token` is either missing, invalid, expired, or does not have the necessary permissions for the requested action.","error":"gocardless_pro.errors.GoCardlessProError: [401] Authentication Failed"},{"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.","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.","error":"gocardless_pro.errors.ApiConnectionException: Network error."},{"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.","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.","error":"gocardless_pro.errors.MalformedResponseException: Unexpected non-JSON response."}]}