### Install SDK and Publish Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/README.md

Install the SDK using Composer and publish the configuration files using Artisan.

```bash
composer require jeffreyvanhees/laravel-online-payment-platform
php artisan vendor:publish --tag=opp-config
```

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

### Facade Service Container Access Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

Shows how to access the OnlinePaymentPlatform facade using Laravel's service container, for example, within a controller.

```php
use Illuminate\Http\Request;
use JeffreyVonEuw\bursement\facades\OnlinePaymentPlatform;

class PaymentController
{
    public function store(Request $request)
    {
        $merchantId = $request->input('merchant_id');
        $chargeData = $request->only(['amount', 'currency', 'payment_method_uuid']);

        $charge = OnlinePaymentPlatform::merchants()->charges()->create($merchantId, $chargeData);

        return response()->json($charge);
    }
}
```

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

### Unit Test Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

A basic example of a unit test for a service that uses the OnlinePaymentPlatform facade. It shows how to mock the facade.

```php
use PHPUnit\Framework\TestCase;
use JeffreyVonEuw\bursement\Facades\OnlinePaymentPlatform;
use Illuminate\Support\Facades\Facade;

class PaymentServiceTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        // Mock the facade
        Facade::shouldReceive('OnlinePaymentPlatform')->andReturnSelf();
    }

    public function test_process_payment_success(): void
    {
        // Mock a specific method call on the facade
        OnlinePaymentPlatform::shouldReceive('merchants->charges->create')
            ->once()
            ->with('merchant_id', ['amount' => 100])
            ->andReturn(['id' => 'ch_123']);

        $service = new PaymentService(OnlinePaymentPlatform::getFacadeRoot()); // Assuming constructor injection
        $result = $service->processPayment('merchant_id', ['amount' => 100]);

        $this->assertEquals(['id' => 'ch_123'], $result);
    }
}
```

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

### Install Laravel Online Payment Platform SDK

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Install the package via Composer. This command downloads and installs the SDK into your Laravel project.

```bash
composer require jeffreyvanhees/laravel-online-payment-platform
```

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

### Testing Configuration with .env.testing

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/configuration.md

Provides an example of setting up testing environment variables in a `.env.testing` file to configure the platform for tests.

```env
APP_ENV=testing
OPP_SANDBOX=true
OPP_SANDBOX_API_KEY=test_key_here
OPP_TIMEOUT=5
OPP_RETRY_TIMES=1

```

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

### Get and Set Configuration Values at Runtime

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/configuration.md

Demonstrates how to retrieve configuration values using the `config()` helper and how to temporarily set configuration values.

```php
// Get configuration value
$apiKey = config('opp.api_key');
$isSandbox = config('opp.sandbox');

// Set configuration temporarily
config(['opp.sandbox' => false]);

```

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

### Complete Configuration Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/configuration.md

This snippet shows the full configuration array for the Online Payment Platform, demonstrating how to set API credentials, environment, HTTP, retry, URL, webhook, logging, and cache settings.

```php
<?php

return [
    /*
    |--------------------------------------------------------------------------
    | API Credentials
    |--------------------------------------------------------------------------
    */
    'api_key' => env('OPP_API_KEY'),
    'sandbox_api_key' => env('OPP_SANDBOX_API_KEY'),

    /*
    |--------------------------------------------------------------------------
    | Environment Configuration
    |--------------------------------------------------------------------------
    */
    'sandbox' => env('OPP_SANDBOX', true),

    /*
    |--------------------------------------------------------------------------
    | HTTP Configuration
    |--------------------------------------------------------------------------
    */
    'timeout' => env('OPP_TIMEOUT', 30),
    'connect_timeout' => env('OPP_CONNECT_TIMEOUT', 5),

    /*
    |--------------------------------------------------------------------------
    | Retry Configuration
    |--------------------------------------------------------------------------
    */
    'retry' => [
        'times' => env('OPP_RETRY_TIMES', 3),
        'sleep' => env('OPP_RETRY_SLEEP', 1000),
    ],

    /*
    |--------------------------------------------------------------------------
    | URL Configuration
    |--------------------------------------------------------------------------
    */
    'urls' => [
        'notify' => env('OPP_NOTIFY_URL'),
        'return' => env('OPP_RETURN_URL'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Webhook Configuration
    |--------------------------------------------------------------------------
    */
    'webhook' => [
        'secret' => env('OPP_NOTIFY_SECRET'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Logging Configuration
    |--------------------------------------------------------------------------
    */
    'logging' => [
        'enabled' => env('OPP_LOGGING_ENABLED', false),
        'channel' => env('OPP_LOGGING_CHANNEL', 'single'),
        'level' => env('OPP_LOGGING_LEVEL', 'info'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Cache Configuration
    |--------------------------------------------------------------------------
    */
    'cache' => [
        'enabled' => env('OPP_CACHE_ENABLED', false),
        'store' => env('OPP_CACHE_STORE', 'default'),
        'ttl' => env('OPP_CACHE_TTL', 3600),
    ],
];

```

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

### ProductData Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/types.md

Demonstrates how to create and collect multiple ProductData instances using an array of product details. This is useful for populating transaction line items.

```php
use JeffreyVanHees\OnlinePaymentPlatform\Data\Common\ProductData;

$products = ProductData::collect([
    [
        'name' => 'Widget Pro',
        'quantity' => 2,
        'price' => 2500,
        'ean' => '1234567890123',
        'vat_rate' => 21.0
    ]
]);
```

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

