### Install GoCardless Python Client

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Install the GoCardless Pro Python client library using pip.

```bash
$ pip install gocardless_pro
```

--------------------------------

### Customers Service Example

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/base-service.md

Demonstrates the methods available for managing customers, including create, list, and get operations, inheriting from the base service.

```APIDOC
## POST /customers

### Description
Creates a new customer.

### Method
POST

### Endpoint
/customers

### Parameters
#### Request Body
- **params** (object) - Optional - Parameters for customer creation.
- **headers** (object) - Optional - Custom headers for the request.

### Response
#### Success Response (200)
- **response** (object) - The created customer object.

## GET /customers

### Description
Retrieves a list of customers.

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering or pagination.
- **headers** (object) - Optional - Custom headers for the request.

### Response
#### Success Response (200)
- **response** (object) - A list of customer objects.

## GET /customers/:identity

### Description
Retrieves a specific customer by their identity.

### Method
GET

### Endpoint
/customers/:identity

### Parameters
#### Path Parameters
- **identity** (string) - Required - The unique identifier of the customer.
#### Query Parameters
- **params** (object) - Optional - Parameters for the request.
- **headers** (object) - Optional - Custom headers for the request.

### Response
#### Success Response (200)
- **response** (object) - The requested customer object.
```

--------------------------------

### Install GoCardless Pro Python SDK

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/README.md

Install the GoCardless Pro Python SDK using pip. This is the first step to integrating with GoCardless.

```bash
pip install gocardless-pro
```

--------------------------------

### Get Payment Example

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/payments-service.md

Example of how to retrieve a payment by its ID using the GoCardless Pro Python client.

