Mollie API PHP Client

https://github.com/mollie/mollie-api-php
Admin
A PHP client library for the Mollie payment API, enabling developers to accept international and...
Tokens:65,408
Snippets:478
Trust Score:10
License:BSD-3-Clause
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/mollie/mollie-api-php/blob/main/CLAUDE.md

Install project dependencies using Composer.

```bash
# Install dependencies
composer install
```

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

### Install Mollie API Client using Composer

Source: https://github.com/mollie/mollie-api-php/blob/main/README.md

Install the Mollie API client for PHP using Composer. This is the recommended method for managing dependencies.

```bash
composer require mollie/mollie-api-php
```

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

### Full Example with Debugging Enabled

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/debugging.md

Demonstrates setting an API key, enabling debugging, making an API call, and handling potential exceptions with sanitized debug information.

```php
try {
    $mollie = new \Mollie\Api\MollieApiClient();
    $mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

    // Enable debugging for development
    $mollie->debug();

    // Your API calls here
    $payment = $mollie->payments->create([...]);

} catch(\Mollie\Api\Exceptions\ApiException $e) {
    // Exception will include sanitized debug information
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Create a Custom HTTP Adapter

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/http-adapters.md

Implement HttpAdapterContract and use HasDefaultFactories to create a custom HTTP adapter. This example shows a basic structure for a custom adapter.

```php
use Mollie\Api\Contracts\HttpAdapterContract;
use Mollie\Api\Traits\HasDefaultFactories;

class MyCustomHttpAdapter implements HttpAdapterContract {
    use HasDefaultFactories;

    public function sendRequest(PendingRequest $pendingRequest): Response {
        // Implementation for sending HTTP request
    }

    public function version(): ?string {
        return 'my-custom-adapter/1.0';
    }
}
```

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

### Create Payment Request Example

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/request-reference.md

Instantiate and send a CreatePaymentRequest to the Mollie API. Ensure the necessary classes are imported.

```php
use Mollie\Api\Http\Requests\CreatePaymentRequest;
use Mollie\Api\Http\Data\Money;

$request = new CreatePaymentRequest(
    description: 'Order #12345',
    amount: Money::euro('10.00'),
    redirectUrl: 'https://example.com/redirect',
    webhookUrl: 'https://example.com/webhook'
);