### Get Partner Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Retrieves the configuration settings for partners.

```APIDOC
## GET /v1/partners/configuration

### Description
Retrieves the configuration settings for partners.

### Method
GET

### Endpoint
/v1/partners/configuration

### Response
#### Success Response (200 OK)
- **configuration** (object) - An object containing various partner configuration settings.

#### Response Example
```json
{
  "configuration": {
    "api_key_enabled": true,
    "webhook_url": "https://example.com/partner/webhook"
  }
}
```
```

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

### Complete Merchant Setup with All Sub-Resources

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/merchants-subresources.md

This snippet demonstrates the full process of creating a business merchant and subsequently adding all associated sub-resources: business address, contact person, bank account, UBO, and a merchant profile. It covers the necessary data objects and API calls for each step.

```php
use OnlinePaymentPlatform;
use JeffreyVanHees\OnlinePaymentPlatform\Data\Requests\Merchants{
    CreateBusinessMerchantData,
    CreateMerchantAddressData,
    CreateMerchantBankAccountData,
    CreateMerchantUBOData
};

// 1. Create merchant
$merchant = OnlinePaymentPlatform::merchants()->create(
    new CreateBusinessMerchantData(
        type: 'business',
        country: 'NLD',
        emailaddress: 'business@example.com',
        legal_name: 'Example B.V.',
        coc_nr: '12345678'
    )
);
$merchantUid = $merchant->dto()->uid;

// 2. Add business address
OnlinePaymentPlatform::merchants()
    ->addresses($merchantUid)
    ->add(new CreateMerchantAddressData(
        type: 'business',
        address_line_1: 'Main Street 123',
        city: 'Amsterdam',
        zipcode: '1000 AA',
        country: 'NLD'
    ));

// 3. Add contact
OnlinePaymentPlatform::merchants()
    ->contacts($merchantUid)
    ->add([
        'type' => 'representative',
        'name' => 'John Smith',
        'email' => 'john@example.com'
    ]);

// 4. Add bank account
$bankAccount = OnlinePaymentPlatform::merchants()
    ->bankAccounts($merchantUid)
    ->add(new CreateMerchantBankAccountData(
        return_url: 'https://example.com/bank-return',
        notify_url: 'https://example.com/bank-notify',
        is_default: true
    ));

// 5. Add Ultimate Beneficial Owner
OnlinePaymentPlatform::merchants()
    ->ubos($merchantUid)
    ->create(new CreateMerchantUBOData(
        name_first: 'Jane',
        name_last: 'Doe',
        date_of_birth: '1980-01-15',
        country_of_residence: 'NLD',
        is_decision_maker: true,
        percentage_of_shares: 100.0
    ));

// 6. Create merchant profile
OnlinePaymentPlatform::merchants()
    ->profiles($merchantUid)
    ->create([
        'name' => 'Main Store',
        'description' => 'Primary e-commerce store',
        'is_default' => true
    ]);

// Merchant is now fully configured
echo "Merchant {$merchantUid} is ready for transactions";

```

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

### Access and Set Configuration Values

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/facade-and-integration.md

Shows how to retrieve configuration values using the `config()` helper function and how to temporarily set configuration values at runtime. Also includes an example of accessing environment variables directly.

```php
// Get configuration values
$apiKey = config('opp.api_key');
$isSandbox = config('opp.sandbox');
$timeout = config('opp.timeout');
$webhookSecret = config('opp.webhook.secret');

// Set configuration (runtime - temporary)
config(['opp.sandbox' => false]);

// Check configuration
if (config('opp.logging.enabled')) {
    // Logging is enabled
}

// Environment variables (if using direct env() access)
$apiKey = env('OPP_API_KEY');
```

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

### Manage Partner Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Provides examples for retrieving and updating partner-specific settings. This includes fetching the current configuration and updating the notification URL.

```php
// Get partner configuration
$config = OnlinePaymentPlatform::partners()->getConfiguration();

// Update partner settings (only notify_url is updatable)
$updated = OnlinePaymentPlatform::partners()->updateConfiguration([
    'notify_url' => 'https://partner.example.com/webhooks',
]);

// Get merchant balance via partner
$merchantBalance = OnlinePaymentPlatform::partners()->getMerchantBalance('mer_123456789');
```

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

### Facade Constructor Injection Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

Demonstrates how to use constructor injection to inject the OnlinePaymentPlatform facade into a Laravel service or controller.

```php
use JeffreyVonEuwursementacades\OnlinePaymentPlatform;

class PaymentService
{
    protected OnlinePaymentPlatform $paymentPlatform;

    public function __construct(OnlinePaymentPlatform $paymentPlatform)
    {
        $this->paymentPlatform = $paymentPlatform;
    }

    public function processPayment(string $merchantId, array $data)
    {
        return $this->paymentPlatform->merchants()->charges()->create($merchantId, $data);
    }
}
```

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

### Feature Test Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

An example of a feature test that interacts with the OnlinePaymentPlatform facade as it would in a real application, without explicit mocking.