```APIDOC
## Get Payment

### Description
Retrieves a payment by its ID.

### Method
`client.payments.get(payment_id)`

### Parameters
#### Path Parameters
- **payment_id** (str) - Required - The unique identifier of the payment.

### Request Example
```python
payment = client.payments.get('PM123')
print(f"Amount: {payment.amount} {payment.currency}")
print(f"Status: {payment.status}")
print(f"Reference: {payment.reference}")
```

### Response
#### Success Response (200)
Returns a Payment object with details about the payment.

- **id** (str) - Payment ID (unique identifier)
- **amount** (int) - Payment amount in minor units
- **amount_refunded** (int) - Amount refunded (in minor units)
- **currency** (str) - ISO 4217 currency code
- **status** (str) - Payment status (see Status Values below)
- **reference** (str) - Unique payment reference
- **description** (str) - Payment description
- **charge_date** (str) - Charge date in YYYY-MM-DD format
- **created_at** (str) - Creation timestamp (ISO 8601)
- **retry_if_possible** (bool) - Whether to auto-retry on failure
- **faster_ach** (bool) - Whether Faster ACH scheme used (US)
- **scheme** (str) - Payment scheme used (bacs, sepa_core, etc.)
- **metadata** (dict) - Custom metadata
- **fx** (object) - Foreign exchange details (if applicable)
  - **fx.exchange_rate** (float) - Actual exchange rate used
  - **fx.estimated_exchange_rate** (float) - Estimated rate before payment
- **fx_amount** (int) - Amount in FX currency
- **fx_currency** (str) - FX target currency
- **links** (object) - Resource links
  - **links.mandate** (str) - ID of associated mandate
  - **links.creditor** (str) - ID of associated creditor
  - **links.instalment_schedule** (str) - ID of instalment schedule (if applicable)
- **api_response** (ApiResponse) - Underlying API response object
- **attributes** (dict) - Raw attributes dict

### Status Values

| Status |
|---| 
| `pending_submission` |
| `submitted` |
| `paid` |
| `failed` |
| `cancelled` |
| `charged_back` |
| `refunded` |
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Install the necessary development dependencies for the project using pip.

```bash
pip install -r requirements-dev.txt
```

--------------------------------

### Create, List, Get, Update, and Cancel Instalment Schedules

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Manage instalment schedules by creating them with specific dates or schedules, listing existing ones, retrieving a single schedule, updating it, or cancelling it.

```python
# Create (with dates)
client.instalment_schedules.create_with_dates(params={...})
```

```python
# Create (with schedule)
client.instalment_schedules.create_with_schedule(params={...})
```

```python
# List instalment schedules
client.instalment_schedules.list(params={...})
```

```python
# Iterate through all instalment_schedules
client.instalment_schedules.all(params={...})
```

```python
# Get a single instalment schedule
client.instalment_schedules.get('IS123', params={...})
```

```python
# Update an instalment schedule
client.instalment_schedules.update('IS123', params={...})
```

```python
# Cancel an instalment schedule
client.instalment_schedules.cancel('IS123', params={...})
```

--------------------------------

### Manage Outbound Payments

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Provides examples for creating, withdrawing, cancelling, approving, retrieving, listing, iterating, updating, and getting statistics for outbound payments. The client must be initialized.

```python
# Create an outbound payment
client.outbound_payments.create(params={...})
```

```python
# Create a withdrawal outbound payment
client.outbound_payments.withdraw(params={...})
```

```python
# Cancel an outbound payment
client.outbound_payments.cancel('OUT123', params={...})
```

```python
# Approve an outbound payment
client.outbound_payments.approve('OUT123', params={...})
```

```python
# Get an outbound payment
client.outbound_payments.get('OUT123', params={...})
```

```python
# List outbound payments
client.outbound_payments.list(params={...})
```

```python
# Iterate through all outbound_payments
client.outbound_payments.all(params={...})
```

```python
# Update an outbound payment
client.outbound_payments.update('OUT123', params={...})
```

```python
# Outbound payment statistics
client.outbound_payments.stats(params={...})
```

--------------------------------

### Manage Payouts

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Examples for listing, iterating, retrieving, and updating payouts. The GoCardless client must be initialized.

```python
# List payouts
client.payouts.list(params={...})
```

```python
# Iterate through all payouts
client.payouts.all(params={...})
```

```python
# Get a single payout
client.payouts.get('PO123', params={...})
```

```python
# Update a payout
client.payouts.update('PO123', params={...})
```

--------------------------------

### Manage Payment Accounts

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Examples for retrieving, listing, and iterating through payment accounts. The GoCardless client must be initialized.

```python
# Get a single payment account details
client.payment_accounts.get('BA123', params={...})
```

```python
# List payment accounts
client.payment_accounts.list(params={...})
```

```python
# Iterate through all payment_accounts
client.payment_accounts.all(params={...})
```

--------------------------------

### Manage Payer Authorisations

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Examples for retrieving, creating, updating, submitting, and confirming payer authorisations. Ensure the client is initialized.

```python
# Get a single Payer Authorisation
client.payer_authorisations.get('PA123', params={...})
```

```python
# Create a Payer Authorisation
client.payer_authorisations.create(params={...})
```

```python
# Update a Payer Authorisation
client.payer_authorisations.update('PA123', params={...})
```

```python
# Submit a Payer Authorisation
client.payer_authorisations.submit('PA123', params={...})
```

```python
# Confirm a Payer Authorisation
client.payer_authorisations.confirm('PA123', params={...})
```

--------------------------------

### Manage Payments

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Examples for creating, listing, iterating, retrieving, updating, cancelling, and retrying payments. Ensure the client is initialized.

```python
# Create a payment
client.payments.create(params={...})
```

```python
# List payments
client.payments.list(params={...})
```

```python
# Iterate through all payments
client.payments.all(params={...})
```

```python
# Get a single payment
client.payments.get('PM123', params={...})
```

```python
# Update a payment
client.payments.update('PM123', params={...})
```

```python
# Cancel a payment
client.payments.cancel('PM123', params={...})
```

```python
# Retry a payment
client.payments.retry('PM123', params={...})
```

--------------------------------

### List Balances

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Example of how to list balances using the GoCardless client. Specific parameters for the list method are indicated by {...}.

```python
# List balances
client.balances.list(params={...})
```

--------------------------------

### Manage Outbound Payment Imports

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Examples for creating, retrieving, listing, and iterating through outbound payment imports. Ensure the GoCardless client is properly initialized.

```python
# Create an outbound payment import
client.outbound_payment_imports.create(params={...})
```

```python
# Get an outbound payment import
client.outbound_payment_imports.get('IM123', params={...})
```

```python
# List outbound payment imports
client.outbound_payment_imports.list(params={...})
```

```python
# Iterate through all outbound_payment_imports
client.outbound_payment_imports.all(params={...})
```

--------------------------------

### Activate Mandate and Create First Payment

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/mandates-service.md

This example shows how to retrieve a mandate and create a payment based on its current status. Payments can be created immediately if the mandate is active, or queued if pending submission.

```python
# Get mandate
mandate = client.mandates.get('MD123')

if mandate.status == 'active':
    # Mandate is active, can charge immediately
    payment = client.payments.create({
        'amount': 1000,
        'currency': 'GBP',
        'reference': 'FIRST-PAYMENT',
        'links': {
            'mandate': mandate.id
        }
    })
    print(f"Created payment: {payment.id}")
elif mandate.status == 'pending_submission':
    # Still pending, payment will charge after activation
    payment = client.payments.create({
        'amount': 1000,
        'currency': 'GBP',
        'reference': 'QUEUED-PAYMENT',
        'links': {
            'mandate': mandate.id
        }
    })
    print(f"Payment queued for activation")
else:
    print(f"Mandate not ready: {mandate.status}")
```

--------------------------------

### Create Mandate PDF

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Use this snippet to create a mandate PDF. No specific setup is required beyond initializing the client.

```python
# Create a mandate PDF
client.mandate_pdfs.create(params={...})
```

--------------------------------

### client.funds_availabilities

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Checks funds availability. The available method is `get()`.

```APIDOC
## client.funds_availabilities

### Description
Checks the availability of funds.

### Methods
- `get()`
```

--------------------------------

### Refund Resource Usage in Python

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/resource-types.md

Illustrates how to get a refund by its ID and display its amount and status.

```python
refund = client.refunds.get('RF123')
print(f"Amount: {refund.amount}")
print(f"Status: {refund.status}")
```

--------------------------------

### client.instalment_schedules

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Manages instalment schedules. Users can list, retrieve, create, and cancel schedules.

```APIDOC
## client.instalment_schedules

