### Install GoCardless Pro PHP Client

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

Install the GoCardless Pro PHP client using Composer. Ensure Composer is installed first.

```bash
curl -sS https://getcomposer.org/installer | php
```

```bash
php composer.phar require gocardless/gocardless-pro
```

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

### Create Billing Request with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Set up a billing request to collect customer details and initiate payment setup. This example shows creating a request specifically for mandate setup with the BACS scheme.

```php
<?php
// Create a billing request for mandate setup
$billingRequest = $client->billingRequests()->create([
    'params' => [
        'mandate_request' => [
            'scheme' => 'bacs'
        ]
    ]
]);

echo "Billing Request ID: " . $billingRequest->id . "\n";
// Output: Billing Request ID: BRQ000XXXXXXXXX
```

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

### List Resources (GET Request)

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

Make a GET request to list resources using the `list` method. Options for URL parameters can be passed as an array.

```php
$client->customers()->list();
```

```php
$customers = $client->customers()->list(['params' => ['limit' => 400]]);
```

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

### List and Get Payouts

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Demonstrates how to list all payouts with optional parameters and retrieve details for a single payout. Requires the GoCardless Pro client to be initialized.

```php
<?php
// List payouts
$payouts = $client->payouts()->list(['params' => ['limit' => 20]]);

foreach ($payouts->records as $payout) {
    echo $payout->id . ": " . $payout->amount . " " . $payout->currency . "\n";
    echo "Status: " . $payout->status . "\n";
    echo "Arrival date: " . $payout->arrival_date . "\n";
}

// Get a single payout
$payout = $client->payouts()->get('PO000XXXXXXXXX');
```

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

### Handle GoCardless Webhooks

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Provides a complete example for setting up a webhook endpoint to receive and validate real-time event notifications from GoCardless. Requires setting the GOCARDLESS_WEBHOOK_ENDPOINT_SECRET environment variable and implementing handler functions for different event types.

```php
<?php
// Webhook endpoint handler
$webhook_endpoint_secret = getenv('GOCARDLESS_WEBHOOK_ENDPOINT_SECRET');

// Get the raw request body and signature header
$request_body = file_get_contents('php://input');
$headers = getallheaders();
$signature_header = $headers['Webhook-Signature'];

try {
    // Parse and validate the webhook
    $events = \GoCardlessPro\Webhook::parse(
        $request_body,
        $signature_header,
        $webhook_endpoint_secret
    );

    foreach ($events as $event) {
        echo "Event ID: " . $event->id . "\n";
        echo "Resource type: " . $event->resource_type . "\n";
        echo "Action: " . $event->action . "\n";

        // Handle different event types
        switch ($event->resource_type) {
            case 'payments':
                handlePaymentEvent($event);
                break;
            case 'mandates':
                handleMandateEvent($event);
                break;
            case 'subscriptions':
                handleSubscriptionEvent($event);
                break;
        }
    }

    // Acknowledge receipt
    header('HTTP/1.1 200 OK');

} catch (\GoCardlessPro\Core\Exception\InvalidSignatureException $e) {
    // Invalid signature - reject the webhook
    header('HTTP/1.1 498 Invalid Token');
    exit;
}

function handlePaymentEvent($event) {
    switch ($event->action) {
        case 'confirmed':
            // Payment was successfully collected
            $paymentId = $event->links->payment;
            echo "Payment $paymentId confirmed\n";
            break;
        case 'failed':
            // Payment failed - notify customer
            echo "Payment failed: " . $event->details->cause . "\n";
            break;
        case 'charged_back':
            // Customer disputed the payment
            echo "Payment charged back\n";
            break;
    }
}

function handleMandateEvent($event) {
    switch ($event->action) {
        case 'cancelled':
            // Mandate was cancelled - suspend service
            echo "Mandate cancelled\n";
            break;
        case 'active':
            // Mandate is now active - ready for payments
            echo "Mandate activated\n";
            break;
    }
}

function handleSubscriptionEvent($event) {
    switch ($event->action) {
        case 'payment_created':
            // New payment created from subscription
            echo "Subscription payment created\n";
            break;
        case 'cancelled':
            // Subscription was cancelled
            echo "Subscription cancelled\n";
            break;
    }
}

// Validate signature without parsing (useful for logging)
$isValid = \GoCardlessPro\Webhook::isSignatureValid(
    $request_body,
    $signature_header,
    $webhook_endpoint_secret
);
```

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

### Get Single Resource (GET Request)

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

Retrieve a single resource by its ID using the `get` method. Optional parameters can be provided in an options array.

```php
$customer = $client->customers()->get($customer_id);
echo $customer->given_name;
```

```php
$client->customers()->get($customer_id, ['params' => ['some_flag' => true]]);
```

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

### Require Composer Autoloader

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

Include Composer's autoloader to use the installed GoCardless Pro PHP client library.

```php
require 'vendor/autoload.php';
```

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