```php
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Foundation\Testing\WithFaker;
use Tests\TestCase;
use JeffreyVonEuw\bursement\Facades\OnlinePaymentPlatform;

class MerchantApiTest extends TestCase
{
    use RefreshDatabase, WithFaker;

    public function test_can_create_merchant_charge(): void
    {
        // Assuming you have a route and controller set up
        $response = $this->postJson('/api/payments', [
            'merchant_id' => 'mer_abc',
            'amount' => 5000,
            'currency' => 'USD',
            'payment_method_uuid' => 'pm_xyz'
        ]);

        $response->assertStatus(201);
        $response->assertJsonStructure(['id']);

        // You can also assert that the facade method was called if needed, 
        // but often in feature tests, you test the end result.
        // OnlinePaymentPlatform::assertFacadeHasBeenCalled('merchants->charges->create');
    }
}
```

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

### Pagination Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

When retrieving lists, use pagination parameters 'page' and 'perpage' to control the results. 'perpage' accepts values between 1 and 100.

```bash
?page=2&perpage=10
```

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

### Complete Purchase Flow Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/facade-and-integration.md

Illustrates a full checkout process, including validating a merchant, creating a transaction with items, and handling the redirect URL. It also shows how to check the status of a transaction upon return.

```php
namespace App\Services;

use OnlinePaymentPlatform;

class CheckoutService
{
    public function processCheckout(array $cartItems, string $merchantUid): string
    {
        try {
            // 1. Validate merchant exists
            $merchant = OnlinePaymentPlatform::merchants()->get($merchantUid);
            if (!$merchant->successful()) {
                throw new \Exception('Invalid merchant');
            }

            // 2. Create transaction with items
            $totalPrice = collect($cartItems)->sum('price');
            $transaction = OnlinePaymentPlatform::transactions()->create([
                'merchant_uid' => $merchantUid,
                'total_price' => $totalPrice,
                'products' => $cartItems,
                'return_url' => route('checkout.return'),
                'notify_url' => route('webhooks.opp')
            ]);

            if (!$transaction->successful()) {
                throw new \Exception('Failed to create transaction');
            }

            // 3. Return redirect URL
            return $transaction->dto()->redirect_url;

        } catch (\Exception $e) {
            \Log::error('Checkout Error: ' . $e->getMessage());
            throw $e;
        }
    }

    public function handlePaymentReturn(string $transactionUid): array
    {
        // Check transaction status
        $transaction = OnlinePaymentPlatform::transactions()->get($transactionUid);
        $status = $transaction->dto()->status;

        if ($status === 'captured') {
            return ['success' => true, 'message' => 'Payment successful'];
        } elseif ($status === 'failed') {
            return ['success' => false, 'message' => 'Payment failed'];
        } else {
            return ['success' => false, 'message' => 'Payment pending'];
        }
    }
}
```

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

### Create a Transaction

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Example of creating a new transaction. It requires merchant UID, total price in cents, product details, and return/notify URLs. The 'total_price' and product 'price' should be in cents.

```php
// Create transactions
$transaction = OnlinePaymentPlatform::transactions()->create([
    'merchant_uid' => 'mer_123456789',
    'total_price' => 1000, // €10.00 in cents
    'products' => [
        [
            'name' => 'Product Name',
            'quantity' => 1,
            'price' => 1000,
        ],
    ],
    'return_url' => 'https://yoursite.com/payment/return',
    'notify_url' => 'https://yoursite.com/webhooks/opp',
]);
```

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

### Get Partner Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/other-resources.md

Retrieves the partner's current configuration settings, including the notify URL.

```php
public function getConfiguration(): Response
```
$config = OnlinePaymentPlatform::partners()->getConfiguration();
$configData = $config->dto();
echo "Notify URL: {$configData->notify_url}";
```

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

### Basic Filtering Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Use the basic filter format '?filter[FILTER]=VALUE' to apply simple filtering to your requests.

```bash
?filter[FILTER]=VALUE
```

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

### ProductData Collection Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/types.md

Shows how to use Spatie's DataCollection to manage collections of DTOs, such as ProductData, for use in other DTOs like CreateTransactionData.

```php
use JeffreyVanHees\OnlinePaymentPlatform\Data\Common\ProductData;

// Collect method
$products = ProductData::collect([
    ['name' => 'Item 1', 'quantity' => 1, 'price' => 1000],
    ['name' => 'Item 2', 'quantity' => 2, 'price' => 500]
]);

// Or use array directly (auto-converted)
$data = new CreateTransactionData(
    merchant_uid: 'mer_123',
    total_price: 2000,
    products: ProductData::collect([...])
);
```

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

### Sandbox-Only Operations Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/errors.md

Demonstrates how to conditionally execute sandbox-only operations, ensuring they are only called when the application is configured for sandbox mode.

```php
// SANDBOX ONLY - Testing
if (config('opp.sandbox')) {
    OnlinePaymentPlatform::merchants()->updateStatus('mer_123', 'live');
    
    // Simulate bank account verification
    OnlinePaymentPlatform::merchants()
        ->bankAccounts('mer_123')
        ->updateStatus('ba_123', 'approved');
}
```

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

### Product Data Structure Example

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/transactions.md

Defines the structure for passing product data, including name, quantity, price, and optional fields like EAN, code, and VAT rate.

```php
use JeffreyVanHees\OnlinePaymentPlatform\Data\Common\ProductData;