### Description
Manages instalment schedules. Allows listing, retrieving, creating, and cancelling schedules.

### Methods
- `list()`
- `get()`
- `create()`
- `cancel()`
```

--------------------------------

### Get a Customer

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/customers-service.md

Retrieve a customer by their ID. This is useful for fetching existing customer details.

```python
customer = client.customers.get('CU123')
print(customer.id)
print(customer.given_name)
print(customer.email)
```

--------------------------------

### Initialize Client for Live Environment

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Use the live environment for production transactions. Ensure thorough testing in sandbox first.

```python
client = Client(
    access_token='YOUR_LIVE_TOKEN',
    environment='live'
)
# Base URL: https://api.gocardless.com
```

--------------------------------

### Export Customer List to CSV

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/customers-service.md

Export a list of all customers to a CSV file. This example specifies the fields to be written and iterates through customers in batches of 100.

```python
import csv

# Export all customers to CSV
with open('customers.csv', 'w', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=[
        'id', 'given_name', 'family_name', 'email', 'country_code', 'created_at'
    ])
    writer.writeheader()
    
    for customer in client.customers.all(params={'limit': 100}):
        writer.writerow({
            'id': customer.id,
            'given_name': customer.given_name,
            'family_name': customer.family_name,
            'email': customer.email,
            'country_code': customer.country_code,
            'created_at': customer.created_at
        })
```

--------------------------------

### Initialize GoCardless Pro Client

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/00_START_HERE.txt

Initialize the GoCardless Pro client with your access token and environment. Ensure you replace 'TOKEN' with your actual access token.

```python
from gocardless_pro import Client
client = Client(access_token='TOKEN', environment='sandbox')
```

--------------------------------

### Manage Payout Items

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

This snippet demonstrates how to get all payout items within a single payout and iterate through them. Ensure the client is initialized.

```python
# Get all payout items in a single payout
client.payout_items.list(params={...})
```

```python
# Iterate through all payout_items
client.payout_items.all(params={...})
```

--------------------------------

### Initialize GoCardless Client with Configuration

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Configure the GoCardless client with an access token, environment, and idempotency settings. All services created from this client will inherit these configurations.

```python
client = Client(
    access_token='TOKEN',
    environment='sandbox',
    raise_on_idempotency_conflict=False
)

# All services use the same configuration
customers_service = client.customers  # Gets client's config
payments_service = client.payments    # Gets client's config
mandates_service = client.mandates    # Gets client's config
```

--------------------------------

### Get Payment Details

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/payments-service.md

Retrieve a specific payment by its ID. This example shows how to access common payment attributes like amount, currency, status, and reference.

```python
payment = client.payments.get('PM123')
print(f"Amount: {payment.amount} {payment.currency}")
print(f"Status: {payment.status}")
print(f"Reference: {payment.reference}")
```

--------------------------------

### Create, List, Get, Update, and Remove Customers

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Manage customer resources using these methods. Create new customers, list existing ones with optional parameters, retrieve a single customer by ID, update customer details, or remove a customer.

```python
# Create a customer
client.customers.create(params={...})
```

```python
# List customers
client.customers.list(params={...})
```

```python
# Iterate through all customers
client.customers.all(params={...})
```

```python
# Get a single customer
client.customers.get('CU123', params={...})
```

```python
# Update a customer
client.customers.update('CU123', params={...})
```

```python
# Remove a customer
client.customers.remove('CU123', params={...})
```

--------------------------------

### Basic GoCardless Pro Python SDK Usage

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/README.md

Demonstrates initializing the GoCardless Pro Python client and performing basic operations such as creating a customer, bank account, mandate, and payment. It also shows how to list payments.

```python
from gocardless_pro import Client

# Initialize client
client = Client(
    access_token='YOUR_ACCESS_TOKEN',
    environment='sandbox'
)

# Create a customer
customer = client.customers.create({
    'given_name': 'John',
    'family_name': 'Doe',
    'email': 'john@example.com'
})

# Create a bank account for the customer
bank_account = client.customer_bank_accounts.create({
    'account_holder_name': 'John Doe',
    'account_number': '55779911',
    'branch_code': '200000',
    'country_code': 'GB',
    'currency': 'GBP',
    'links': {'customer': customer.id}
})

# Create a mandate
mandate = client.mandates.create({
    'reference': 'MANDATE-001',
    'scheme': 'bacs',
    'links': {
        'creditor': 'CR123ABC',
        'customer_bank_account': bank_account.id
    }
})

# Create a payment
payment = client.payments.create({
    'amount': 10000,  # £100 in pence
    'currency': 'GBP',
    'reference': 'PAYMENT-001',
    'links': {'mandate': mandate.id}
})

# List payments
for payment in client.payments.all():
    print(f"{payment.id}: {payment.amount} {payment.currency}")
```

--------------------------------

### Monitor Next Charge Dates

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/mandates-service.md

This example iterates through all active mandates to find the earliest possible charge date. It handles cases where no active mandates are found.

```python
# Find earliest possible charge date across active mandates
earliest_date = None