$payment = $mollie->send($request);
```

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

### Get Onboarding Status

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve the current onboarding status for your Mollie account. This helps in tracking the progress of your account setup and verification.

```php
// Get onboarding status
$onboarding = $mollie->onboarding->status();
```

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

### Run All Tests (Parallel)

Source: https://github.com/mollie/mollie-api-php/blob/main/CLAUDE.md

Execute all tests in parallel using Paratest. Ensure dependencies are installed via composer.

```bash
# Run all tests (parallel)
composer test                    # or: vendor/bin/paratest --verbose
```

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

### Create Payment Request with Positional Parameters (PHP 7.4)

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/requests.md

Legacy example showing how to create a payment request using positional parameters. This method is less readable due to the number of optional parameters.

```php
// Legacy: Positional parameters (PHP 7.4)
$createPaymentRequest = new CreatePaymentRequest(
    'Test payment',
    new Money('EUR', '10.00'),
    'https://example.org/redirect',
    null,  // cancelUrl
    'https://example.org/webhook'
    // ... many nulls for optional parameters
);
```

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

### Manage Webhooks using Endpoint Collections (Legacy)

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/webhooks/manage-webhooks.md

Demonstrates legacy methods for managing webhooks, including getting, updating, deleting, testing, and listing them via endpoint collections. Also shows convenience methods on the webhook resource itself.

```php
try {
    // Get a webhook
    $webhook = $mollie->webhooks->get('wh_4KgGJJSZpH');

    // Update a webhook
    $webhook = $mollie->webhooks->update('wh_4KgGJJSZpH', [
        'url' => 'https://updated-example.com/webhook',
        'name' => 'Updated name'
    ]);

    // Delete a webhook
    $mollie->webhooks->delete('wh_4KgGJJSZpH');

    // Test a webhook
    $mollie->webhooks->test('wh_4KgGJJSZpH');

    // List webhooks
    $webhooks = $mollie->webhooks->page();

    // Use convenience methods on webhook resource
    $webhook = $mollie->webhooks->get('wh_4KgGJJSZpH');

    // Update using convenience method
    $webhook->update([
        'name' => 'New name'
    ]);

    // Delete using convenience method
    $webhook->delete();

    // Test using convenience method
    $webhook->test();
} catch (
    \Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Using Endpoint Collections (Legacy Style)

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/webhooks/manage-webhooks.md

Demonstrates legacy methods for managing webhooks using endpoint collections, including get, update, delete, test, and page.

```APIDOC
## Using Endpoint Collections (Legacy Style)

### Description
This section illustrates legacy methods for interacting with webhooks using the SDK's endpoint collection pattern.

### Methods
- **Get a webhook**: `$mollie->webhooks->get('wh_4KgGJJSZpH');`
- **Update a webhook**: `$mollie->webhooks->update('wh_4KgGJJSZpH', ['url' => 'https://updated-example.com/webhook', 'name' => 'Updated name']);`
- **Delete a webhook**: `$mollie->webhooks->delete('wh_4KgGJJSZpH');`
- **Test a webhook**: `$mollie->webhooks->test('wh_4KgGJJSZpH');`
- **List webhooks**: `$mollie->webhooks->page();`

### Convenience Methods on Webhook Resource
- **Update using convenience method**: `$webhook->update(['name' => 'New name']);`
- **Delete using convenience method**: `$webhook->delete();`
- **Test using convenience method**: `$webhook->test();`
```

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

### Get and List Permissions

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve details for a specific API permission scope or list all available permissions associated with your account.

```php
// Get a permission
$permission = $mollie->permissions->get('payments.read');

// List all permissions
$permissions = $mollie->permissions->list();
```

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

### Get and List Payment Methods

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve details for a specific payment method or list all available payment methods, optionally filtering by enabled methods for a given amount.

```php
// Get a method
$method = $mollie->methods->get(\\Mollie\Api\Types\PaymentMethod::IDEAL);

// List all methods
$methods = $mollie->methods->all();

// List enabled methods
$methods = $mollie->methods->allEnabled([
    'amount' => [
        'currency' => 'EUR',
        'value' => '100.00'
    ]
]);
```

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

### Create a Payment using Mollie API Client

Source: https://github.com/mollie/mollie-api-php/blob/main/README.md

Example of creating a payment using the Mollie API client. Ensure you have the necessary `use` statements for `Money` and `CreatePaymentRequest`.

```php
use Mollie\Api\Http\Data\Money;
use Mollie\Api\Http\Requests\CreatePaymentRequest;

/** @var Mollie\Api\Resources\Payment $payment */
$payment = $mollie->send(new CreatePaymentRequest(
    description: 'My first API payment',
    amount: new Money('EUR', '10.00'),
    redirectUrl: 'https://webshop.example.org/order/12345/',
    webhookUrl: 'https://webshop.example.org/mollie-webhook/'
));
```

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

### Create and Get Sessions

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Create a new session for a payment or retrieve an existing session using its ID. Sessions are used for specific payment flows.

```php
// Create a session
$session = $mollie->sessions->create([
    'amount' => [
        'currency' => 'EUR',
        'value' => '100.00'
    ],
    'description' => 'Session for service'
]);

// Get a session
$session = $mollie->sessions->get('sessionId');
```

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

### List and Get Account Capabilities

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/capabilities/list-capabilities.md

Use this snippet to list all capabilities associated with a Mollie account and to retrieve the details of a specific capability. Ensure you have initialized the Mollie client with a valid OAuth access token.

```php
use Mollie\Api\Http\Requests\ListCapabilitiesRequest;
use Mollie\Api\Http\Requests\GetCapabilityRequest;

try {
    // Initialize the Mollie client with your OAuth access token
    $mollie = new \Mollie\Api\MollieApiClient();
    $mollie->setAccessToken('access_xxx');

    // List all capabilities
    $capabilities = $mollie->send(
        new ListCapabilitiesRequest()
    );

    foreach ($capabilities as $capability) {
        echo "Capability: {$capability->name}\n";
        echo "- Status: {$capability->status}\n";
        echo "- Description: {$capability->description}\n\n";
    }

    // Get a specific capability
    $capability = $mollie->send(
        new GetCapabilityRequest(
            id: 'payments'
        )
    );

    echo "Payment capability status: {$capability->status}\n";
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Create, Get, Revoke, and List Mandates

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Manage customer mandates by creating new ones, retrieving existing ones, revoking them, or listing all mandates associated with a customer.

```php
// Create a mandate for a customer
$mandate = $mollie->mandates->createFor($customer, [
    'method' => \Mollie\Api\Types\PaymentMethod::DIRECTDEBIT,
    'consumerName' => 'John Doe',
    'consumerAccount' => 'NL55INGB0000000000',
    'consumerBic' => 'INGBNL2A',
    'signatureDate' => '2024-01-01',
    'mandateReference' => 'YOUR-COMPANY-MD13804'
]);

// Get a mandate
$mandate = $mollie->mandates->getFor($customer, 'mdt_h3gAaD5zP');

// Revoke a mandate
$mollie->mandates->revokeFor($customer, 'mdt_h3gAaD5zP');

// List mandates
$mandates = $mollie->mandates->pageFor($customer);
```

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

### List Payments with PHP

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/payments/list-payments.md

Retrieve a paginated list of payments ordered by creation date. Includes examples of iterating through payments, checking their status, and accessing refund/chargeback information. Use this to display or process payment records.

```php
use Mollie\Api\Http\Requests\GetPaginatedPaymentsRequest;

try {
    // Get all payments for this API key ordered by newest
    $payments = $mollie->send(new GetPaginatedPaymentsRequest);

    // Display the payments
    foreach ($payments as $payment) {
        echo "Payment {$payment->id}:\n";
        echo "- Description: {$payment->description}\n";
        echo "- Amount: {$payment->amount->currency} {$payment->amount->value}\n";
        echo "- Status: {$payment->status}\n";
        
        if ($payment->hasRefunds()) {
            echo "- Has been (partially) refunded\n";
        }
        
        if ($payment->hasChargebacks()) {
            echo "- Has been charged back\n";
        }
        
        if ($payment->canBeRefunded() && $payment->amountRemaining->currency === 'EUR' && floatval($payment->amountRemaining->value) >= 2.00) {
            echo "- Can be refunded\n";
        }
        
        echo "\n";
    }

    // Get the next page of payments if available
    $nextPayments = $payments->next();
    
    if (!empty($nextPayments)) {
        foreach ($nextPayments as $payment) {
            // Process next page of payments...
        }
    }
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Initialize Mollie Client

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Set up the Mollie API client by providing your API key. This is the first step before accessing any endpoints.

```php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_*************************");
```

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

### Create and Configure Mollie API Client

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/requests.md

Instantiate the Mollie API client and set your API key. This is the first step before sending any requests.

```php
use Mollie\Api\MollieApiClient;

$mollie = new MollieApiClient();
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');
```

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

### Get a balance transfer using endpoint collections (Legacy)

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/connect-balance-transfers/get-balance-transfer.md

This snippet shows how to retrieve a balance transfer using the legacy endpoint collection style in the Mollie API PHP client. It directly calls the `get` method on the `connectBalanceTransfers` endpoint collection, passing the transfer ID.

```APIDOC
## GET /connect/balance-transfers/{balanceTransferId}

### Description
Retrieves the details of a specific connect balance transfer using the legacy endpoint collection method.

### Method
GET

### Endpoint
/connect/balance-transfers/{balanceTransferId}

### Parameters
#### Path Parameters
- **balanceTransferId** (string) - Required - The ID of the balance transfer to retrieve (e.g., `cbt_4KgGJJSZpH`).

### Request Example
```php
// Get a balance transfer using endpoint collections
$balanceTransfer = $mollie->connectBalanceTransfers->get('cbt_4KgGJJSZpH');
```

### Response
#### Success Response (200)
Returns a `ConnectBalanceTransfer` object with details of the transfer. The response structure is the same as described in the SDK method above.

#### Response Example
(See Response Example in the SDK method above)

### Error Handling
- Returns 404 if the transfer ID doesn't exist.
- Returns 403 if you don't have permission to access this transfer.
```

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

### Customers - Get Customer

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves details for a specific customer using its ID.

```APIDOC
## Customers - Get Customer

### Description
Retrieves details for a specific customer using its ID.

### Method
GET

### Endpoint
/v2/customers/{customerId}

### Parameters
#### Path Parameters
- **customerId** (string) - Required - The ID of the customer to retrieve (e.g., 'cst_8wmqcHMN4U').

### Request Example
```php
$customer = $mollie->customers->get('cst_8wmqcHMN4U');
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the customer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.
- **locale** (string) - The preferred language for the customer.
- **metadata** (object) - Custom data stored with the customer.
- **createdAt** (string) - The date and time the customer was created.

#### Response Example
```json
{
  "id": "cst_8wmqcHMN4U",
  "name": "John Doe",
  "email": "john@example.org",
  "locale": "en_US",
  "metadata": null,
  "createdAt": "2024-02-01T10:00:00+00:00"
}
```
```

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

### Get a Webhook

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/webhooks/manage-webhooks.md

Retrieves a specific webhook by its ID using a direct request.

```APIDOC
## Get a Webhook

### Description
Retrieves a specific webhook using its unique identifier.

### Method
POST

### Endpoint
/v2/webhooks/{webhook_id}

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

### Request Example
```json
{
  "id": "wh_4KgGJJSZpH"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the webhook.
- **url** (string) - The URL where webhook notifications will be sent.
- **name** (string) - An optional name for the webhook.
- **eventTypes** (string) - The event types the webhook is subscribed to.
- **status** (string) - The current status of the webhook (e.g., 'enabled', 'disabled').

#### Response Example
```json
{
  "resource": "webhook",
  "id": "wh_4KgGJJSZpH",
  "url": "https://example.com/webhook",
  "profileId": "pfl_v9hTwCvYqw",
  "createdAt": "2023-12-25T10:30:54+00:00",
  "name": "Payment notifications",
  "eventTypes": "payment.created",
  "status": "enabled",
  "_links": {}
}
```
```

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

### Balances - Get Primary Balance

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves the primary balance information for the account.

```APIDOC
## Balances - Get Primary Balance

### Description
Retrieves the primary balance information for the account.

### Method
GET

### Endpoint
/v2/balances/primary

### Parameters
None

### Request Example
```php
$balance = $mollie->balances->primary();
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the balance.
- **amount** (object) - The current balance amount.
  - **currency** (string) - The currency of the amount.
  - **value** (string) - The value of the amount.
- **type** (string) - The type of the balance (e.g., 'bankaccount').
- **createdAt** (string) - The date and time the balance was created.

#### Response Example
```json
{
  "id": "bal_12345",
  "amount": {
    "currency": "EUR",
    "value": "100.50"
  },
  "type": "bankaccount",
  "createdAt": "2024-01-01T10:00:00+00:00"
}
```
```

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

### Initialize Mollie API Client

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/README.md

Initialize the Mollie API client with your API key. This is a prerequisite for using any of the recipes.

```php
use Mollie\Api\MollieApiClient;

$mollie = new MollieApiClient;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');
```

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

### Onboarding Management

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves the onboarding status for the current organization.

```APIDOC
## Get Onboarding Status

### Description
Retrieves the onboarding status for the current organization.

### Method
`GET` (implied)

### Endpoint
`/onboarding/status` (implied)

### Response
#### Success Response (200)
- Onboarding status object
```

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

### Invoices - Get Specific Invoice

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves details for a specific invoice using its ID.

```APIDOC
## Invoices - Get Specific Invoice

### Description
Retrieves details for a specific invoice using its ID.

### Method
GET

### Endpoint
/v2/invoices/{invoiceId}

### Parameters
#### Path Parameters
- **invoiceId** (string) - Required - The ID of the invoice to retrieve (e.g., 'inv_xBEbP9rvAq').

### Request Example
```php
$invoice = $mollie->invoices->get('inv_xBEbP9rvAq');
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the invoice.
- **reference** (string) - The invoice reference.
- **issueDate** (string) - The date the invoice was issued.
- **dueDate** (string) - The due date of the invoice.
- **amount** (object) - The total amount of the invoice.
  - **currency** (string) - The currency of the amount.
  - **value** (string) - The value of the amount.
- **status** (string) - The status of the invoice (e.g., 'open', 'paid', 'overdue').

#### Response Example
```json
{
  "id": "inv_xBEbP9rvAq",
  "reference": "INV-2024-001",
  "issueDate": "2024-02-10",
  "dueDate": "2024-03-10",
  "amount": {
    "currency": "EUR",
    "value": "150.00"
  },
  "status": "paid"
}
```
```

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

### Clients - Get Specific Client

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves details for a specific client using its ID.

```APIDOC
## Clients - Get Specific Client

### Description
Retrieves details for a specific client using its ID.

### Method
GET

### Endpoint
/v2/clients/{clientId}

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The ID of the client to retrieve (e.g., 'org_12345678').

#### Query Parameters
- **testmode** (boolean) - Optional - Set to `true` to retrieve the test mode client.

### Request Example
```php
$client = $mollie->clients->get('org_12345678', [
    'testmode' => true
]);
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the client.
- **name** (string) - The name of the client.
- **createdAt** (string) - The date and time the client was created.

#### Response Example
```json
{
  "id": "org_12345678",
  "name": "My Test Client",
  "createdAt": "2024-01-05T09:00:00+00:00"
}
```
```

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

### Common Patterns - Pagination

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Demonstrates how to paginate through lists of resources, such as payments, to efficiently retrieve data in manageable chunks.

```APIDOC
## Common Patterns - Pagination

### Description
Illustrates the common pattern for paginating through lists of resources returned by the API. Most list methods support pagination, allowing you to fetch data page by page or iterate through all items.

### Methods Supporting Pagination
Methods like `$mollie->payments->page()` and `$mollie->payments->iterator()` support pagination.

### Parameters for Pagination
- `from` (string) - Optional - The ID of the resource to start fetching from.
- `limit` (int) - Optional - The number of items to retrieve per page.

### Usage Examples
```php
// Get first page of payments
$payments = $mollie->payments->page();

// Get a specific page of payments, starting from a given ID and with a limit
$payments = $mollie->payments->page(
    from: 'tr_7UhSN1zuXS',  // Start from this ID
    limit: 50               // Items per page
);

// Get all items using an iterator
foreach ($mollie->payments->iterator() as $payment) {
    echo $payment->id;
}
```
```

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

### Manage Webhooks

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Create, retrieve, update, delete, test, and list webhooks. Also demonstrates using convenience methods on the webhook resource.

```php
use Mollie\Api\Types\WebhookEventType;

// Create a webhook
$webhook = $mollie->webhooks->create([
    'url' => 'https://example.com/webhook',
    'description' => 'Payment notifications',
    'events' => [
        WebhookEventType::PAYMENT_LINK_PAID,
        WebhookEventType::PROFILE_VERIFIED
    ],
    'secret' => 'my-secret-key-123'
]);

// Get a webhook
$webhook = $mollie->webhooks->get('wh_4KgGJJSZpH');

// Update a webhook
$webhook = $mollie->webhooks->update('wh_4KgGJJSZpH', [
    'url' => 'https://updated-example.com/webhook',
    'description' => 'Updated description'
]);

// Delete a webhook
$mollie->webhooks->delete('wh_4KgGJJSZpH');

// Test a webhook
$mollie->webhooks->test('wh_4KgGJJSZpH');

// List webhooks
$webhooks = $mollie->webhooks->page();

// Using convenience methods on webhook resource
$webhook = $mollie->webhooks->get('wh_4KgGJJSZpH');
$webhook->update(['description' => 'New description']);
$webhook->delete();
$webhook->test();
```

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

### Balances - Get Specific Balance

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves details for a specific balance using its ID.

```APIDOC
## Balances - Get Specific Balance

### Description
Retrieves details for a specific balance using its ID.

### Method
GET

### Endpoint
/v2/balances/{balanceId}

### Parameters
#### Path Parameters
- **balanceId** (string) - Required - The ID of the balance to retrieve (e.g., 'bal_12345').

### Request Example
```php
$balance = $mollie->balances->get('bal_12345');
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the balance.
- **amount** (object) - The current balance amount.
  - **currency** (string) - The currency of the amount.
  - **value** (string) - The value of the amount.
- **type** (string) - The type of the balance (e.g., 'bankaccount').
- **createdAt** (string) - The date and time the balance was created.

#### Response Example
```json
{
  "id": "bal_12345",
  "amount": {
    "currency": "EUR",
    "value": "100.50"
  },
  "type": "bankaccount",
  "createdAt": "2024-01-01T10:00:00+00:00"
}
```
```

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

### Terminal Pairing Codes

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Documentation for requesting, getting, listing, and revoking terminal pairing codes.

```APIDOC
## Terminal Pairing Codes

Official Documentation:
[Request pairing code](https://docs.mollie.com/reference/terminals-request-pairing-code),
[Get pairing code](https://docs.mollie.com/reference/terminals-get-pairing-code),
[List pairing codes](https://docs.mollie.com/reference/terminals-list-pairing-codes),
[Revoke pairing code](https://docs.mollie.com/reference/terminals-revoke-pairing-code)

### Request Pairing Code

##### Description
Requests a pairing code for a terminal.

### Get Pairing Code

##### Description
Retrieves a pairing code for a terminal.

### List Pairing Codes

##### Description
Lists all pairing codes.

### Revoke Pairing Code

##### Description
Revokes a pairing code.
```

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

### Get a Single Capture

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/payments/retrieve-captures.md

Retrieves a specific capture for a given payment ID and capture ID.

```APIDOC
## Get a Single Capture

### Description
Retrieves details of a specific capture for a payment.

### Method
GET

### Endpoint
/v2/payments/{paymentId}/captures/{captureId}

### Parameters
#### Path Parameters
- **paymentId** (string) - Required - The ID of the payment.
- **captureId** (string) - Required - The ID of the capture.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the capture.
- **paymentId** (string) - The ID of the payment this capture belongs to.
- **amount** (object) - The amount captured.
  - **currency** (string) - The currency of the amount.
  - **value** (string) - The value of the amount.
- **description** (string) - An optional description for the capture.
- **status** (string) - The status of the capture (e.g., "pending", "succeeded", "failed").
- **createdAt** (string) - The date and time the capture was created.

### Response Example
{
  "id": "cpt_4qqhO89gsT",
  "paymentId": "tr_WDqYK6vllg",
  "amount": {
    "currency": "EUR",
    "value": "5.00"
  },
  "description": "Order #12345",
  "status": "pending",
  "createdAt": "2024-02-24T12:13:14+00:00"
}
```

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

### Create a Subscription

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/subscriptions/manage-subscriptions.md

Use this snippet to create a new subscription for a customer. Ensure you have the customer ID and define the payment amount, interval, description, and webhook URL.

```php
use Mollie\Api\Http\Requests\CreateSubscriptionRequest;

try {
    // Create a subscription for a customer
    $subscription = $mollie->send(
        new CreateSubscriptionRequest(
            customerId: 'cst_8wmqcHMN4U',
            parameters: [
                'amount' => [
                    'value' => '10.00',
                    'currency' => 'EUR'
                ],
                'interval' => '1 month',
                'description' => 'Monthly subscription',
                'webhookUrl' => 'https://example.com/webhook',
                'metadata' => [
                    'subscription_id' => time()
                ]
            ]
        )
    );

    echo "Subscription status: {$subscription->status}\n";
} catch (\
Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Testing Pattern with Mock Client

Source: https://github.com/mollie/mollie-api-php/blob/main/CLAUDE.md

Demonstrates how to use the mock MollieApiClient for testing without making real HTTP calls. Assert that a specific request was sent.

```php
$client = MollieApiClient::fake([
    GetPaymentRequest::class => MockResponse::ok(['resource' => 'payment', ...]),
]);

$payment = $client->send(new GetPaymentRequest('tr_xxx'));

$client->assertSent(GetPaymentRequest::class);
```

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

### Balance Reports - Get Balance Report Details

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieves a specific balance report with optional filtering and grouping.

```APIDOC
## Balance Reports - Get Balance Report Details

### Description
Retrieves a specific balance report with optional filtering and grouping.

### Method
GET

### Endpoint
/v2/balance-reports/{balanceReportId}

### Parameters
#### Path Parameters
- **balanceReportId** (string) - Required - The ID of the balance report to retrieve.

#### Query Parameters
- **from** (string) - Optional - The start date for the report (YYYY-MM-DD).
- **until** (string) - Optional - The end date for the report (YYYY-MM-DD).
- **grouping** (string) - Optional - How to group the report data (e.g., 'transaction-categories').

### Request Example
```php
$report = $mollie->balanceReports->getForId('bal_12345', [
    'from' => '2024-01-01',
    'until' => '2024-01-31',
    'grouping' => 'transaction-categories'
]);
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the balance report.
- **from** (string) - The start date of the report.
- **until** (string) - The end date of the report.
- **currency** (string) - The currency of the report amounts.
- **data** (array) - An array of report data entries, structure depends on grouping.

#### Response Example
```json
{
  "id": "br_abc123",
  "from": "2024-01-01",
  "until": "2024-01-31",
  "currency": "EUR",
  "data": [
    {
      "period": "2024-01-01",
      "amount": {
        "currency": "EUR",
        "value": "50.00"
      }
    }
  ]
}
```
```

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

### Get and List Payment Chargebacks

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve details for a specific payment chargeback or list all chargebacks associated with a given payment.

```php
// Get a chargeback
$chargeback = $mollie->paymentChargebacks->getFor($payment, 'chb_n9z0tp');

// List chargebacks for payment
$chargebacks = $mollie->paymentChargebacks->pageFor($payment);
```

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

### Create and List Subscriptions

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Create a new subscription for a customer or list existing subscriptions for a customer. This is used for recurring payments.

```php
// Create a subscription
$subscription = $mollie->subscriptions->createForCustomer('customerId', [
    'amount' => [
        'currency' => 'EUR',
        'value' => '25.00'
    ],
    'interval' => '1 month',
    'description' => 'Monthly subscription'
]);

// List subscriptions
$subscriptions = $mollie->subscriptions->pageForCustomer('customerId');
```

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

### Manage Clients

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve a specific client by ID with optional test mode, or list all clients with pagination.

```php
// Get a specific client
$client = $mollie->clients->get('org_12345678', [
    'testmode' => true
]);

// List all clients
$clients = $mollie->clients->page(
    from: 'org_12345678',
    limit: 50
);
```

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

### Create Webhook using Direct Request (New Style)

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/webhooks/create-webhook.md

Use the `CreateWebhookRequest` class to create a webhook. Ensure you have the Mollie API client initialized and handle potential `ApiException`.

```php
use Mollie\Api\Http\Requests\CreateWebhookRequest;
use Mollie\Api\Types\WebhookEventType;

try {
    // Create a webhook using the direct request (new style)
    $webhook = $mollie->send(
        new CreateWebhookRequest(
            url: 'https://example.com/webhook',
            name: 'Payment notifications',
            eventTypes: WebhookEventType::PAYMENT_LINK_PAID
        )
    );

    echo "Webhook created: {$webhook->id}\n";
    echo "URL: {$webhook->url}\n";
    echo "Name: {$webhook->name}\n";
    echo "Event Types: {$webhook->eventTypes}\n";
    echo "Status: {$webhook->status}\n";
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Get and List Settlements

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve details for a specific settlement using its ID or list all available settlements. This is useful for financial reconciliation.

```php
// Get a settlement
$settlement = $mollie->settlements->get('settlementId');

// List settlements
$settlements = $mollie->settlements->page();
```

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

### Retrieve Balance Report Details

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Get detailed balance reports for a specific balance, with options to specify date ranges and grouping.

```php
// Get report for specific balance
$report = $mollie->balanceReports->getForId('bal_12345', [
    'from' => '2024-01-01',
    'until' => '2024-01-31',
    'grouping' => 'transaction-categories'
]);
```

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

### Connect Balance Transfer Pagination Methods

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/connect-balance-transfers/list-balance-transfers.md

Illustrates how to navigate through paginated results of connect balance transfers. Shows how to check for next/previous pages and use an auto-iterator for seamless traversal of all pages.

```php
// Check if there's a next page
if ($balanceTransfers->hasNext()) {
    $nextPage = $balanceTransfers->next();
}

// Check if there's a previous page
if ($balanceTransfers->hasPrevious()) {
    $previousPage = $balanceTransfers->previous();
}

// Get auto-iterator for all transfers
$iterator = $balanceTransfers->getAutoIterator();
foreach ($iterator as $transfer) {
    // Processes all transfers across all pages automatically
}
```

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

### List Connect Balance Transfers using Legacy Endpoint Collections

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/connect-balance-transfers/list-balance-transfers.md

Demonstrates listing balance transfers using the older endpoint collection style. It also shows how to use the iterator for automatic pagination within this legacy approach.

```php
try {
    // List balance transfers using endpoint collections
    $balanceTransfers = $mollie->connectBalanceTransfers->page();

    foreach ($balanceTransfers as $transfer) {
        echo "Transfer: {$transfer->description}\n";
        echo "Amount: {$transfer->amount->value}\n\n";
    }

    // Use iterator for automatic pagination
    foreach ($mollie->connectBalanceTransfers->iterator() as $transfer) {
        // Process each transfer across all pages...
    }
} catch (
Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Payment Status Constant Change

Source: https://github.com/mollie/mollie-api-php/blob/main/UPGRADING.md

Redundant prefixes have been removed from constants for a cleaner API. For example, `Payment::STATUS_PAID` is now `Payment::PAID`.

```php
// Before
Payment::STATUS_PAID;

// After
Payment::PAID;
```

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

### Get and List Terminals

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Retrieve details for a specific terminal using its ID or list all available terminals. This is used for managing physical payment terminals.

```php
// Get a terminal
$terminal = $mollie->terminals->get('terminalId');

// List terminals
$terminals = $mollie->terminals->page();
```

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

### Create Payment with Array Parameters

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Create a payment using a simple array for parameters. This method is direct but offers less type safety.

```php
$payment = $mollie->payments->create([
    'amount' => [
        'currency' => 'EUR',
        'value' => '10.00'
    ],
    'description' => 'My first API payment'
]);
```

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

### Get, List, and Retrieve Organization Information

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/endpoint-collections.md

Manage and retrieve information about your Mollie organization, including specific organizations by ID, the current organization, and partner status.

```php
// Get an organization
$organization = $mollie->organizations->get('org_12345678');

// Get current organization
$organization = $mollie->organizations->current();

// Get partner status
$partner = $mollie->organizations->partnerStatus();
```

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

### Create Client Link and Generate Redirect URL

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/onboarding/create-client-link.md

Use this snippet to create a client link for a new merchant and generate a redirect URL for them to complete onboarding. Ensure you have the Mollie API client initialized and include necessary data for the owner, organization, and registration details. The `state` parameter is crucial for CSRF prevention and should be stored in the session.

```php
use Mollie\Api\Http\Data\Owner;
use Mollie\Api\Resources\ClientLink;
use Mollie\Api\Http\Data\OwnerAddress;
use Mollie\Api\Http\Requests\CreateClientLinkRequest;

try {
    // Create a client link for a new merchant
    /** @var ClientLink $clientLink */
    $clientLink = $mollie->send(
        new CreateClientLinkRequest(
            owner: new Owner(
                email: 'merchant@example.com',
                givenName: 'John',
                familyName: 'Doe',
                locale: 'en_US'
            ),
            organizationName: 'Example Store',
            address: new OwnerAddress(
                countryCode: 'NL',
                streetAndNumber: 'Keizersgracht 313',
                postalCode: '1016 EE',
                city: 'Amsterdam'
            ),
            registrationNumber: '30204462',
            vatNumber: 'NL123456789B01'
        )
    );

    // Generate the redirect URL for the merchant
    $redirectUrl = $clientLink->getRedirectUrl(
        clientId: 'app_j9Pakf56Ajta6Y65AkdTtAv',
        state: bin2hex(random_bytes(8)),  // Random state to prevent CSRF
        prompt: 'force',  // Always show login screen
        scopes: [
            'onboarding.read',
            'onboarding.write'
        ]
    );

    // Redirect the merchant to complete their onboarding
    header('Location: ' . $redirectUrl, true, 303);
} catch (\
Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Get a Webhook using Direct Request

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/webhooks/manage-webhooks.md

Retrieves a specific webhook by its ID using a direct API request. Ensure the Mollie API client is initialized.

```php
use Mollie\Api\Http\Requests\GetWebhookRequest;

try {
    // Get a specific webhook using direct request
    $webhook = $mollie->send(
        new GetWebhookRequest(
            id: 'wh_4KgGJJSZpH'
        )
    );

    echo "Webhook {$webhook->id}:\n";
    echo "- URL: {$webhook->url}\n";
    echo "- Name: {$webhook->name}\n";
    echo "- Event Types: {$webhook->eventTypes}\n";
    echo "- Status: {$webhook->status}\n";
} catch (\
Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Create First Customer Payment (Recurring)

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/customers/customer-payments.md

Use this snippet to create the initial payment for a customer, which also establishes a mandate for future recurring payments. Ensure you have a customer ID and provide necessary payment details like amount, description, and URLs.

```php
use Mollie\Api\Http\Data\Money;
use Mollie\Api\Http\Requests\CreateCustomerPaymentRequest;
use Mollie\Api\Types\SequenceType;

try {
    // Create the first payment for a customer
    $payment = $mollie->send(
        new CreateCustomerPaymentRequest(
            customerId: 'cst_8wmqcHMN4U',
            description: 'First payment - Order #12345',
            amount: Money::euro('29.95'),  // Using convenience method
            redirectUrl: 'https://example.com/payments/return?order_id=12345',
            webhookUrl: 'https://example.com/payments/webhook',
            metadata: [
                'order_id' => '12345'
            ],
            sequenceType: SequenceType::FIRST // This creates a mandate for future payments
        )
    );

    // Redirect the customer to complete the payment
    header('Location: ' . $payment->getCheckoutUrl(), true, 303);
} catch (\
Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```

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

### Handling Payment Link Paid Events

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/webhooks/webhook-events.md

Specific example for handling a 'payment-link.paid' webhook event type, extracting payment link details from the embedded entity.

```php
// payment-link.paid
if ($webhookEvent->type === 'payment-link.paid') {
    $paymentLink = $webhookEvent->getEntity();
    echo "Payment Link: {$paymentLink->id}\n";
    echo "Amount: {$paymentLink->amount->value} {$paymentLink->amount->currency}\n";
    echo "Status: {$paymentLink->status}\n";
}
```

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

### Configure Test Mode Globally

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/testing.md

Set the API key and enable test mode for all subsequent requests made by the Mollie API client.

```php
use Mollie\Api\MollieApiClient;

$mollie = new MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");
$mollie->test(true); // Applies to all subsequent requests
```

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

### Create Payment with OAuth in PHP

Source: https://github.com/mollie/mollie-api-php/blob/main/docs/recipes/payments/create-payment-oauth.md

Initializes the Mollie client with an OAuth token, retrieves a profile, and creates a payment. Requires specifying `profileId` for OAuth tokens. Redirects the customer to the checkout URL.

```php
use Mollie\Api\Http\Data\Money;
use Mollie\Api\Http\Requests\CreatePaymentRequest;
use Mollie\Api\Http\Requests\GetPaginatedProfilesRequest;

try {
    // Initialize the Mollie client with your OAuth access token
    $mollie = new \Mollie\Api\MollieApiClient();
    $mollie->setAccessToken('access_xxx');

    // Get the first available profile since OAuth tokens don't belong to a specific profile
    $profiles = $mollie->send(new GetPaginatedProfilesRequest);

    $profile = $profiles[0]; // Select the correct profile for this merchant

    // Generate a unique order ID
    $orderId = time();

    // Create the payment
    $payment = $mollie->send(
        new CreatePaymentRequest(
            profileId: $profile->id, // Required when using OAuth
            description: "Order #{$orderId}",
            amount: new Money(currency: 'EUR', value: '10.00'),
            redirectUrl: 'https://example.com/return.php?order_id=' . $orderId,
            cancelUrl: 'https://example.com/cancel.php',
            webhookUrl: 'https://example.com/webhook.php',
            metadata: ['order_id' => $orderId]
        )
    );

    // Redirect the customer to complete the payment
    header('Location: ' . $payment->getCheckoutUrl(), true, 303);
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}
```
Tokens:
Raw