ProductData::collect([
    [
        'name' => 'Product name (max 150 chars)',
        'quantity' => 1, // max 65535
        'price' => 2500, // in cents, max 99999999
        'ean' => '1234567890123', // optional, max 13 chars
        'code' => 'PROD-001', // optional, max 50 chars
        'vat_rate' => 21.0, // optional, 0-100%
    ]
])
```

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

### Update a Transaction

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Shows how to update an existing transaction. This example updates the description of a transaction identified by its UID.

```php
// Update transaction
$updated = OnlinePaymentPlatform::transactions()->update('tra_987654321', [
    'description' => 'Updated description',
]);
```

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

### Create, Get, List, and Cancel Withdrawals

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Demonstrates how to manage withdrawals to a merchant's bank account using the SDK. Includes creating, retrieving status, listing, and canceling pending withdrawals.

```php
// Create withdrawal to merchant's bank account
$withdrawal = OnlinePaymentPlatform::withdrawals()->create('mer_123456789', [
    'amount' => 50000, // €500.00 in cents
    'currency' => 'EUR',
    'bank_account_uid' => 'ban_123456789',
    'description' => 'Weekly payout',
    'reference' => 'PAYOUT-2024-W01',
]);

// Retrieve withdrawal status
$withdrawal = OnlinePaymentPlatform::withdrawals()->get('wit_123456789');

// List withdrawals for a merchant
$withdrawals = OnlinePaymentPlatform::withdrawals()->list([
    'merchant_uid' => 'mer_123456789',
    'status' => 'completed',
    'limit' => 25,
]);

// Cancel pending withdrawal
OnlinePaymentPlatform::withdrawals()->delete('wit_123456789');
```

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

### Process Incoming Webhooks

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/facade-and-integration.md

Provides an example of how to handle incoming webhooks from the Online Payment Platform, including verifying the signature and processing different event types like transaction captures and failures. Ensure the webhook secret is configured correctly.

```php
namespace App\Http\Controllers;

use OnlinePaymentPlatform;
use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function handleOppWebhook(Request $request)
    {
        $data = $request->all();

        // Verify webhook signature
        $secret = config('opp.webhook.secret');
        if (!$this->verifySignature($data, $secret)) {
            return response('Unauthorized', 401);
        }

        // Process based on event type
        match($data['event_type']) {
            'transaction.captured' => $this->handleCaptured($data),
            'transaction.failed' => $this->handleFailed($data),
            'refund.created' => $this->handleRefund($data),
            default => null
        };

        return response('OK', 200);
    }

    private function handleCaptured(array $data)
    {
        $transactionUid = $data['transaction_uid'];
        $amount = $data['amount'];

        // Update order status
        $order = Order::where('transaction_uid', $transactionUid)->first();
        if ($order) {
            $order->update(['status' => 'paid']);
            // Send confirmation email, etc.
        }
    }

    private function verifySignature(array $data, string $secret): bool
    {
        $signature = $data['signature'] ?? null;
        $payload = json_encode($data);
        $computed = hash_hmac('sha256', $payload, $secret);
        return hash_equals($computed, $signature ?? '');
    }
}
```

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

### BaseData Class Usage Examples

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/types.md

Demonstrates how to use the BaseData class for converting DTOs to arrays or JSON, and creating DTOs from arrays.

```php
// Convert to array
$array = $dto->toArray();

// Convert to JSON
$json = $dto->toJson();

// Create from array
$dto = CreateTransactionData::from([
    'merchant_uid' => 'mer_123',
    'total_price' => 1000,
    'products' => [...]
]);
```

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

### General ApiException Handling

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/errors.md

A comprehensive example of catching ApiException, displaying its message and status code, and accessing additional response details.

```php
try {
    OnlinePaymentPlatform::merchants()->get('mer_invalid');
} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage();
    echo "Status Code: " . $e->getCode();
    
    // Access response details
    if ($response = $e->getMeta()['response'] ?? null) {
        echo "Response: " . json_encode($response);
    }
}
```

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

### Create, Get, and List Disputes

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Shows how to manage disputes related to transactions. Includes creating disputes with evidence, retrieving dispute details with transaction information, and listing disputes based on status and date.

```php
// Create dispute for a transaction
$dispute = OnlinePaymentPlatform::disputes()->create([
    'transaction_uid' => 'tra_123456789',
    'amount' => 1000, // €10.00 in cents
    'reason' => 'Product not received',
    'message' => 'Customer claims product was never delivered',
    'evidence' => [
        'tracking_number' => 'TRACK123456',
        'shipping_date' => '2024-01-15',
    ],
]);

// Retrieve dispute with transaction details
$dispute = OnlinePaymentPlatform::disputes()->get('dis_123456789', [
    'include' => 'transaction',
]);

// List all disputes
$disputes = OnlinePaymentPlatform::disputes()->list([
    'status' => 'pending',
    'created_after' => '2024-01-01',
]);
```

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

### Feature Tests for Online Payment Platform

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/facade-and-integration.md

Use these examples to test merchant and transaction creation in feature tests. Ensure sandbox mode is enabled for testing.

```php
namespace Tests\Feature;

use OnlinePaymentPlatform;
use Tests\TestCase;

class PaymentTest extends TestCase
{
    public function test_create_merchant()
    {
        // Ensure sandbox mode for testing
        config(['opp.sandbox' => true]);

        $response = OnlinePaymentPlatform::merchants()->create([
            'type' => 'consumer',
            'country' => 'NLD',
            'emailaddress' => 'test@example.com',
            'name_first' => 'Test',
            'name_last' => 'User'
        ]);

        $this->assertTrue($response->successful());
        $this->assertNotNull($response->dto()->uid);
    }