for mandate in client.mandates.all(params={
    'filters': {'status': ['active']}
}):
    if mandate.next_possible_charge_date:
        if not earliest_date or mandate.next_possible_charge_date < earliest_date:
            earliest_date = mandate.next_possible_charge_date

if earliest_date:
    print(f"Earliest possible charge date: {earliest_date}")
else:
    print("No active mandates available")
```

--------------------------------

### Initialize GoCardless Client

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/README.md

Instantiate the GoCardless Client with your access token and environment. Ensure your access token is kept secure.

```python
client = Client(
    access_token='YOUR_TOKEN',  # From GoCardless dashboard
    environment='sandbox'
)
```

--------------------------------

### Get Total Collected Amount by Status

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/payments-service.md

Calculate the total amount collected for payments with a specific status, such as 'paid'. This example demonstrates filtering payments using query parameters.

```python
total = 0
for payment in client.payments.all(params={
    'filters': {
        'status': ['paid']
    }
}):
    total += payment.amount

print(f"Total collected: £{total/100:.2f}")
```

--------------------------------

### Iterate All Mandates

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/mandates-service.md

Use the `all` method to get a paginator for iterating through all mandates. This is useful for processing a large number of mandates without managing pagination manually. The example shows how to count mandates by status.

```python
for mandate in client.mandates.all():
    print(f"Processing mandate {mandate.id}")
```

```python
status_counts = {}

for mandate in client.mandates.all():
    status = mandate.status
    status_counts[status] = status_counts.get(status, 0) + 1

for status, count in status_counts.items():
    print(f"{status}: {count} mandates")
```

--------------------------------

### Initialize Client for Sandbox Environment

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Use the sandbox environment for testing and development. It provides full feature parity without real transactions.

```python
client = Client(
    access_token='YOUR_SANDBOX_TOKEN',
    environment='sandbox'
)
# Base URL: https://api-sandbox.gocardless.com
```

--------------------------------

### Initialize GoCardless Client

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/INDEX.md

Instantiate the GoCardless client with an access token and specify the environment (e.g., 'sandbox').

```python
client = Client(access_token, environment='sandbox')
```

--------------------------------

### Instalment Schedules

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Operations for managing instalment schedules.

```APIDOC
## Create Instalment Schedule (with dates)

### Description
Creates an instalment schedule using specific dates.

### Method
`client.instalment_schedules.create_with_dates(params={...})`

## Create Instalment Schedule (with schedule)

### Description
Creates an instalment schedule based on a provided schedule.

### Method
`client.instalment_schedules.create_with_schedule(params={...})`

## List Instalment Schedules

### Description
Lists available instalment schedules.

### Method
`client.instalment_schedules.list(params={...})`

## Iterate Through All Instalment Schedules

### Description
Iterates through all instalment schedules.

### Method
`client.instalment_schedules.all(params={...})`

## Get Single Instalment Schedule

### Description
Retrieves details of a specific instalment schedule.

### Method
`client.instalment_schedules.get('IS123', params={...})`

## Update Instalment Schedule

### Description
Updates an existing instalment schedule.

### Method
`client.instalment_schedules.update('IS123', params={...})`

## Cancel Instalment Schedule

### Description
Cancels an instalment schedule.

### Method
`client.instalment_schedules.cancel('IS123', params={...})`
```

--------------------------------

### Load Configuration from JSON File

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Initialize the GoCardless Pro Client using credentials stored in a JSON configuration file. The file should contain access_token and environment details under a 'gocardless' key.

```python
import json
from gocardless_pro import Client

# Load from config file
with open('config.json', 'r') as f:
    config = json.load(f)

client = Client(
    access_token=config['gocardless']['access_token'],
    environment=config['gocardless']['environment']
)
```

```json
{
  "gocardless": {
    "access_token": "YOUR_TOKEN_HERE",
    "environment": "sandbox"
  }
}
```

--------------------------------

### Create Billing Request Template

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Define and create a new billing request template. This allows for reusable payment setup configurations.

```python
# Create a Billing Request Template
client.billing_request_templates.create(params={...})
```

--------------------------------

### Instantiate GoCardless Pro Client

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Create a Client instance with your API access token and specify the environment. Set raise_on_idempotency_conflict to False to prevent exceptions on duplicate requests.

```python
from gocardless_pro import Client

client = Client(
    access_token='YOUR_ACCESS_TOKEN',
    environment='sandbox',
    raise_on_idempotency_conflict=False
)
```

--------------------------------

### all

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/refunds-service.md

Get a paginator for iterating all refunds. This method provides an easy way to loop through all refunds without manually handling pagination.

```APIDOC
## all(params=None)

### Description
Get a paginator for iterating all refunds.

### Method
GET

### Endpoint
/refunds

### Parameters
#### Path Parameters
None

#### Query Parameters
- **params** (dict) - Optional - Query parameters including filters

#### Request Body
None

### Request Example
```json
{
  "limit": 100
}
```