### Filter Events by Type with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Filter events to retrieve only those related to a specific resource type and action. This example shows how to get failed payment events.

```php
// Filter events by type
$paymentEvents = $client->events()->list([
    'params' => [
        'resource_type' => 'payments',
        'action'        => 'failed'
    ]
]);
```

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

### Refunds API

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Create, get, and list refunds for payments. Refunds can be for full or partial amounts.

```APIDOC
## Refunds

Create refunds for payments that have been collected. Refunds can be for partial or full amounts.

### Create Refund

**Method**: POST
**Endpoint**: `/refunds`

**Parameters**:

#### Request Body
- **params** (object) - Required - Parameters for creating the refund.
  - **amount** (integer) - Required - Refund amount in pence/cents.
  - **total_amount_confirmation** (integer) - Required - Confirm total amount.
  - **links** (object) - Required - Links to related resources.
    - **payment** (string) - Required - The ID of the payment to refund.
  - **metadata** (object) - Optional - Additional metadata.
    - **reason** (string) - Optional - Reason for the refund.

### Request Example
```json
{
  "params": {
    "amount": 1500,
    "total_amount_confirmation": 1500,
    "links": {
      "payment": "PM000XXXXXXXXX"
    },
    "metadata": {
      "reason": "Customer request"
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created refund.
- **status** (string) - The status of the refund.

#### Response Example
```json
{
  "id": "RF000XXXXXXXXX",
  "status": "created"
}
```

### Get Refund

**Method**: GET
**Endpoint**: `/refunds/{id}`

### List Refunds for a Payment

**Method**: GET
**Endpoint**: `/refunds`

**Parameters**:

#### Query Parameters
- **payment** (string) - Required - The ID of the payment to list refunds for.

### Response Example (List)
```json
{
  "records": [
    {
      "id": "RF000XXXXXXXXX",
      "amount": 1500,
      "currency": "GBP"
    }
  ]
}
```
```

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

### Get a Refund with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve details of a specific refund using its ID. This is useful for checking the status or details of a previously created refund.

```php
// Get a refund
$refund = $client->refunds()->get('RF000XXXXXXXXX');
```

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

### Get a Mandate

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a specific mandate by its ID. Useful for checking its status or next charge date.

```php
<?php
// Get a mandate
$mandate = $client->mandates()->get('MD000XXXXXXXXX');
echo "Next possible charge date: " . $mandate->next_possible_charge_date . "\n";
```

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

### Get a Single Event with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve details of a specific event using its ID. This allows you to inspect the details of a particular change in your GoCardless account.

```php
// Get a single event
$event = $client->events()->get('EV000XXXXXXXXX');
echo "Event action: " . $event->action . "\n";
echo "Resource ID: " . $event->links->payment . "\n";
```

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

### Get a Customer Bank Account

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a specific customer bank account by its ID. This is useful for checking account details or status.

```php
<?php
// Get a bank account
$bankAccount = $client->customerBankAccounts()->get('BA000XXXXXXXXX');
echo "Account ending: " . $bankAccount->account_number_ending . "\n";
```

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

### Get Billing Request Status with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve the current status of a billing request using its ID. This is useful for checking if the customer has completed the necessary steps.

```php
// Get billing request status
$billingRequest = $client->billingRequests()->get('BRQ000XXXXXXXXX');
echo "Status: " . $billingRequest->status . "\n";
```

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

### Access API Response Details

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

Access the `api_response` attribute from a resource or ListResponse object to get details like status code, headers, and body.

```php
$api_response = $client->customers()->get($customer_id)->api_response;
echo $api_response->status_code;
```

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

### Initialize GoCardless Pro Client

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

Create a GoCardlessPro\Client instance using your access token and the desired environment (SANDBOX or LIVE). It is recommended to store the access token as an environment variable.

```php
$access_token = getenv('GC_ACCESS_TOKEN');
$client = new \GoCardlessPro\Client([
  'access_token' => $access_token,
  'environment'  => \GoCardlessPro\Environment::SANDBOX
]);
```

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

### Initialize GoCardless Pro PHP Client

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Initialize the client with an access token and environment. Store access tokens securely using environment variables. The timeout can be optionally configured.

```php
<?php
require 'vendor/autoload.php';

// Initialize the client with your access token
$access_token = getenv('GC_ACCESS_TOKEN');
$client = new \GoCardlessPro\Client([
    'access_token' => $access_token,
    'environment'  => \GoCardlessPro\Environment::SANDBOX  // Use LIVE for production
]);
```

```php
// Optional: Configure timeout (in seconds)
$client = new \GoCardlessPro\Client([
    'access_token' => $access_token,
    'environment'  => \GoCardlessPro\Environment::LIVE,
    'timeout'      => 30
]);
```

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

### Create a Monthly Subscription with PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Set up a recurring subscription that bills the customer monthly. Specify the amount, currency, interval, and the day of the month for charging.

```php
<?php
// Create a monthly subscription
$subscription = $client->subscriptions()->create([
    'params' => [
        'amount'          => 2500,           // 25.00 GBP
        'currency'        => 'GBP',
        'name'            => 'Premium Plan',
        'interval_unit'   => 'monthly',
        'interval'        => 1,              // Every 1 month
        'day_of_month'    => 1,              // Charge on the 1st
        'links'           => [
            'mandate' => 'MD000XXXXXXXXX'
        ],
        'metadata' => [
            'plan_id' => 'premium'
        ]
    ]
]);

echo "Subscription ID: " . $subscription->id . "\n";
echo "Status: " . $subscription->status . "\n";
// Output: Subscription ID: SB000XXXXXXXXX
// Output: Status: active

```

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

### Create Subscription with Limited Payments using PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Set up a subscription that will only run for a specific number of payments. The 'count' parameter defines the total number of payments to be made.

```php
<?php
// Create a subscription with limited number of payments
$subscription = $client->subscriptions()->create([
    'params' => [
        'amount'        => 5000,
        'currency'      => 'GBP',
        'name'          => '12-Month Membership',
        'interval_unit' => 'monthly',
        'interval'      => 1,
        'count'         => 12,  // Only 12 payments
        'links'         => [
            'mandate' => 'MD000XXXXXXXXX'
        ]
    ]
]);

```

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

### Create Resource (POST Request)

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

Make a POST request to create a resource by providing the request body as the first argument. This can include parameters for the resource.

```php
$client->customers()->create([
  'params' => ['given_name' => 'Pete', 'family_name' => 'Hamilton']
]);
```

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

### Create a New Customer in GoCardless

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Create a new customer record using the client. Customer details include email, name, address, country code, and optional metadata.

```php
<?php
// Create a new customer
$customer = $client->customers()->create([
    'params' => [
        'email'        => 'user@example.com',
        'given_name'   => 'John',
        'family_name'  => 'Smith',
        'address_line1'=> '123 Main Street',
        'city'         => 'London',
        'postal_code'  => 'SW1A 1AA',
        'country_code' => 'GB',
        'metadata'     => [
            'user_id' => '12345'
        ]
    ]
]);

echo "Created customer: " . $customer->id . "\n";
```

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

### Create a One-Off Payment with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Use this to create a single payment. Ensure the mandate is active and provide all required parameters like amount, currency, and description.

```php
<?php
// Create a one-off payment
$payment = $client->payments()->create([
    'params' => [
        'amount'      => 1500,        // Amount in pence/cents (15.00 GBP)
        'currency'    => 'GBP',
        'description' => 'Invoice #12345',
        'links'       => [
            'mandate' => 'MD000XXXXXXXXX'
        ],
        'metadata' => [
            'invoice_id' => '12345'
        ]
    ]
]);

echo "Payment ID: " . $payment->id . "\n";
echo "Payment status: " . $payment->status . "\n";
echo "Charge date: " . $payment->charge_date . "\n";
// Output: Payment ID: PM000XXXXXXXXX
// Output: Payment status: pending_submission
// Output: Charge date: 2024-01-15

```

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

### Create Customer Bank Account with UK Details

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Use this to create a customer bank account using local UK bank details. Ensure the 'account_number' and 'branch_code' (sort code) are correctly provided.

```php
<?php
// Create a customer bank account with UK bank details
$bankAccount = $client->customerBankAccounts()->create([
    'params' => [
        'account_number'       => '55779911',
        'branch_code'          => '200000',  // Sort code
        'account_holder_name'  => 'John Smith',
        'country_code'         => 'GB',
        'currency'             => 'GBP',
        'links'                => [
            'customer' => 'CU000XXXXXXXXX'
        ]
    ]
]);

echo "Bank account ID: " . $bankAccount->id . "\n";
// Output: Bank account ID: BA000XXXXXXXXX
```

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

### Create Full Refund with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Use this to create a full refund for a collected payment. Ensure the amount and total_amount_confirmation match the full payment amount. Metadata can be included for tracking.

```php
<?php
// Create a full refund
$refund = $client->refunds()->create([
    'params' => [
        'amount' => 1500,  // Refund amount in pence/cents
        'total_amount_confirmation' => 1500,  // Confirm total amount
        'links'  => [
            'payment' => 'PM000XXXXXXXXX'
        ],
        'metadata' => [
            'reason' => 'Customer request'
        ]
    ]
]);

echo "Refund ID: " . $refund->id . "\n";
echo "Refund status: " . $refund->status . "\n";
// Output: Refund ID: RF000XXXXXXXXX
// Output: Refund status: created
```

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

### Create a Weekly Subscription with End Date in PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Configure a subscription that recurs weekly and has a defined end date. This is useful for fixed-term recurring services.

```php
<?php
// Create a weekly subscription with end date
$subscription = $client->subscriptions()->create([
    'params' => [
        'amount'        => 999,
        'currency'      => 'GBP',
        'name'          => 'Weekly Box',
        'interval_unit' => 'weekly',
        'interval'      => 1,
        'start_date'    => '2024-02-01',
        'end_date'      => '2024-12-31',
        'links'         => [
            'mandate' => 'MD000XXXXXXXXX'
        ]
    ]
]);

```

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

### Create Customer Bank Account with IBAN

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Use this to create a customer bank account for SEPA countries using an IBAN. Ensure the 'iban', 'country_code', and 'currency' are correctly provided.

```php
<?php
// Create a bank account with IBAN (for SEPA countries)
$bankAccount = $client->customerBankAccounts()->create([
    'params' => [
        'iban'                => 'DE89370400440532013000',
        'account_holder_name' => 'Hans Mueller',
        'country_code'        => 'DE',
        'currency'            => 'EUR',
        'links'               => [
            'customer' => 'CU000XXXXXXXXX'
        ]
    ]
]);
```

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

### Create Partial Refund with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Use this to create a partial refund for a collected payment. Specify the desired refund amount in pence/cents. The total_amount_confirmation should match the partial refund amount.

```php
// Create a partial refund
$refund = $client->refunds()->create([
    'params' => [
        'amount' => 500,  // Partial refund of 5.00
        'total_amount_confirmation' => 500,
        'links'  => [
            'payment' => 'PM000XXXXXXXXX'
        ]
    ]
]);
```

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

### List Customers with Pagination

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a list of customers, specifying the number of results per page using the 'limit' parameter.

```php
// List customers with pagination
$customers = $client->customers()->list(['params' => ['limit' => 50]]);
foreach ($customers->records as $customer) {
    echo $customer->id . ": " . $customer->email . "\n";
}
```

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

### Create Redirect Flow with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Initiate a redirect flow to collect mandate authorization from customers using GoCardless hosted pages. Requires a description, session token, and success redirect URL. An optional payment scheme can be specified.

```php
<?php
// Create a redirect flow
$redirectFlow = $client->redirectFlows()->create([
    'params' => [
        'description'          => 'Premium Subscription',
        'session_token'        => 'user-session-token-123',  // Your session identifier
        'success_redirect_url' => 'https://yoursite.com/payment/complete',
        'scheme'               => 'bacs'  // Optional: specify payment scheme
    ]
]);

echo "Redirect URL: " . $redirectFlow->redirect_url . "\n";
// Redirect the customer to this URL to authorize the mandate
```

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

### Paginate Resources in PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Utilize the `all()` method for automatic pagination, returning an Iterator for large datasets. Manual pagination can be achieved using `list()` with cursors for custom page sizes and navigation.

```php
<?php
// Automatic pagination - iterate through all customers
foreach ($client->customers()->all() as $customer) {
    echo $customer->id . ": " . $customer->email . "\n";
}

// Pagination with custom page size
foreach ($client->customers()->all(['params' => ['limit' => 100]]) as $customer) {
    echo $customer->id . "\n";
}

// Manual pagination using list() and cursors
$customers = $client->customers()->list(['params' => ['limit' => 50]]);
echo "Retrieved: " . count($customers->records) . " customers\n";

// Check if there are more pages
if ($customers->after) {
    $nextPage = $client->customers()->list([
        'params' => [
            'after' => $customers->after,
            'limit' => 50
        ]
    ]);
}

// Paginate through payments for a specific customer
foreach ($client->payments()->all(['params' => ['customer' => 'CU000XXXXXXXXX']]) as $payment) {
    echo $payment->id . ": " . $payment->amount . " " . $payment->status . "\n";
}

```

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

### Create Billing Request Flow with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Generate a hosted page (flow) for a billing request, allowing customers to enter their details and authorize payments. Requires redirect and exit URIs, and the ID of the billing request.

```php
// Create a billing request flow (hosted page)
$billingRequestFlow = $client->billingRequestFlows()->create([
    'params' => [
        'redirect_uri' => 'https://yoursite.com/callback',
        'exit_uri'     => 'https://yoursite.com/cancelled',
        'links'        => [
            'billing_request' => $billingRequest->id
        ]
    ]
]);

echo "Authorize URL: " . $billingRequestFlow->authorisation_url . "\n";
// Redirect customer to this URL
```

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

### Create a Mandate

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Create a new mandate for a customer bank account. This authorizes GoCardless to collect payments. Specify the payment 'scheme' and link it to a 'customer_bank_account'.

```php
<?php
// Create a mandate
$mandate = $client->mandates()->create([
    'params' => [
        'scheme' => 'bacs',  // bacs, sepa_core, ach, etc.
        'links'  => [
            'customer_bank_account' => 'BA000XXXXXXXXX'
        ],
        'metadata' => [
            'contract_id' => 'ABC123'
        ]
    ]
]);

echo "Mandate ID: " . $mandate->id . "\n";
echo "Mandate status: " . $mandate->status . "\n";
// Output: Mandate ID: MD000XXXXXXXXX
// Output: Mandate status: pending_submission
```

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

### List Payments with Filters in PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a list of payments, applying filters such as customer, status, and creation date. Use the 'created_at[gte]' parameter for date filtering.

```php
<?php
// List payments with filters
$payments = $client->payments()->list([
    'params' => [
        'customer'   => 'CU000XXXXXXXXX',
        'status'     => 'confirmed',
        'created_at[gte]' => '2024-01-01T00:00:00Z'
    ]
]);

```

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

### Iterate Through All Customers

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Automatically paginate through all available customer records.

```php
// Iterate through all customers using automatic pagination
foreach ($client->customers()->all() as $customer) {
    echo $customer->id . ": " . $customer->given_name . "\n";
}
```

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

### Create a Payment with a Specific Charge Date using PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Schedule a payment for a future date by specifying the 'charge_date' parameter. This is useful for planning future collections.

```php
<?php
// Create a payment with a specific charge date
$payment = $client->payments()->create([
    'params' => [
        'amount'      => 5000,
        'currency'    => 'GBP',
        'charge_date' => '2024-02-01',
        'links'       => [
            'mandate' => 'MD000XXXXXXXXX'
        ]
    ]
]);

```

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

### Resume a Paused Subscription with PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Restart payments for a subscription that was previously paused. Future payments will be generated according to the subscription schedule.

```php
<?php
// Resume a paused subscription
$subscription = $client->subscriptions()->resume('SB000XXXXXXXXX');

```

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

### Iterate Through All Events with Pagination with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Automatically paginate through all events, optionally filtering by resource type. This is useful for processing a large number of events without manual pagination handling.

```php
// Iterate through all events with automatic pagination
foreach ($client->events()->all(['params' => ['resource_type' => 'payments']]) as $event) {
    echo $event->created_at . ": " . $event->action . "\n";
}
```

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

### Retrieve a Subscription by ID using GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Fetch details of an existing subscription using its unique ID. This allows you to check its status and upcoming payment schedule.

```php
<?php
// Get a subscription
$subscription = $client->subscriptions()->get('SB000XXXXXXXXX');
echo "Upcoming payments: " . count($subscription->upcoming_payments) . "\n";

```

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

### List Payout Items

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Shows how to list individual payment items associated with a specific payout. Ensure the payout ID is correctly provided.

```php
// List payout items (individual payments in a payout)
$payoutItems = $client->payoutItems()->list([
    'params' => ['payout' => 'PO000XXXXXXXXX']
]);

foreach ($payoutItems->records as $item) {
    echo $item->type . ": " . $item->amount . "\n";
}
```

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

### Complete Redirect Flow with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

After the customer returns from the hosted payment pages, complete the redirect flow using the flow ID and the original session token. This provides links to the created customer and mandate.

```php
// After customer returns, complete the redirect flow
$completedFlow = $client->redirectFlows()->complete($redirectFlow->id, [
    'params' => [
        'session_token' => 'user-session-token-123'  // Must match original
    ]
]);

echo "Customer ID: " . $completedFlow->links->customer . "\n";
echo "Mandate ID: " . $completedFlow->links->mandate . "\n";
// Now you can create payments using the mandate
```

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

### List Refunds for a Payment with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a list of all refunds associated with a specific payment. This allows you to see all refund activities for a given payment.

```php
// List refunds for a payment
$refunds = $client->refunds()->list([
    'params' => ['payment' => 'PM000XXXXXXXXX']
]);

foreach ($refunds->records as $refund) {
    echo $refund->id . ": " . $refund->amount . " " . $refund->currency . "\n";
}
```

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

### Pause a Subscription using GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Temporarily halt all future payments for a subscription. The subscription can be resumed later.

```php
<?php
// Pause a subscription
$subscription = $client->subscriptions()->pause('SB000XXXXXXXXX');

```

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

### Billing Requests API

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Collect customer details and set up payments using GoCardless's hosted flows.

```APIDOC
## Billing Requests

Billing Requests provide a flexible way to collect customer details and set up payments using GoCardless's hosted flows.

### Create Billing Request

**Method**: POST
**Endpoint**: `/billing_requests`

**Parameters**:

#### Request Body
- **params** (object) - Required - Parameters for creating the billing request.
  - **mandate_request** (object) - Optional - Details for mandate creation.
    - **scheme** (string) - Required - Payment scheme (e.g., 'bacs').

### Request Example
```json
{
  "params": {
    "mandate_request": {
      "scheme": "bacs"
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created billing request.

#### Response Example
```json
{
  "id": "BRQ000XXXXXXXXX"
}
```

### Create Billing Request Flow

**Method**: POST
**Endpoint**: `/billing_request_flows`

**Parameters**:

#### Request Body
- **params** (object) - Required - Parameters for creating the flow.
  - **redirect_uri** (string) - Required - URL to redirect to after authorization.
  - **exit_uri** (string) - Required - URL to redirect to if the flow is cancelled.
  - **links** (object) - Required - Links to related resources.
    - **billing_request** (string) - Required - The ID of the billing request.

### Request Example
```json
{
  "params": {
    "redirect_uri": "https://yoursite.com/callback",
    "exit_uri": "https://yoursite.com/cancelled",
    "links": {
      "billing_request": "BRQ000XXXXXXXXX"
    }
  }
}
```

### Response
#### Success Response (200)
- **authorisation_url** (string) - The URL for the customer to authorize the billing request.

#### Response Example
```json
{
  "authorisation_url": "https://pay.gocardless.com/flow/BRWF000XXXXXXXXX"
}
```

### Get Billing Request

**Method**: GET
**Endpoint**: `/billing_requests/{id}`

### Fulfil Billing Request

**Method**: POST
**Endpoint**: `/billing_requests/{id}/fulfil`

### Cancel Billing Request

**Method**: POST
**Endpoint**: `/billing_requests/{id}/cancel`

**Parameters**:

#### Request Body
- **params** (object) - Optional - Parameters for cancelling the request.
  - **metadata** (object) - Optional - Additional metadata.
    - **cancelled_reason** (string) - Optional - Reason for cancellation.
```

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

### List Customer Bank Accounts for a Customer

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a list of all bank accounts associated with a specific customer. Requires the customer ID.

```php
<?php
// List bank accounts for a customer
$bankAccounts = $client->customerBankAccounts()->list([
    'params' => ['customer' => 'CU000XXXXXXXXX']
]);
```

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

### Retrieve a Single Customer by ID

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Fetch a specific customer's details using their unique ID.

```php
// Get a single customer
$customer = $client->customers()->get('CU000XXXXXXXXX');
echo "Customer name: " . $customer->given_name . " " . $customer->family_name . "\n";
```

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

### Create Payment with Custom Idempotency Key in PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Use the 'Idempotency-Key' header to ensure that a payment request is processed only once, even if sent multiple times. This prevents duplicate charges.

```php
<?php
// Create a payment with custom idempotency key
$payment = $client->payments()->create([
    'params' => [
        'amount'   => 2500,
        'currency' => 'GBP',
        'links'    => ['mandate' => 'MD000XXXXXXXXX']
    ],
    'headers' => [
        'Idempotency-Key' => 'invoice-12345-payment'
    ]
]);

```

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

### Handle API and Connection Errors in PHP

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

Catch specific GoCardless Pro API exceptions, including general API errors, malformed responses, and connection issues. Ensure your application can gracefully handle these scenarios.

```php
try {
  $client->customer()->create([
    'params' => ['invalid_name' => 'Pete']
  ]);
} catch (\GoCardlessPro\Core\Exception\ApiException $e) {
  // Api request failed / record couldn't be created.
} catch (GoCardlessPro\Core\Exception\MalformedResponseException $e) {
  // Unexpected non-JSON response.
} catch (GoCardlessPro\Core\Exception\ApiConnectionException $e) {
  // Network error.
}
```

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

### Retrieve a Payment by ID using GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Fetch details of an existing payment using its unique ID. This is useful for checking the status or details of a specific payment.

```php
<?php
// Get a payment
$payment = $client->payments()->get('PM000XXXXXXXXX');
echo "Amount refunded: " . $payment->amount_refunded . "\n";

```

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

### List Recent Events with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a list of recent events from your GoCardless account. This is useful for tracking changes to payments, mandates, and other resources. A limit can be set for the number of events returned.

```php
<?php
// List recent events
$events = $client->events()->list(['params' => ['limit' => 100]]);

foreach ($events->records as $event) {
    echo $event->id . ": " . $event->resource_type . " - " . $event->action . "\n";
}
// Output: EV000XXX: payments - confirmed
// Output: EV000XXX: mandates - created
```

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

### Update Subscription Amount and Name with PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Modify the amount and name of an existing subscription. This is useful for plan changes or price adjustments.

```php
<?php
// Update subscription amount
$subscription = $client->subscriptions()->update('SB000XXXXXXXXX', [
    'params' => [
        'amount' => 3000,
        'name'   => 'Premium Plan (Updated)'
    ]
]);

```

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

### Update Resource (PUT Request)

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

Make a PUT request to update a resource by providing the resource ID and the request body. Optional parameters can be included in the body.

```php
$client->customers()->update($customer_id, [
  'params' => ['family_name' => 'Smith']
]);
```

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

### Specify Custom Idempotency Key

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

Provide a custom idempotency key in the headers for POST requests to prevent duplicate resource creation. The library automatically injects idempotency keys if not provided.

```php
$client->customers()->create([
  'params' =>  ['given_name' => 'Pete', 'family_name' => 'Hamilton']
  'headers' => ['Idempotency-Key' => 'ABC123']
]);
```

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

### Cancel a Subscription using GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Permanently stop a subscription and all future payments. This action cannot be undone.

```php
<?php
// Cancel a subscription
$subscription = $client->subscriptions()->cancel('SB000XXXXXXXXX');

```

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

### List Mandates for a Customer

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a list of all mandates associated with a specific customer. Iterates through records to display ID and status.

```php
<?php
// List mandates for a customer
$mandates = $client->mandates()->list([
    'params' => ['customer' => 'CU000XXXXXXXXX']
]);

foreach ($mandates->records as $mandate) {
    echo $mandate->id . ": " . $mandate->status . "\n";
}
```

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

### Fulfil Billing Request with GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Mark a billing request as fulfilled after the customer has completed the authorization process. This action is typically performed server-side after receiving confirmation.

```php
// Fulfil a billing request (after customer authorization)
$billingRequest = $client->billingRequests()->fulfil('BRQ000XXXXXXXXX');
```

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

### Events API

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Retrieve a record of changes to resources in your GoCardless account.

```APIDOC
## Events

Events provide a record of changes to resources in your GoCardless account. Use events to track the status of payments, mandates, and other objects.

### List Events

**Method**: GET
**Endpoint**: `/events`

**Parameters**:

#### Query Parameters
- **limit** (integer) - Optional - Maximum number of records to return.
- **resource_type** (string) - Optional - Filter events by resource type (e.g., 'payments', 'mandates').
- **action** (string) - Optional - Filter events by action (e.g., 'created', 'confirmed', 'failed').

### Request Example (List with limit)
```json
{
  "params": {
    "limit": 100
  }
}
```

### Response Example (List)
```json
{
  "records": [
    {
      "id": "EV000XXX",
      "resource_type": "payments",
      "action": "confirmed"
    },
    {
      "id": "EV000XXX",
      "resource_type": "mandates",
      "action": "created"
    }
  ]
}
```

### Get Event

**Method**: GET
**Endpoint**: `/events/{id}`

### Response
#### Success Response (200)
- **action** (string) - The action performed on the resource.
- **links.payment** (string) - The ID of the associated payment (if applicable).

#### Response Example
```json
{
  "action": "confirmed",
  "links": {
    "payment": "PM000XXXXXXXXX"
  }
}
```

### Iterate Through All Events

**Method**: GET
**Endpoint**: `/events` (with automatic pagination)

**Parameters**:

#### Query Parameters
- **resource_type** (string) - Optional - Filter events by resource type.

### Response Example (Iteration)
```json
{
  "created_at": "2023-10-27T10:00:00Z",
  "action": "confirmed"
}
```
```

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

### Handle API Errors in PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Implement specific exception types for different API error scenarios to manage failures gracefully. This includes handling validation, state, usage, connection, and generic API errors.

```php
<?php
use GoCardlessPro\Core\Exception\ApiException;
use GoCardless\Core\Exception\ValidationFailedException;
use GoCardlessPro\Core\Exception\InvalidApiUsageException;
use GoCardlessPro\Core\Exception\InvalidStateException;
use GoCardlessPro\Core\Exception\ApiConnectionException;
use GoCardlessPro\Core\Exception\MalformedResponseException;

try {
    $payment = $client->payments()->create([
        'params' => [
            'amount'   => 1500,
            'currency' => 'GBP',
            'links'    => ['mandate' => 'MD000XXXXXXXXX']
        ]
    ]);
} catch (ValidationFailedException $e) {
    // Invalid parameters provided
    echo "Validation error: " . $e->getMessage() . "\n";
    foreach ($e->getErrors() as $error) {
        echo "Field: " . $error->field . " - " . $error->message . "\n";
    }
} catch (InvalidStateException $e) {
    // Resource is in wrong state (e.g., mandate not active)
    echo "Invalid state: " . $e->getMessage() . "\n";
    echo "Request ID: " . $e->getRequestId() . "\n";
} catch (InvalidApiUsageException $e) {
    // API usage error (e.g., missing required fields)
    echo "API usage error: " . $e->getMessage() . "\n";
} catch (ApiConnectionException $e) {
    // Network error after retries exhausted
    echo "Connection error: " . $e->getMessage() . "\n";
} catch (MalformedResponseException $e) {
    // Unexpected response from API
    echo "Malformed response: " . $e->getMessage() . "\n";
} catch (ApiException $e) {
    // Generic API error
    echo "API error: " . $e->getMessage() . "\n";
    echo "Error type: " . $e->getType() . "\n";
    echo "Error code: " . $e->getCode() . "\n";
    echo "Documentation: " . $e->getDocumentationUrl() . "\n";
}

// Access raw API response for debugging
try {
    $customer = $client->customers()->get('CU000XXXXXXXXX');
    $apiResponse = $customer->api_response;
    echo "Status code: " . $apiResponse->status_code . "\n";
    echo "Headers: " . print_r($apiResponse->headers, true) . "\n";
} catch (ApiException $e) {
    $apiResponse = $e->getApiResponse();
    echo "Error response body: " . $apiResponse->body . "\n";
}

```

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

### Redirect Flows API

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Facilitate customer mandate authorization using GoCardless's hosted payment pages.

```APIDOC
## Redirect Flows

Redirect flows allow you to collect mandate authorization from customers using GoCardless's hosted payment pages.

### Create Redirect Flow

**Method**: POST
**Endpoint**: `/redirect_flows`

**Parameters**:

#### Request Body
- **params** (object) - Required - Parameters for creating the redirect flow.
  - **description** (string) - Required - Description of the payment.
  - **session_token** (string) - Required - Your session identifier.
  - **success_redirect_url** (string) - Required - URL to redirect to after successful authorization.
  - **scheme** (string) - Optional - Specify payment scheme (e.g., 'bacs').

### Request Example
```json
{
  "params": {
    "description": "Premium Subscription",
    "session_token": "user-session-token-123",
    "success_redirect_url": "https://yoursite.com/payment/complete",
    "scheme": "bacs"
  }
}
```

### Response
#### Success Response (200)
- **redirect_url** (string) - The URL to redirect the customer to.

#### Response Example
```json
{
  "redirect_url": "https://pay.gocardless.com/flow/RF000XXXXXXXXX"
}
```

### Complete Redirect Flow

**Method**: POST
**Endpoint**: `/redirect_flows/{id}/complete`

**Parameters**:

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

#### Request Body
- **params** (object) - Required - Parameters for completing the flow.
  - **session_token** (string) - Required - Must match the original session token.

### Response
#### Success Response (200)
- **links.customer** (string) - The ID of the customer.
- **links.mandate** (string) - The ID of the mandate.

#### Response Example
```json
{
  "links": {
    "customer": "CU000XXXXXXXXX",
    "mandate": "MD000XXXXXXXXX"
  }
}
```
```

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

### Update an Existing Customer

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Modify the details of an existing customer by providing their ID and the updated parameters.

```php
// Update a customer
$customer = $client->customers()->update('CU000XXXXXXXXX', [
    'params' => [
        'email' => 'newemail@example.com'
    ]
]);
```

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

### Validate and Parse GoCardless Webhooks in PHP

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

Securely validate incoming webhooks from GoCardless using a shared secret and parse them into Event objects. This ensures the integrity of the data received and allows for automated actions.

```php
<?php
// When you create a webhook endpoint, you can specify a secret. When GoCardless sends
// you a webhook, it will sign the body using that secret. Since only you and GoCardless
// know the secret, you can check the signature and ensure that the webhook is truly
// from GoCardless.
//
// We recommend storing your webhook endpoint secret in an environment variable
// for security, but you could include it as a string directly in your code
$webhook_endpoint_secret = getenv('GOCARDLESS_WEBHOOK_ENDPOINT_SECRET');

$request_body = file_get_contents('php://input');

$headers = getallheaders();
$signature_header = $headers['Webhook-Signature'];

try {
     $events = GoCardlessPro\Webhook::parse($request_body, $signature_header, $webhook_endpoint_secret);

     foreach ($events as $event) {
         // You can access each event in the webhook.
         echo $event->id;
     }

     header('HTTP/1.1 200 OK');
} catch (GoCardlessPro\Core\Exception\InvalidSignatureException) {
     // The webhook doesn't appear to be genuinely from GoCardless, as the signature
     // included in the `Webhook-Signature` header doesn't match the one computed with
     // your webhook endpoint secret and the body.
     header('HTTP/1.1 498 Invalid Token');
}
```

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

### Retry a Failed Payment using GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Attempt to retry a payment that previously failed. This is typically used for retrying direct debit payments that were not successful.

```php
<?php
// Retry a failed payment
$payment = $client->payments()->retry('PM000XXXXXXXXX');

```

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

### Iterate Through List Response

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

Access and iterate through the records returned by a `list()` call. The `records` attribute contains the list of resources.

```php
echo count($customers->records);
foreach ($customers->records as $resource) {
  echo $resource->given_name;
}
```

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

### Remove a Customer for GDPR Compliance

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Delete a customer record from the system, typically for GDPR compliance.

```php
// Remove a customer (GDPR compliance)
$client->customers()->remove('CU000XXXXXXXXX');
```

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

### Update Payment Metadata using GoCardless Pro PHP

Source: https://context7.com/gocardless/gocardless-pro-php/llms.txt

Modify the metadata associated with an existing payment. This is useful for adding or updating custom information linked to the payment.

```php
<?php
// Update payment metadata
$payment = $client->payments()->update('PM000XXXXXXXXX', [
    'params' => [
        'metadata' => ['updated' => 'true']
    ]
]);

```