    public function test_create_transaction()
    {
        $merchantUid = $this->createTestMerchant();

        $response = OnlinePaymentPlatform::transactions()->create([
            'merchant_uid' => $merchantUid,
            'total_price' => 1000,
            'products' => [
                ['name' => 'Test Product', 'quantity' => 1, 'price' => 1000]
            ]
        ]);

        $this->assertTrue($response->successful());
        $this->assertNotNull($response->dto()->redirect_url);
    }

    private function createTestMerchant(): string
    {
        $response = OnlinePaymentPlatform::merchants()->create([
            'type' => 'consumer',
            'country' => 'NLD',
            'emailaddress' => 'merchant@example.com'
        ]);

        return $response->dto()->uid;
    }
}
```

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

### Create a Charge for Balance Transfer

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Example of creating a charge, specifically for balance transfers between merchants. Requires type, amount in cents, sender/receiver UIDs, description, and optional metadata.

```php
// Create charges for balance transfers between merchants
$charge = OnlinePaymentPlatform::charges()->create([
    'type' => 'balance',
    'amount' => 1500, // €15.00 in cents
    'from_owner_uid' => 'mer_123456789',
    'to_owner_uid' => 'mer_987654321',
    'description' => 'Monthly platform fee',
    'metadata' => ['invoice_id' => 'INV-2024-001'],
]);
```

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

### Get Mandate Details

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Retrieves the details of a specific mandate.

```APIDOC
## GET /v1/mandates/{mandate_uid}

### Description
Retrieves the details of a specific mandate.

### Method
GET

### Endpoint
/v1/mandates/{mandate_uid}

### Parameters
#### Path Parameters
- **mandate_uid** (string) - Required - The unique identifier of the mandate.

### Response
#### Success Response (200 OK)
- **mandate_uid** (string) - The unique identifier for the mandate.
- **merchant_uid** (string) - The unique identifier of the associated merchant.
- **consumer_email** (string) - The email address of the consumer.
- **consumer_iban** (string) - The IBAN of the consumer.
- **consumer_name** (string) - The full name of the consumer.
- **status** (string) - The current status of the mandate.
- **created_at** (string) - Timestamp when the mandate was created.
- **updated_at** (string) - Timestamp when the mandate was last updated.

#### Response Example
```json
{
  "mandate_uid": "man_xxxxxxxxxxxxxx",
  "merchant_uid": "mer_xxxxxxxxxxxxxx",
  "consumer_email": "customer@example.com",
  "consumer_iban": "NL91ABNA0412345678",
  "consumer_name": "John Doe",
  "status": "active",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-02T10:00:00Z"
}
```
```

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

### Custom HTTP Client Initialization

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Shows how to instantiate the OnlinePaymentPlatformConnector with custom API keys and sandbox settings, and how to add custom middleware for request modification and response handling.

```php
use JeffreyVanHees\OnlinePaymentPlatform\OnlinePaymentPlatformConnector;

// Using constructor
$connector = new OnlinePaymentPlatformConnector(
    apiKey: 'your-api-key',
    sandbox: true
);

// Or using the static make() method
$connector = OnlinePaymentPlatformConnector::make('your-api-key', true);
$connector = OnlinePaymentPlatformConnector::make('your-api-key'); // defaults to sandbox
$connector = OnlinePaymentPlatformConnector::make('your-api-key', false); // production

// Add custom middleware
$connector->middleware()->onRequest(function ($request) {
    $request->headers()->add('Custom-Header', 'value');
    return $request;
});

// Add retry logic
$connector->middleware()->onResponse(function ($response) {
    if ($response->status() === 429) {
        sleep(1);
        return $response->throw(); // Retry
    }
    return $response;
});
```

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

### Get Transaction Details

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Retrieves the details of a specific transaction.

```APIDOC
## GET /v1/transactions/{transaction_uid}

### Description
Retrieves the details of a specific transaction.

### Method
GET

### Endpoint
/v1/transactions/{transaction_uid}

### Parameters
#### Path Parameters
- **transaction_uid** (string) - Required - The unique identifier of the transaction.

### Response
#### Success Response (200 OK)
- **transaction_uid** (string) - The unique identifier for the transaction.
- **merchant_uid** (string) - The unique identifier of the associated merchant.
- **amount** (integer) - The transaction amount in cents.
- **currency** (string) - The ISO 4217 currency code.
- **description** (string) - A description for the transaction.
- **status** (string) - The current status of the transaction.
- **created_at** (string) - Timestamp when the transaction was created.
- **updated_at** (string) - Timestamp when the transaction was last updated.

#### Response Example
```json
{
  "transaction_uid": "txn_xxxxxxxxxxxxxx",
  "merchant_uid": "mer_xxxxxxxxxxxxxx",
  "amount": 1000,
  "currency": "EUR",
  "description": "Order #12345",
  "status": "completed",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:05:00Z"
}
```
```

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

### Get Merchant Settlements

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Retrieves a list of settlements for a specific merchant.

```APIDOC
## GET /v1/merchants/{merchant_uid}/settlements

### Description
Retrieves a list of settlements for a specific merchant.

### Method
GET

### Endpoint
/v1/merchants/{merchant_uid}/settlements