### Response
#### Success Response (200)
- **Paginator[Refund]** - Iterator yielding Refund objects
```

--------------------------------

### List, Iterate, and Get Events

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve and manage event data. Use `list` for filtered results, `all` for iteration, and `get` to fetch a specific event by its ID.

```python
# List events
client.events.list(params={...})
```

```python
# Iterate through all events
client.events.all(params={...})
```

```python
# Get a single event
client.events.get('EV123', params={...})
```

--------------------------------

### Initialize GoCardless Pro Python Client

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Instantiate the GoCardless Pro Python client with your API access token and either a predefined environment or a custom base URL. The access token is mandatory. Use the sandbox environment for testing and the live environment for production.

```python
from gocardless_pro import Client

# Initialize with sandbox environment
client = Client(
    access_token='YOUR_ACCESS_TOKEN',
    environment='sandbox'
)

# Initialize with custom base URL
client = Client(
    access_token='YOUR_ACCESS_TOKEN',
    base_url='https://api-sandbox.gocardless.com'
)
```

--------------------------------

### Initialise Billing Request Flow

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Start or initialise an existing billing request flow. This often triggers the customer-facing part of the process.

```python
# Initialise a Billing Request Flow
client.billing_request_flows.initialise('BRF123', params={...})
```

--------------------------------

### Perform GET Request

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/api-client.md

Use the `get` method to retrieve data from a specific API endpoint. You can include query parameters to filter or paginate results. Ensure the path is correctly formatted.

```python
response = api_client.get('/customers', params={'limit': 10})
```

--------------------------------

### Getting Rate Limit Reset Time

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/rate-limit.md

Explains how to get the Unix timestamp indicating when the current rate limit window will reset. It also shows how to convert this timestamp to a human-readable date and time.

```python
reset_ts = client.rate_limit['ratelimit-reset']
print(f"Rate limit resets at: {reset_ts}")

import datetime
reset_time = datetime.datetime.fromtimestamp(int(reset_ts))
print(f"Human-readable: {reset_time}")
```

--------------------------------

### Get Event

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieves a specific event by its ID.

```APIDOC
## GET /events/{id}

### Description
Retrieves a specific event by its ID.

### Method
GET

### Endpoint
/events/{id}

### Response
#### Success Response (200)
Event object
```

--------------------------------

### Load Configuration from Environment Variable

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Configure the GoCardless Pro Client by loading the access token from the GOCARDLESS_ACCESS_TOKEN environment variable. Ensure the variable is set to avoid a ValueError.

```python
import os
from gocardless_pro import Client

# Load from environment
access_token = os.environ.get('GOCARDLESS_ACCESS_TOKEN')
if not access_token:
    raise ValueError("GOCARDLESS_ACCESS_TOKEN environment variable not set")

client = Client(
    access_token=access_token,
    environment='sandbox'
)
```

--------------------------------

### Get Refund

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/refunds-service.md

Retrieves a specific refund by its ID.

```APIDOC
## Get Refund

### Description
Retrieves a specific refund by its ID.

### Method
GET

### Endpoint
`/refunds/:refund_id}`

### Parameters
#### Path Parameters
- **refund_id** (string) - Required - The ID of the refund to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Refund ID.
- **amount** (integer) - Refund amount in minor units.
- **currency** (string) - ISO 4217 currency code.
- **status** (string) - Refund status.
- **created_at** (string) - Creation timestamp (ISO 8601).

### Request Example
```python
refund = client.refunds.get('RF123')
print(f"Amount: {refund.amount} {refund.currency}")
```
```

--------------------------------

### Get Webhook

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieves the details of a specific webhook by its ID.

```APIDOC
## GET /webhooks/{id}

### Description
Retrieves a specific webhook by its ID.

### Method
GET

### Endpoint
/webhooks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook.
```

--------------------------------

### Handle GoCardless Pro Errors

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/00_START_HERE.txt

Implement error handling for API requests. This example shows how to catch specific validation and rate limit errors, printing informative messages.

```python
from gocardless_pro import errors
try:
    payment = client.payments.create(params)
except errors.ValidationFailedError as e:
    print(f"Validation error: {e}")
except errors.RateLimitError:
    print(f"Rate limited. Reset: {client.rate_limit['ratelimit-reset']}")
```

--------------------------------

### Get Payout

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieves the details of a specific payout by its ID.

```APIDOC
## GET /payouts/{id}

### Description
Retrieves a specific payout by its ID.

### Method
GET

### Endpoint
/payouts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the payout.
```

--------------------------------

### Get Creditor

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieves the details of a specific creditor by its ID.

```APIDOC
## GET /creditors/{id}

### Description
Retrieves a specific creditor by its ID.

### Method
GET

### Endpoint
/creditors/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the creditor.
```

--------------------------------

### client.logos

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Offers a logo service. Users can list and get logos.

```APIDOC
## client.logos

### Description
Provides access to logos.

### Methods
- `list()`
- `get()`
```

--------------------------------

### Redirect Flows

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Methods for managing redirect flows, including getting and completing them.

```APIDOC
## Get Redirect Flow

### Description
Retrieves details for a specific redirect flow.

### Method
GET

### Endpoint
/redirect_flows/:redirect_flow_id