### Parameters
#### Path Parameters
- **merchant_uid** (string) - Required - The unique identifier of the merchant.

#### Query Parameters
- **page** (integer) - Optional - The current page number for pagination.
- **perpage** (integer) - Optional - Items per page (1-100).

### Response
#### Success Response (200 OK)
- **data** (array) - A list of settlement objects for the specified merchant.
- **pagination** (object) - Pagination information.

#### Response Example
```json
{
  "data": [
    {
      "settlement_uid": "set_xxxxxxxxxxxxxx",
      "merchant_uid": "mer_xxxxxxxxxxxxxx",
      "amount": 150000,
      "currency": "EUR",
      "status": "processed",
      "period_start": "2023-01-01T00:00:00Z",
      "period_end": "2023-01-31T23:59:59Z"
    }
  ],
  "pagination": {
    "total_items": 1,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 10
  }
}
```
```

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

### Get Transaction

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/transactions.md

Retrieves the details of a specific transaction, including its status.

```APIDOC
## get()

### Description
Retrieves the details of a specific transaction.

### Method
GET (Assumed based on get operation, actual method not specified)

### Endpoint
`/transactions/{transactionUid}` (Assumed endpoint structure)

### Parameters
#### Path Parameters
- **transactionUid** (string) - Required - The UID of the transaction to retrieve.

### Request Example
```php
$transaction = OnlinePaymentPlatform::transactions()
    ->get('tra_123456789');

$data = $transaction->dto();

if ($data->status === 'captured') {
    echo "Payment successful";
} else if ($data->status === 'pending') {
    echo "Awaiting customer action";
} else if ($data->status === 'failed') {
    echo "Payment failed";
}
```

### Response
#### Success Response
- **transaction** (object) - An object containing the transaction details, including its status.
```

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

### Create Connector with Custom Settings

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/configuration.md

Shows how to instantiate the `OnlinePaymentPlatformConnector` with custom API key and sandbox settings.

```php
// Create connector with custom settings
$connector = new OnlinePaymentPlatformConnector(
    apiKey: 'custom-key',
    sandbox: false
);

```

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

### Access Settlements Resource

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/connector.md

Get the SettlementsResource for platform-wide settlement reporting.

```php
$settlements = $connector->settlements();
```

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

### Checking Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/facade-and-integration.md

Use `php artisan config:show opp` to check the current configuration for the Online Payment Platform.

```bash
# Check configuration
php artisan config:show opp
```

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

### Access Disputes Resource

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/connector.md

Get the DisputesResource to manage transaction disputes.

```php
$disputes = $connector->disputes();
```

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

### Get Settlement Specification Rows

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Retrieves the rows for a specific settlement specification.

```APIDOC
## GET /v1/settlements/{settlement_uid}/specifications/{specification_uid}/rows

### Description
Retrieves the rows for a specific settlement specification.

### Method
GET

### Endpoint
/v1/settlements/{settlement_uid}/specifications/{specification_uid}/rows

### Parameters
#### Path Parameters
- **settlement_uid** (string) - Required - The unique identifier of the settlement.
- **specification_uid** (string) - Required - The unique identifier of the specification.

### Response
#### Success Response (200 OK)
- **data** (array) - A list of row objects within the settlement specification.

#### Response Example
```json
{
  "data": [
    {
      "row_id": "row_xxxxxxxxxxxxxx",
      "type": "transaction",
      "transaction_uid": "txn_xxxxxxxxxxxxxx",
      "amount": 1000,
      "description": "Order #12345"
    }
  ]
}
```
```

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

### Initialize Connector using Factory Method

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/connector.md

Utilize the static 'make' method for a convenient way to create a connector instance with the API key and an optional sandbox flag.

```php
use JeffreyVanHees\OnlinePaymentPlatform\OnlinePaymentPlatformConnector;

// Using factory method
$connector = OnlinePaymentPlatformConnector::make('api-key-here');
```

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

### Get Merchant Charge

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/merchants-subresources.md

Retrieves the details of a specific charge associated with a merchant.

```php
public function get(string $chargeUid): Response
```

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

### Access Charges Resource

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/connector.md

Get the ChargesResource for managing balance transfers between merchants.

```php
$charges = $connector->charges();
```

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

### Handle Disputes with Evidence

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/other-resources.md

Illustrates how to handle disputes by uploading evidence files and then creating a dispute with the uploaded evidence. Requires file upload and dispute creation steps.

```php
// 1. Upload evidence file
$upload = OnlinePaymentPlatform::files()->createUpload([
    'filename' => 'tracking.pdf',
    'purpose' => 'dispute_evidence'
]);

OnlinePaymentPlatform::files()->upload(
    $upload->dto()->uid,
    $upload->dto()->token,
    '/path/to/tracking.pdf',
    'tracking.pdf'
);

// 2. Create dispute
$dispute = OnlinePaymentPlatform::disputes()->create([
    'transaction_uid' => 'tra_123456789',
    'amount' => 1000,
    'reason' => 'Product not received',
    'evidence' => ['file_uid' => $upload->dto()->uid]
]);
```

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

### Get Merchant Details

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Retrieves the details of a specific merchant using their unique identifier.

```APIDOC
## GET /v1/merchants/{merchant_uid}

### Description
Retrieves the details of a specific merchant.

### Method
GET

### Endpoint
/v1/merchants/{merchant_uid}