### Parameters
#### Path Parameters
- **redirect_flow_id** (string) - Required - The ID of the redirect flow to retrieve.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

### Response
#### Success Response (200)
Details of the redirect flow.

## Complete Redirect Flow

### Description
Completes a redirect flow, typically after user authorization.

### Method
POST

### Endpoint
/redirect_flows/:redirect_flow_id/complete

### Parameters
#### Path Parameters
- **redirect_flow_id** (string) - Required - The ID of the redirect flow to complete.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

### Response
#### Success Response (200)
Details of the completed redirect flow.
```

--------------------------------

### Create Customer

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Create a new customer using the client. Idempotency keys are automatically added to prevent duplicate resource creation.

```python
# Create a new customer. We automatically add idempotency keys to requests to create
# resources, stopping duplicates accidentally getting created if something goes wrong
# with the API (e.g. networking problems) - see https://developer.gocardless.com/api
# -reference/#making-requests-idempotency-keys for details
customer = client.customers.create(params={'email': 'jane@example.com'})
```

--------------------------------

### Client Constructor

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Instantiate a client object with your access token and environment. This is the main entry point for interacting with the GoCardless Pro API.

```APIDOC
## Client Constructor

### Description
Instantiate a client object with your access token and environment, then use the resource service properties to access the API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **access_token** (str) - Required - GoCardless API access token from your dashboard (https://manage.gocardless.com/organisation/access-tokens)
- **environment** (str) - Optional - One of `'sandbox'` or `'live'`. Cannot be used with `base_url`
- **base_url** (str) - Optional - Custom base URL for the API. Use this to override the default environment URL if needed
- **raise_on_idempotency_conflict** (bool) - Optional - If True, raise `IdempotentCreationConflictError` on duplicate creation attempts. If False (default), fetch the conflicting resource instead

### Raises
- `ValueError` - If `access_token` is not provided
- `ValueError` - If neither `environment` nor `base_url` is provided
- `ValueError` - If `environment` is not one of the valid options

### Request Example
```python
from gocardless_pro import Client

# Initialize with sandbox environment
client = Client(
    access_token='YOUR_ACCESS_TOKEN',
    environment='sandbox'
)

# Initialize with custom base URL
client = Client(
    access_token='YOUR_ACCESS_TOKEN',
    base_url='https://api-sandbox.gocardless.com'
)
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Get a Single Webhook

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve details for a specific webhook using its ID.

```python
client.webhooks.get('WB123', params={...})
```

--------------------------------

### Get a Single Subscription

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve details for a specific subscription using its ID.

```python
client.subscriptions.get('SB123', params={...})
```

--------------------------------

### Get a Single Scheme Identifier

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve a specific scheme identifier by its ID.

```python
client.scheme_identifiers.get('SU123', params={...})
```

--------------------------------

### Client Configuration for Services in Python

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/base-service.md

Shows how to configure a GoCardless Client with access token, environment, and service-wide settings. These settings, like max_network_retries and retry_delay_in_seconds, are automatically applied to all service instances created by the client.

```python
client = Client(
    access_token='TOKEN',
    environment='sandbox',
    # These are passed to all service instances:
    # max_network_retries=3
    # retry_delay_in_seconds=0.5
    raise_on_idempotency_conflict=False  # Configurable here
)

# All services use these settings:
customer = client.customers.create(...)  # Uses max_network_retries=3, etc.
payment = client.payments.create(...)    # Uses same settings
```

--------------------------------

### Create Customer SDK Method

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Call this method from the GoCardless Pro Python SDK to create a customer. Pass the customer details as a dictionary.

```python
client.customers.create(params)
```

--------------------------------

### Get a Single Refund

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve details for a specific refund using its ID.

```python
client.refunds.get('RF123', params={...})
```

--------------------------------

### Get Mandate

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieve a specific mandate object using its unique identifier.

```http
GET /mandates/{id}
```

--------------------------------

### Get Payment

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieve a specific payment object using its unique identifier.

```http
GET /payments/{id}
```

--------------------------------

### Create Webhook SDK

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Use the SDK to create a webhook. Pass the required parameters to the create method.

```python
client.webhooks.create(params)
```

--------------------------------

### Get Single Block

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve the details of a specific block using its identifier.

```python
# Get a single block
client.blocks.get('BLC123', params={...})
```

--------------------------------

### Create Customer and Bank Account

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/customers-service.md

First create a customer, then create a bank account linked to that customer. Ensure you have the customer ID before creating the bank account.

```python
# First create the customer
customer = client.customers.create({
    'given_name': 'John',
    'family_name': 'Doe',
    'email': 'john@example.com'
})

# Then create a bank account for the customer
bank_account = client.customer_bank_accounts.create({
    'account_holder_name': 'John Doe',
    'account_number': '55779911',
    'branch_code': '200000',
    'country_code': 'GB',
    'currency': 'GBP',
    'links': {
        'customer': customer.id
    }
})
```

--------------------------------

### client.institutions

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Provides information about institutions. Users can list and get institution details.

```APIDOC
## client.institutions

### Description
Retrieves information about financial institutions.

### Methods
- `list()`
- `get()`
```

--------------------------------

### Initialize Client with Custom Base URL

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

Configure the client to use a custom base URL for advanced use cases or specific testing scenarios.

```python
client = Client(
    access_token='TOKEN',
    base_url='https://custom-api.example.com'
)
```

--------------------------------

### Get Customer Bank Account

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Retrieves a specific customer bank account by its ID.

```APIDOC
## GET /customer_bank_accounts/{id}

### Description
Retrieves a specific customer bank account by its ID.

### Method
GET

### Endpoint
/customer_bank_accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the customer bank account to retrieve

### Response
#### Success Response (200 OK)
- **customer_bank_account** (object) - The customer bank account object
```

--------------------------------

### Create a Payment

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/INDEX.md

Initiate a payment using the payments service with the required payment details.

```python
client.payments.create({...})
```

--------------------------------

### Create a Subscription

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Create a new subscription. Ensure all required parameters are provided.

```python
client.subscriptions.create(params={...})
```

--------------------------------

### List Subscriptions

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Get a list of subscriptions. Filtering and pagination can be applied using `params`.

```python
client.subscriptions.list(params={...})
```

--------------------------------

### Get Refund - GoCardless Pro Python

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Use this to retrieve a specific refund by its ID.

```python
client.refunds.get(identity)
```

--------------------------------

### Initialize ApiClient

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/api-client.md

Instantiate the ApiClient with the base URL and your access token. This client is used for making direct HTTP requests to the GoCardless API.

```python
from gocardless_pro.api_client import ApiClient

api_client = ApiClient(
    base_url='https://api-sandbox.gocardless.com',
    access_token='YOUR_ACCESS_TOKEN'
)
```

--------------------------------

### Create GoCardless Client for Sandbox Testing

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/configuration.md

This fixture creates a GoCardless client configured for the sandbox environment. It reads the access token from the GOCARDLESS_SANDBOX_TOKEN environment variable. If the token is not set, the test will be skipped. This is useful for integration tests that require interaction with the GoCardless sandbox.

```python
import os
import pytest
from gocardless_pro import Client

@pytest.fixture
def gocardless_client():
    """Create client for sandbox testing."""
    access_token = os.environ.get('GOCARDLESS_SANDBOX_TOKEN')
    if not access_token:
        pytest.skip("GOCARDLESS_SANDBOX_TOKEN not set")
    
    return Client(
        access_token=access_token,
        environment='sandbox'
    )

def test_create_customer(gocardless_client):
    """Test creating a customer."""
    customer = gocardless_client.customers.create({
        'given_name': 'Test',
        'family_name': 'Customer',
        'email': f'test-{uuid.uuid4()}@example.com'
    })
    assert customer.id is not None
    assert customer.given_name == 'Test'
```

--------------------------------

### Get Single Creditor

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve the details of a specific creditor using their unique identifier.

```python
# Get a single creditor
client.creditors.get('CR123', params={...})
```

--------------------------------

### Create Customer Bank Account - GoCardless Pro Python

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Use this to create a customer bank account. Requires account details and customer ID.

```python
client.customer_bank_accounts.create(params)
```

--------------------------------

### Get Bank Authorisation

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve details of a specific bank authorisation using its ID.

```python
# Get a Bank Authorisation
client.bank_authorisations.get('BAU123', params={...})
```

--------------------------------

### Create a Customer

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/INDEX.md

Use the customers service to create a new customer by providing the necessary details.

```python
client.customers.create({...})
```

--------------------------------

### Get Customer

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/customers-service.md

Retrieves a customer by their ID. You can then access various properties of the customer object.

```APIDOC
## Get Customer

### Description
Retrieves a customer by their ID. You can then access various properties of the customer object.

### Method
```
GET
```

### Endpoint
```
/customers/{id}
```

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.

### Request Example
```python
customer = client.customers.get('CU123')
```

### Response
#### Success Response (200)
- **id** (str) - Customer ID (unique identifier)
- **given_name** (str) - Customer's first name
- **family_name** (str) - Customer's last name
- **email** (str) - Customer's email address
- **phone_number** (str) - Customer's phone number
- **address_line1** (str) - Street address line 1
- **address_line2** (str) - Street address line 2
- **address_line3** (str) - Street address line 3
- **city** (str) - City
- **postal_code** (str) - Postal/ZIP code
- **region** (str) - Region/State/Province
- **country_code** (str) - ISO 3166-1 country code
- **company_name** (str) - Company name
- **language** (str) - ISO 639-1 language code
- **created_at** (str) - Creation timestamp (ISO 8601)
- **metadata** (dict) - Custom metadata
- **danish_identity_number** (str) - Danish CPR number (if provided)
- **swedish_identity_number** (str) - Swedish personal number (if provided)
- **api_response** (ApiResponse) - Underlying API response object
- **attributes** (dict) - Raw attributes dict

### Response Example
```python
# Assuming customer object is retrieved
print(customer.id)
print(customer.given_name)
print(customer.email)
```
```

--------------------------------

### List Webhooks SDK

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Use the SDK to list existing webhooks. Optional parameters can be passed.

```python
client.webhooks.list(params)
```

--------------------------------

### Create a Customer

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/00_START_HERE.txt

Create a new customer by providing their given name, family name, and email address. This is a prerequisite for creating mandates and payments.

```python
customer = client.customers.create({
    'given_name': 'John',
    'family_name': 'Doe',
    'email': 'john@example.com'
})
```

--------------------------------

### Get Payment by ID

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/payments-service.md

Retrieve the details of a single payment using its unique identifier.

```APIDOC
## `get(identity, params=None, headers=None)`

Retrieve a single payment by ID.

```python
payment = client.payments.get('PM123ABC')
print(f"Amount: {payment.amount} {payment.currency}")
print(f"Status: {payment.status}")
```

### Parameters:

- `identity` (str, Required) - Payment ID (begins with "PM")
- `params` (dict, Optional) - Query parameters
- `headers` (dict, Optional) - Custom HTTP headers

### Returns:

- `Payment` - The requested payment resource

### Raises:

- `ApiError` with 404 - If payment not found
```

--------------------------------

### List and Iterate Negative Balance Limits

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

This snippet shows how to list all negative balance limits or iterate through them. Ensure the client is initialized.

```python
# List negative balance limits
client.negative_balance_limits.list(params={...})
```

```python
# Iterate through all negative_balance_limits
client.negative_balance_limits.all(params={...})
```

--------------------------------

### Get a Single Tax Rate

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/README.rst

Retrieve details for a specific tax rate using its ID.

```python
client.tax_rates.get('GB_VAT_1', params={...})
```

--------------------------------

### Get Event Details

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/resource-types.md

Retrieve a specific event by its ID. Useful for inspecting API changes.

```python
event = client.events.get('EV123')
print(f"Action: {event.action}")
print(f"Resource: {event.resource_type}")
```

--------------------------------

### Iterate All Customers

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/pagination.md

Demonstrates iterating through all customers using the client.*.all() convenience method and the equivalent manual Paginator usage.

```python
# Using client.*.all() convenience method
for customer in client.customers.all():
    print(f"{customer.given_name} {customer.family_name}")
```

```python
# Equivalent manual usage
from gocardless_pro.paginator import Paginator
paginator = Paginator(client.customers, params={})
for customer in paginator:
    print(f"{customer.given_name} {customer.family_name}")
```

--------------------------------

### Payment Resource Usage in Python

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/resource-types.md

Shows how to fetch a payment by its ID and print its amount, currency, status, and refunded amount.

```python
payment = client.payments.get('PM123')
print(f"Amount: {payment.amount} {payment.currency}")
print(f"Status: {payment.status}")
print(f"Refunded: {payment.amount_refunded}")
```

--------------------------------

### List Creditors SDK

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Use the SDK to list existing creditors. Optional parameters can be passed.

```python
client.creditors.list(params)
```

--------------------------------

### client.transferred_mandates

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Provides access to transferred mandate information. Users can list and get transferred mandates.

```APIDOC
## client.transferred_mandates

### Description
Provides access to transferred mandate information.

### Methods
- `list()`
- `get()`
```

--------------------------------

### Create Payout SDK

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/endpoints.md

Use the SDK to create a payout. Pass the required parameters to the create method.

```python
client.payouts.create(params)
```

--------------------------------

### client.exports

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Offers data export services. Users can list, get, and create data exports.

```APIDOC
## client.exports

### Description
Manages data export services. Allows listing, retrieving, and creating data exports.

### Methods
- `list()`
- `get()`
- `create()`
```

--------------------------------

### client.currency_exchange_rates

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/client.md

Provides access to currency exchange rates. Users can list and get exchange rates.

```APIDOC
## client.currency_exchange_rates

### Description
Retrieves currency exchange rates.

### Methods
- `list()`
- `get()`
```

--------------------------------

### List Resources with Parameters

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/INDEX.md

Retrieve a list of resources, such as customers, by passing parameters to the list method.

```python
client.customers.list(params)
```

--------------------------------

### ApiClient.get

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/api-reference/api-client.md

Performs a GET request to the specified path with optional query parameters and custom headers.

```APIDOC
## GET /path

### Description
Performs a GET request to the specified path with optional query parameters and custom headers.

### Method
GET

### Endpoint
[path]

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Dictionary of query string parameters
- **headers** (dict) - Optional - Custom HTTP headers to merge with default headers

### Request Example
```python
response = api_client.get('/customers', params={'limit': 10})
```

### Response
#### Success Response (200)
- **response** (requests.Response) - Raw response object from the requests library

### Raises
- `ApiError` (or subclass) - If status code >= 400
- `MalformedResponseError` - If response body cannot be parsed as JSON
```

--------------------------------

### Customer Resource Usage in Python

Source: https://github.com/gocardless/gocardless-pro-python/blob/master/_autodocs/resource-types.md

Demonstrates how to retrieve a customer by ID and access its properties like name, email, and country code.

```python
customer = client.customers.get('CU123')
print(f"{customer.given_name} {customer.family_name}")
print(f"Email: {customer.email}")
print(f"Country: {customer.country_code}")
```