### Parameters
#### Path Parameters
- **merchant_uid** (string) - Required - The unique identifier of the merchant.

### Response
#### Success Response (200 OK)
- **merchant_uid** (string) - The unique identifier for the merchant.
- **name** (string) - The name of the business.
- **email** (string) - The email address of the merchant.
- **phone_number** (string) - The phone number of the merchant.
- **address** (object) - The address details of the merchant.
  - **street_line1** (string) - Street name and number.
  - **street_line2** (string) - Additional street details.
  - **city** (string) - City.
  - **state_province** (string) - State or province.
  - **postal_code** (string) - Postal code.
  - **country_code** (string) - ISO 3166-1 alpha-2 country code.
- **status** (string) - The current status of the merchant.
- **created_at** (string) - Timestamp when the merchant was created.
- **updated_at** (string) - Timestamp when the merchant was last updated.

#### Response Example
```json
{
  "merchant_uid": "mer_xxxxxxxxxxxxxx",
  "name": "Example Business",
  "email": "contact@example.com",
  "phone_number": "+31201234567",
  "address": {
    "street_line1": "Example Street 1",
    "city": "Amsterdam",
    "postal_code": "1000AA",
    "country_code": "NL"
  },
  "status": "live",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}
```
```

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

### Get Transaction

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/transactions.md

Retrieves the details of a specific payment transaction using its unique identifier.

```APIDOC
## GET /transactions/{transactionUid}

### Description
Retrieves the details of a specific transaction by its unique identifier (UID).

### Method
GET

### Endpoint
/transactions/{transactionUid}

### Parameters
#### Path Parameters
- **transactionUid** (string) - Required - The unique identifier of the transaction (e.g., 'tra_123456789').

### Request Example
```php
$response = OnlinePaymentPlatform::transactions()->get('tra_123456789');
$transaction = $response->dto();
echo "Status: {$transaction->status}";
echo "Amount: {$transaction->total_price} cents";
echo "Merchant: {$transaction->merchant_uid}";
```

### Response
#### Success Response (200)
- **uid** (string) - The unique identifier of the transaction.
- **status** (string) - The current status of the transaction (e.g., pending, authorized, captured, failed, refunded, cancelled).
- **total_price** (int) - The total amount in cents.
- **merchant_uid** (string) - The UID of the merchant.

#### Response Example
```json
{
  "uid": "tra_abcdef123456",
  "status": "authorized",
  "total_price": 2850,
  "merchant_uid": "mer_123456789",
  "created_at": "2023-10-27T10:00:00+00:00"
}
```

### Errors
- **ApiException**: When transaction not found or other API errors.
- **AuthenticationException**: When API key is invalid.
```

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

### Partners Resource

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

Operations for retrieving and updating partner configurations, and getting merchant balances.

```APIDOC
## Partners Resource

### Description
Operations for retrieving and updating partner configurations, and getting merchant balances.

### Methods
- `getConfiguration()`: Retrieve partner configuration.
- `updateConfiguration()`: Update configuration (notify_url only).
- `getMerchantBalance()`: Get merchant balance.
```

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

### Delete Mandate

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Example of how to delete a mandate using its unique identifier (UID). This action is irreversible.

```php
// Delete mandate
OnlinePaymentPlatform::mandates()->delete('man_123456789');
```

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

### Verify Environment Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/errors.md

Confirm that the sandbox or production environment setting is correct.

```php
// Make sure you're using correct environment
OPP_SANDBOX=true  // for sandbox
OPP_SANDBOX=false // for production
```

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

### API Status Check

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/api-documentation.md

Check if the API is operational by making a GET request to the /status endpoint.

```bash
GET /status
```

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

### Initialize Connector using Constructor

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/connector.md

Use the constructor to create a new connector instance, providing the API key and an optional sandbox flag.

```php
use JeffreyVanHees\OnlinePaymentPlatform\OnlinePaymentPlatformConnector;

// Using constructor
$connector = new OnlinePaymentPlatformConnector('api-key-here', true);
```

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

### Get Merchant Balance

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/other-resources.md

Retrieves the balance information for a specified merchant using their unique UID.

```php
public function getMerchantBalance(string $merchantUid): Response
```
$balance = OnlinePaymentPlatform::partners()->getMerchantBalance('mer_123456789');
$balanceData = $balance->dto();
echo "Balance: {$balanceData->amount}";
```

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

### Configuration and Utility Methods

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/connector.md

Includes methods for configuring the connector's base URL, default headers, authentication, and checking the operational environment.

```APIDOC
## Configuration Methods

### resolveBaseUrl()

Determines the base URL for API requests based on the environment setting.

**Returns:** string (either sandbox or production URL)

| Sandbox | URL |
|---------|-----|
| true | `https://api-sandbox.onlinebetaalplatform.nl/v1` |
| false | `https://api.onlinebetaalplatform.nl/v1` |

### defaultHeaders()

Provides default HTTP headers for all requests.

**Returns:** array
```php
[
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
]
```

### defaultAuth()

Configures the authentication mechanism using the API key.

**Returns:** `TokenAuthenticator` with the configured API key

## Utility Methods

### isSandbox()

Checks whether the connector is operating in sandbox or production mode.

**Returns:** boolean

**Example:**
```php
if ($connector->isSandbox()) {
    // Sandbox-only operations
}
```

### getNotifyUrl()

Retrieves the configured webhook notification URL from Laravel config.

**Returns:** string or null

### getReturnUrl()

Retrieves the configured return URL from Laravel config.

**Returns:** string or null
```

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

### List Merchants

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

Retrieves a list of merchants. This is a basic example of interacting with the Merchants resource via the facade.

```php
OnlinePaymentPlatform::merchants()->list()
```

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

### Get Response JSON

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

Retrieves the raw JSON response body as an array using the `json()` method.

```php
$response = OnlinePaymentPlatform::merchants()->list();

$jsonData = $response->json();

print_r($jsonData);
```

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

### Configuration

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/README.md

This section outlines the configuration options for the SDK, including API credentials, environment settings, HTTP and retry configurations, URL and webhook settings, and logging/caching options.

```APIDOC
## Configuration

This section outlines the configuration options for the SDK.

- **API Credentials**: `api_key`, `sandbox_api_key`
- **Environment**: `sandbox` flag, base URLs
- **HTTP Configuration**: `timeout`, `connect_timeout`
- **Retry Configuration**: `retry.times`, `retry.sleep`
- **URL Configuration**: `notify_url`, `return_url`
- **Webhook Configuration**: `notify_secret` for signature verification
- **Logging Configuration**: enable, channel, level
- **Cache Configuration**: enable, store, TTL
- Environment variables reference table
- Runtime configuration access
- Testing configuration
```

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

### Configure API Credentials and URLs

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/README.md

Configure your API credentials and URLs in the .env file. Ensure you replace placeholders with your actual keys and URLs.

```env
OPP_API_KEY=your_production_api_key_here
OPP_SANDBOX_API_KEY=your_sandbox_api_key_here
OPP_SANDBOX=true

OPP_NOTIFY_URL=https://yourapp.com/webhooks/opp
OPP_RETURN_URL=https://yourapp.com/payment/return

OPP_NOTIFY_SECRET=your_webhook_secret
```

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

### Webhook Processing with Signature Verification

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/INDEX.md

Example of how to process incoming webhooks, including verifying the signature to ensure authenticity.

```php
use Illuminate\Http\Request;
use JeffreyVonEuw\bursement\Facades\OnlinePaymentPlatform;

public function handleWebhook(Request $request)
{
    if (!OnlinePaymentPlatform::webhooks()->verifySignature($request)) {
        return response('Invalid signature', 400);
    }

    $payload = $request->json()->all();
    // Process the webhook payload

    return response('Webhook received');
}
```

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

### Standard SDK File Structure

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/docs/saloon-implementation-guide.md

Illustrates a recommended directory structure for organizing SaloonPHP SDK components, promoting maintainability and clarity.

```bash
src/
├── OnlinePaymentPlatformConnector.php
├── Resources/
│   ├── MerchantsResource.php
│   ├── TransactionsResource.php
│   └── ...
├── Requests/
│   ├── Merchants/
│   ├── Transactions/
│   └── ...
├── Data/
│   ├── Requests/
│   ├── Responses/
│   └── Common/
└── Exceptions/

```

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

### Handling ValidationException

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/errors.md

Example of catching a ValidationException to display user-friendly error messages and iterate through specific validation errors.

```php
try {
    $merchant = OnlinePaymentPlatform::merchants()->create([
        'type' => 'consumer',
        // Missing required country field
        'emailaddress' => 'user@example.com'
    ]);
} catch (ValidationException $e) {
    echo "Validation failed: " . $e->getMessage();
    
    // Get all validation errors
    $errors = $e->getMeta()['errors'] ?? [];
    foreach ($errors as $field => $messages) {
        echo "{$field}: " . implode(', ', $messages);
    }
}
```

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

### BankAccountsResource - Get Bank Account

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/merchants-subresources.md

Retrieves the details of a specific merchant bank account using its unique identifier.

```APIDOC
## GET /merchants/{merchantUid}/bank-accounts/{bankAccountUid}

### Description
Retrieves a specific bank account.

### Method
GET

### Endpoint
`/merchants/{merchantUid}/bank-accounts/{bankAccountUid}`

### Parameters
#### Path Parameters
- **merchantUid** (string) - Required - The unique identifier of the merchant.
- **bankAccountUid** (string) - Required - The unique identifier of the bank account.

### Response
#### Success Response (200)
- **account.account_iban** (string) - The IBAN of the bank account.
- **account.account_name** (string) - The name associated with the bank account.
- **bank.bic** (string) - The BIC (SWIFT code) of the bank.
- **bank.bank_name** (string) - The name of the bank.

### Response Example
```json
{
  "account": {
    "account_iban": "iban_123456789",
    "account_name": "Account Holder Name"
  },
  "bank": {
    "bic": "BICCODE",
    "bank_name": "Bank Name"
  }
}
```
```

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

### Environment-Based Configuration for Connector

Source: https://github.com/jeffreyvanhees/laravel-online-payment-platform/blob/main/_autodocs/api-reference/facade-and-integration.md

Demonstrates how to configure the OnlinePaymentPlatformConnector in a non-Laravel context by reading API key and sandbox mode from environment variables.

```php
// In non-Laravel context, provide explicit parameters
$connector = new OnlinePaymentPlatformConnector(
    apiKey: $_ENV['OPP_API_KEY'],
    sandbox: $_ENV['OPP_SANDBOX'] === 'true'
);
```