### Create a Product Instance

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/product.md

Example of instantiating a Product object with required parameters.

```php
use AratKruglik\WayForPay\Domain\Product;

$product = new Product(
    name: 'Blue T-Shirt Size M',
    price: 150.00,
    count: 2
);
```

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

### Install WayForPay Laravel Package

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Use Composer to install the package.

```bash
composer require aratkruglik/wayforpay-laravel
```

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

### Merchant Instantiation Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/merchant.md

Example of how to create a new Merchant object with compensation card details. Ensure all required parameters are provided and compensation details are valid.

```php
use AratKruglik\WayForPay\Domain\Merchant;
use AratKruglik\WayForPay\Domain\CompensationCard;

$merchant = new Merchant(
    site: 'https://sub-merchant.com',
    phone: '+380501234567',
    email: 'merchant@example.com',
    description: 'Sub-merchant description',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111'
    )
);
```

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

### Example: P2P Account Transfer

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/wayforpay-service.md

Illustrates creating an AccountTransfer object and initiating a P2P transfer.

```php
use AratKruglik\WayForPay\Domain\AccountTransfer;

$transfer = new AccountTransfer(
    orderReference: 'TRANSFER_001',
    amount: 1500.00,
    currency: 'UAH',
    iban: 'UA213223130000026007233566001',
    okpo: '12345678',
    accountName: 'FOP Ivanov I.I.',
    description: 'Payout for services',
    serviceUrl: 'https://myshop.com/api/wayforpay/callback',
    recipientEmail: 'recipient@example.com'
);

$response = WayForPay::p2pAccount($transfer);
```

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

### Instantiate Client Object

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/client.md

Example of creating a new Client object with all available parameters. This demonstrates how to populate customer information for a payment transaction.

```php
use AratKruglik\WayForPay\Domain\Client;

$client = new Client(
    nameFirst: 'John',
    nameLast: 'Doe',
    email: 'john@example.com',
    phone: '+380501234567',
    address: '123 Main St',
    city: 'Kyiv',
    country: 'UA'
);
```

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

### ReasonCode Usage Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/types.md

Demonstrates how to check if a transaction was successful using `isSuccess()` or get its description using `getDescription()`.

```php
use AratKruglik\WayForPay\Enums\ReasonCode;

$code = ReasonCode::tryFrom(1100);

if ($code?->isSuccess()) {
    echo "Transaction successful";
}

echo $code?->getDescription(); // "Operation was performed without errors"
```

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

### Example: Handle Webhook

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/wayforpay-service.md

Demonstrates handling a webhook request, including error catching for WayForPay exceptions.

```php
use AratKruglik\WayForPay\Contracts\WayForPayInterface;
use AratKruglik\WayForPay\Exceptions\WayForPayException;

public function handle(Request $request, WayForPayInterface $wayforpay)
{
    try {
        $response = $wayforpay->handleWebhook($request->all());
        return response()->json($response);
    } catch (WayForPayException $e) {
        return response()->json(['status' => 'error'], 400);
    }
}
```

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

### Usage Example: Handling WayForPayException

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle WayForPayException, logging relevant details like message, reason code, and response data.

```php
use AratKruglik\WayForPay\Exceptions\WayForPayException;
use AratKruglik\WayForPay\Enums\ReasonCode;

try {
    $response = WayForPay::charge($transaction, $card);
} catch (WayForPayException $e) {
    $reasonCode = $e->getReasonCode();
    
    if ($reasonCode?->isSuccess()) {
        // Successful despite exception - shouldn't happen
    } else {
        // Handle failure
        Log::error('Payment failed', [
            'message' => $e->getMessage(),
            'reason_code' => $reasonCode?->value,
            'reason_description' => $reasonCode?->getDescription(),
            'response_data' => $e->getResponseData(),
        ]);
    }
}
```

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

### Production Environment Configuration

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Example `.env` file settings for the production environment, using live credentials, the production domain, a standard timeout, and debug mode disabled.

```env
# .env.production
WAYFORPAY_MERCHANT_ACCOUNT=prod_merchant
WAYFORPAY_SECRET_KEY=prod_secret_key
WAYFORPAY_MERCHANT_DOMAIN=myshop.com
WAYFORPAY_TIMEOUT=30
WAYFORPAY_DEBUG=false
```

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

### Service Provider Registration (Manual)

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Example of manually registering the WayForPay service provider and its aliases in the `config/app.php` file if auto-discovery is not functioning.

```php
// config/app.php
'providers' => [
    AratKruglik\WayForPay\WayForPayServiceProvider::class,
],

'aliases' => [
    'WayForPay' => AratKruglik\WayForPay\Facades\WayForPay::class,
    'Mms' => AratKruglik\WayForPay\Facades\Mms::class,
],
```

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

### Development Environment Configuration

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Example `.env` file settings for the development environment, including test credentials, local domain, increased timeout, and debug mode enabled.

```env
# .env.local or .env.dev
WAYFORPAY_MERCHANT_ACCOUNT=test_merchant
WAYFORPAY_SECRET_KEY=test_secret_key
WAYFORPAY_MERCHANT_DOMAIN=localhost:8000
WAYFORPAY_TIMEOUT=60
WAYFORPAY_DEBUG=true
```

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

### CompensationType Usage Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/types.md

Demonstrates how to use the CompensationType enum to specify payout methods.

```php
use AratKruglik\WayForPay\Enums\CompensationType;

$type = CompensationType::ACCOUNT;
echo $type->value; // 'account'
```

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

### Webhook Controller and Listener Setup

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/webhook-controller.md

Configure API routes to direct WayForPay callbacks to the WebhookController. Implement an event listener to process the WayForPayCallbackReceived event, updating order status based on transaction status and sending confirmation emails.

```php
// routes/api.php
Route::post('wayforpay/callback', WebhookController::class);

// app/Listeners/ProcessWayForPayWebhook.php
use AratKruglik\WayForPay\Events\WayForPayCallbackReceived;

class ProcessWayForPayWebhook
{
    public function handle(WayForPayCallbackReceived $event)
    {
        $data = $event->data;
        $order = Order::where('reference', $data['orderReference'])->first();

        if (!$order) {
            return;
        }

        match ($data['transactionStatus']) {
            'Approved' => $order->markAsPaid(),
            'Refunded' => $order->markAsRefunded(),
            'Declined' => $order->markAsFailed(),
            default => null,
        };

        // Send confirmation email
        Mail::to($order->customer->email)
            ->send(new OrderStatusChanged($order));
    }
}

// In EventServiceProvider or bootstrap
Event::listen(WayForPayCallbackReceived::class, ProcessWayForPayWebhook::class);
```

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

### Instantiate AccountTransfer

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/account-transfer.md

Example of creating a new AccountTransfer object with all necessary parameters, including optional ones like description and serviceUrl. Ensure currency is 'UAH' for P2P transfers.

```php
use AratKruglik\WayForPay\Domain\AccountTransfer;

$transfer = new AccountTransfer(
    orderReference: 'TRANSFER_001',
    amount: 1500.00,
    currency: 'UAH',
    iban: 'UA213223130000026007233566001',
    okpo: '12345678',
    accountName: 'FOP Ivanov I.I.',
    description: 'Payout for services',
    serviceUrl: 'https://myshop.com/api/wayforpay/callback',
    recipientEmail: 'recipient@example.com'
);
```

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

### toArray() Usage Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/merchant.md

Demonstrates calling the toArray() method on a Merchant object to get data for API requests. The resulting array contains all relevant merchant and compensation information.

```php
$data = $merchant->toArray();
// Includes: site, phone, email, description,
//           plus all fields from compensation method
```

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

### Signed Webhook Response Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/webhook-controller.md

Example of a signed JSON response expected by WayForPay for acknowledging webhook receipt. The signature is computed using HMAC-MD5.

```json
{
    "orderReference": "ORDER_001",
    "status": "accept",
    "time": 1234567890,
    "signature": "abc123def456..."
}
```

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

### Example: Remove Recurring Payment

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/wayforpay-service.md

Demonstrates how to call the removeRecurring method with a specific order reference.

```php
WayForPay::removeRecurring('SUB_123');
```

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

### Usage Example: Handling SignatureMismatchException

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/errors.md

Shows how to catch SignatureMismatchException for webhook security and other WayForPayExceptions for general validation errors, returning appropriate HTTP responses.

```php
use AratKruglik\WayForPay\Exceptions\SignatureMismatchException;
use AratKruglik\WayForPay\Exceptions\WayForPayException;

try {
    $response = WayForPayService::handleWebhook(request()->all());
} catch (SignatureMismatchException $e) {
    // Security issue - signature doesn't match
    Log::warning('Webhook signature mismatch', [
        'ip' => request()->ip(),
        'user_agent' => request->userAgent(),
    ]);
    
    return response()->json([
        'status' => 'error',
        'message' => 'Invalid signature'
    ], 403);
} catch (WayForPayException $e) {
    // Other validation errors
    return response()->json([
        'status' => 'error',
        'message' => $e->getMessage()
    ], 400);
}
```

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

### TransactionStatus Usage Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/types.md

Shows how to check if a transaction status is final or indicates success.

```php
use AratKruglik\WayForPay\Enums\TransactionStatus;

$status = TransactionStatus::APPROVED;

if ($status->isFinal()) {
    // Stop checking status
}

if ($status->isSuccess()) {
    // Order was successfully paid
}
```

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

### Perform P2P Account Transfer

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/account-transfer.md

Example of using the WayForPayService facade to initiate a P2P account transfer. This involves creating an AccountTransfer object and passing it to the p2pAccount method.

```php
use AratKruglik\\.WayForPay\\Facades\\WayForPay;
use AratKruglik\\WayForPay\\Domain\\AccountTransfer;

$transfer = new AccountTransfer(
    orderReference: 'TRANSFER_001',
    amount: 1500.00,
    currency: 'UAH',
    iban: 'UA213223130000026007233566001',
    okpo: '12345678',
    accountName: 'FOP Ivanov I.I.',
    description: 'Payout for services',
    serviceUrl: 'https://myshop.com/api/wayforpay/callback',
    recipientEmail: 'recipient@example.com'
);

$response = WayForPay::p2pAccount($transfer);

// Response includes transfer status and transaction reference
```

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

### Accessing Partner Public Properties

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/partner.md

All properties of the Partner object are read-only and can be accessed directly. This example shows how to retrieve the partner's code.

```php
$partner->partnerCode;
```

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

### Registering a Sub-Merchant with MmsService

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/merchant.md

Example of registering a new sub-merchant using the MmsService. This involves creating a Merchant object and passing it to the addMerchant method. The response contains the new merchant's account ID and API key.

```php
use AratKruglik\WayForPay\Facades\Mms;
use AratKruglik\WayForPay\Domain\Merchant;
use AratKruglik\WayForPay\Domain\CompensationCard;

$merchant = new Merchant(
    site: 'https://sub-merchant.com',
    phone: '+380501234567',
    email: 'merchant@example.com',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111'
    )
);

$response = Mms::addMerchant($merchant);

// Response includes:
// - merchantAccount (account ID for the new sub-merchant)
// - secretKey (API key for the sub-merchant)
```

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

### Purchase and Get Purchase Form Data Methods

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/adr/0002-purchase-returns-html-form.md

Defines the signatures for the purchase method, which returns an HTML string, and getPurchaseFormData, which returns an array of form data. Use purchase() for direct integration and getPurchaseFormData() for custom form rendering.

```php
public function purchase(Transaction $transaction, ?string $returnUrl = null, ?string $serviceUrl = null): string;
public function getPurchaseFormData(Transaction $transaction, ?string $returnUrl = null, ?string $serviceUrl = null): array;
```

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

### Listen for WayForPay Callback Event

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/webhook-controller.md

Listen for the WayForPayCallbackReceived event to process webhook data within your application. This example shows how to update order status based on transaction status.

```php
use AratKruglik\WayForPay\Events\WayForPayCallbackReceived;
use Illuminate\Support\Facades\Event;

Event::listen(WayForPayCallbackReceived::class, function ($event) {
    $data = $event->data;

    // Process the webhook
    if ($data['transactionStatus'] === 'Approved') {
        // Order paid
        Order::where('reference', $data['orderReference'])->update(['paid' => true]);
    }

    if ($data['transactionStatus'] === 'Refunded') {
        // Order refunded
        Order::where('reference', $data['orderReference'])->update(['refunded' => true]);
    }
});
```

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

### Register Partner with Compensation Card

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/compensation-card.md

Use CompensationCard when registering a partner or merchant to specify their payout method. This example shows how to create a Partner object with an associated CompensationCard and add it via the MMS facade.

```php
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationCard;
use AratKruglik\WayForPay\Facades\Mms;

$partner = new Partner(
    partnerCode: 'PARTNER_001',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111',
        expMonth: '12',
        expYear: '25'
    )
);

Mms::addPartner($partner);
```

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

### Product Constructor

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/product.md

Initializes a new Product object with name, price, and count. Performs validation on input parameters.

```APIDOC
## Product Constructor

### Description
Initializes a new Product object with name, price, and count. Performs validation on input parameters.

### Method
`__construct(string $name, float $price, int $count)`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **name** (string) - Required - Product name (1-255 characters, non-empty)
- **price** (float) - Required - Unit price in major currency units (>= 0)
- **count** (int) - Required - Quantity ordered (>= 1)

### Throws
`InvalidArgumentException` for invalid name, price, or count during construction

### Example
```php
use AratKruglik\WayForPay\Domain\Product;

$product = new Product(
    name: 'Blue T-Shirt Size M',
    price: 150.00,
    count: 2
);
```
```

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

### Instantiate Transaction with Client and Options

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/transaction.md

Create a new Transaction object, including optional client details and payment system configurations. Ensure all required parameters like order reference, amount, currency, and order date are provided.

```php
use AratKruglik\WayForPay\Domain\Transaction;
use AratKruglik\WayForPay\Domain\Client;

$client = new Client(
    nameFirst: 'John',
    nameLast: 'Doe',
    email: 'john@example.com',
    phone: '+380501234567'
);

$transaction = new Transaction(
    orderReference: 'ORDER_001',
    amount: 150.75,
    currency: 'UAH',
    orderDate: time(),
    client: $client,
    paymentSystems: 'card;googlePay;applePay',
    orderTimeout: 3600
);
```

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

### Product Constructor

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/product.md

Initializes a new Product object. Throws InvalidArgumentException for invalid name, price, or count.

```php
public function __construct(
    public string $name,
    public float $price,
    public int $count
)
```

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

### ReasonCode Enum

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/PRD.md

Represents the possible reason codes for a WayForPay transaction. Provides methods to check for success and get a description.

```php
enum ReasonCode: int
{
    case OK = 1100;
    case DECLINED_BY_ISSUER = 1101;
    case BAD_CVV2 = 1102;
    case EXPIRED_CARD = 1103;
    case INSUFFICIENT_FUNDS = 1104;
    case INVALID_CARD = 1105;
    case EXCEED_WITHDRAWAL_FREQUENCY = 1106;
    case THREE_DS_FAIL = 1108;
    case FORMAT_ERROR = 1109;
    case TRANSACTION_NOT_ALLOWED = 1114;
    case SYSTEM_ERROR = 1116;
    case DUPLICATE_ORDER_REFERENCE = 1118;
    case SIGNATURE_MISMATCH = 1124;
    case MERCHANT_DISABLED = 1125;
    case REGULAR_OK = 4100;
    case REGULAR_NOT_FOUND = 4101;
    case REGULAR_ALREADY_ACTIVE = 4102;
    case REGULAR_SUSPENDED = 4103;

    public function isSuccess(): bool
    {
        return $this === self::OK || $this === self::REGULAR_OK;
    }

    public function getDescription(): string
    {
        return match ($this) {
            self::OK => 'Operation successful',
            self::DECLINED_BY_ISSUER => 'Issuing bank refused',
            self::BAD_CVV2 => 'Wrong CVV code',
            self::EXPIRED_CARD => 'Card expired',
            self::INSUFFICIENT_FUNDS => 'Insufficient funds',
            self::INVALID_CARD => 'Invalid card number or status',
            self::EXCEED_WITHDRAWAL_FREQUENCY => 'Card operation limit exceeded',
            self::THREE_DS_FAIL => '3DS transaction failed',
            self::FORMAT_ERROR => 'Format error',
            self::TRANSACTION_NOT_ALLOWED => 'Transaction not allowed',
            self::SYSTEM_ERROR => 'System error',
            self::DUPLICATE_ORDER_REFERENCE => 'Duplicate order reference',
            self::SIGNATURE_MISMATCH => 'Signature mismatch',
            self::MERCHANT_DISABLED => 'Merchant account disabled',
            self::REGULAR_OK => 'Regular operation successful',
            self::REGULAR_NOT_FOUND => 'Subscription not found',
            self::REGULAR_ALREADY_ACTIVE => 'Subscription already active',
            self::REGULAR_SUSPENDED => 'Subscription suspended',
        };
    }
}
```

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

### Configure WayForPay Credentials

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Add your WayForPay merchant account, secret key, and domain to your .env file.

```env
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant_login
WAYFORPAY_SECRET_KEY=your_secret_key
WAYFORPAY_MERCHANT_DOMAIN=your_domain.com
```

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

### Client Constructor

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/client.md

Initializes a new Client object with customer details. All parameters are optional and have default null values. Validation is performed on email, phone, and country formats.

```APIDOC
## Constructor Client

### Description
Initializes a new Client object with customer details. All parameters are optional and have default null values. Validation is performed on email, phone, and country formats.

### Method
__construct

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
use AratKruglik\WayForPay\Domain\Client;

$client = new Client(
    nameFirst: 'John',
    nameLast: 'Doe',
    email: 'john@example.com',
    phone: '+380501234567',
    address: '123 Main St',
    city: 'Kyiv',
    country: 'UA'
);
```

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

#### Response Example
None

### Throws
`InvalidArgumentException` for invalid email, phone, or country format during construction
```

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

### Get Merchant Balance

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Fetch the current merchant balance. An optional date can be provided to query the balance for a specific day in 'dd.mm.yyyy' format.

```php
use AratKruglik\WayForPay\Facades\Mms;

$balance = Mms::merchantBalance();

// With date filter (dd.mm.yyyy format)
$balance = Mms::merchantBalance('01.01.2026');
```

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

### Register Partner with Compensation Account

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/compensation-account.md

Demonstrates how to create a Partner object and associate it with a CompensationAccount, then add the partner using the MMS facade.

```php
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationAccount;
use AratKruglik\WayForPay\Facades\Mms;

$partner = new Partner(
    partnerCode: 'PARTNER_002',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    compensationAccount: new CompensationAccount(
        iban: 'UA213223130000026007233566001',
        okpo: '12345678',
        name: 'FOP Partner Name'
    )
);

Mms::addPartner($partner);
```

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

### ReasonCode Enum Definition

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/types.md

Defines transaction result codes from the WayForPay API. Use `tryFrom()` to get an enum instance from an integer value.

```php
enum ReasonCode: int
{
    case OK = 1100;
    case DECLINED_BY_ISSUER = 1101;
    case BAD_CVV2 = 1102;
    case EXPIRED_CARD = 1103;
    case INSUFFICIENT_FUNDS = 1104;
    case INVALID_CARD = 1105;
    case EXCEED_WITHDRAWAL_FREQUENCY = 1106;
    case THREE_DS_FAIL = 1108;
    case FORMAT_ERROR = 1109;
    case TRANSACTION_NOT_ALLOWED = 1114;
    case SYSTEM_ERROR = 1116;
    case DUPLICATE_ORDER_REFERENCE = 1118;
    case SIGNATURE_MISMATCH = 1124;
    case MERCHANT_DISABLED = 1125;
    case REGULAR_OK = 4100;
    case REGULAR_NOT_FOUND = 4101;
    case REGULAR_ALREADY_ACTIVE = 4102;
    case REGULAR_SUSPENDED = 4103;
}
```

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

### Add Products to Transaction

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/product.md

Shows how to add Product instances to a Transaction object before retrieving them.

```php
$transaction = new Transaction(
    orderReference: 'ORDER_001',
    amount: 250.00,
    currency: 'UAH',
    orderDate: time()
);

$transaction->addProduct(new Product('Item 1', 100.00, 1))
    ->addProduct(new Product('Item 2', 150.00, 1));

// Later, when processing:
$products = $transaction->getProducts();
```

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

### HMAC-Authenticated Operation Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/adr/0006-dual-authentication-modes.md

This snippet demonstrates how to generate an HMAC signature for a refund operation and send the request to the WayForPay API. It is used for most API operations.

```php
$data['merchantSignature'] = $this->signatureGenerator->generateForRefund($data);
return $this->sendRequest($data); // -> api.wayforpay.com/api
```

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

### Access Configuration Values in Code

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Retrieve WayForPay configuration values within your Laravel application using the Config facade. Ensure the package is installed and configured.

```php
use Illuminate\Support\Facades\Config;

$merchantAccount = Config::get('wayforpay.merchant_account');
$secretKey = Config::get('wayforpay.secret_key');
$merchantDomain = Config::get('wayforpay.merchant_domain');
$timeout = Config::get('wayforpay.timeout');
$debug = Config::get('wayforpay.debug');
```

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

### Initialize Partner with Compensation Account

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/partner.md

Use this snippet to create a Partner object when payouts are to be made to a bank account. This requires providing an IBAN, OKPO code, and account holder name.

```php
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationAccount;

$partner = new Partner(
    partnerCode: 'PARTNER_002',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    compensationAccount: new CompensationAccount(
        iban: 'UA213223130000026007233566001',
        okpo: '12345678',
        name: 'FOP Partner Name'
    )
);
```

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

### Instantiate CompensationCard (Full)

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/compensation-card.md

Create a CompensationCard with all available details, including card number, expiration date, CVV, and holder name. Use this when all card information is available and required.

```php
use AratKruglik\WayForPay\Domain\CompensationCard;

// Full: with expiry and CVV
$compensationCard = new CompensationCard(
    cardNumber: '4111-1111-1111-1111',
    expMonth: '12',
    expYear: '25',
    cvv: '123',
    holderName: 'PARTNER NAME'
);
```

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

### Service Provider Registration (Auto-Discovery)

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

The WayForPay service provider is typically auto-registered by Laravel. This example shows how it would appear in `config/app.php` if manual registration were needed.

```php
// config/app.php - auto-registered
'providers' => [
    // ...
    AratKruglik\WayForPay\WayForPayServiceProvider::class,
],

'aliases' => [
    // ...
    'WayForPay' => AratKruglik\WayForPay\Facades\WayForPay::class,
    'Mms' => AratKruglik\WayForPay\Facades\Mms::class,
],
```

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

### Retrieve Merchant Balance

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/mms-service.md

Gets the current balance for the merchant. Optionally, you can specify a cutoff date to retrieve the balance as of that date. The balance is returned with amounts by currency.

```php
public function merchantBalance(?string $toDate = null): array
```

```php
// Current balance
$balance = Mms::merchantBalance();

// Balance as of specific date
$balance = Mms::merchantBalance('01.01.2026');

echo $balance['UAH']; // UAH balance
echo $balance['USD']; // USD balance
```

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

### Instantiate CompensationCard (Minimal)

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/compensation-card.md

Create a CompensationCard with only the required card number. This is useful when only the card number is needed for compensation.

```php
use AratKruglik\WayForPay\Domain\CompensationCard;

// Minimal: card number only
$compensationCard = new CompensationCard(
    cardNumber: '4111111111111111'
);
```

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

### Webhook Error Response - Signature Mismatch

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/PRD.md

Example of an error response when a webhook signature does not match. Returns a 403 HTTP status with a JSON body indicating the error.

```json
{"status": "error", "message": "Invalid signature"}
```

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

### Access WayForPay Services via Facades

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/README.md

Demonstrates how to use the WayForPay and MMS facades to access various payment and marketplace functionalities. Ensure facades are correctly configured in your Laravel application.

```php
use AratKruglik\WayForPay\Facades\WayForPay;
use AratKruglik\WayForPay\Facades\Mms;

WayForPay::purchase($transaction);
WayForPay::charge($transaction, $card);

Mms::addPartner($partner);
Mms::merchantBalance();
```

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

### Invalid Card Data Example

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/errors.md

Demonstrates catching an InvalidArgumentException when creating a Card object with invalid data, such as a too-short card number. Logs the specific error message.

```php
use AratKruglik\WayForPay\Domain\Card;

try {
    $card = new Card(
        cardNumber: '1234', // Too short!
        expMonth: '12',
        expYear: '25',
        cvv: '123'
    );
} catch (InvalidArgumentException $e) {
    Log::error('Invalid card data', [
        'error' => $e->getMessage() // "Card number must be between 13 and 19 digits"
    ]);
}
```

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

### Purchase Transaction via Facade

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/PRD.md

Initiates a payment transaction using the WayForPay Facade. Requires the transaction details and a return URL. The response is HTML to be rendered to the user.

```php
use AratKruglik\WayForPay\Facades\WayForPay;

$html = WayForPay::purchase($transaction, returnUrl: 'https://example.com/thanks');
return response($html);
```

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

### Initialize Partner with Compensation Card

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/partner.md

Use this snippet to create a Partner object when payouts are to be made to a credit card. Ensure you provide all required parameters and a valid CompensationCard object.

```php
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationCard;

$partner = new Partner(
    partnerCode: 'PARTNER_001',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    description: 'Partner shop description',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111',
        expMonth: '12',
        expYear: '25',
        cvv: '123',
        holderName: 'PARTNER NAME'
    )
);
```

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

### Publish WayForPay Configuration File

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Publish the WayForPay configuration file to your project's config directory using the artisan command. This allows for direct modification of settings.

```bash
php artisan vendor:publish --tag=wayforpay-config
```

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

### Initialize Partner with Compensation Card Token

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/partner.md

Use this snippet to create a Partner object when payouts are to be made using a pre-existing tokenized card. This is an alternative to providing full card details.

```php
$partner = new Partner(
    partnerCode: 'PARTNER_003',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    compensationCardToken: 'card_token_from_wayforpay'
);
```

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

### Webhook Error Response - General Exception

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/PRD.md

Example of a general error response for webhook handling. Returns a 400 HTTP status with a JSON body detailing the error message.

```json
{"status": "error", "message": "..."}
```

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

### Instantiate CompensationAccount

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/compensation-account.md

Create a new CompensationAccount object with IBAN, OKPO, name, and an optional MFO. Ensure all parameters meet the specified format requirements.

```php
use AratKruglik\WayForPay\Domain\CompensationAccount;

$account = new CompensationAccount(
    iban: 'UA213223130000026007233566001',
    okpo: '12345678',
    name: 'FOP Ivanov I.I.',
    mfo: '305999'
);
```

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

### Run Tests

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Execute the project's tests using the Pest testing framework.

```bash
vendor/bin/pest
```

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

### Get Purchase Form Data for Custom Frontend

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/wayforpay-service.md

Retrieve raw form data to render a custom payment form within your single-page application or frontend. This allows for more control over the user interface.

```php
$formData = WayForPay::getPurchaseFormData($transaction, $returnUrl, $serviceUrl);

return response()->json([
    'form_action' => 'https://secure.wayforpay.com/pay',
    'form_data' => $formData,
]);
```

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

### Set Merchant Account via Environment Variable

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Configure your WayForPay merchant account login using the WAYFORPAY_MERCHANT_ACCOUNT environment variable.

```env
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant_login
```

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

### Convert Partner Object to Array

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/partner.md

Call the toArray() method on a Partner object to get an associative array suitable for API requests. This array includes all partner details and the merged compensation method data.

```php
$data = $partner->toArray();
// Includes: partnerCode, site, phone, email, description,
//           plus all fields from compensation method
```

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

### Partner Constructor

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/partner.md

Initializes a new Partner object. It requires core contact information and allows for specifying compensation details via card, bank account, or a tokenized card. Exactly one compensation method must be provided.

```APIDOC
## Constructor

### Description
Initializes a new Partner object with essential contact details and compensation information.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Constructor Parameters
- **partnerCode** (string) - Required - Unique partner identifier.
- **site** (string) - Required - Partner website URL (valid HTTP/HTTPS).
- **phone** (string) - Required - Contact phone number (6-20 chars, optional +, hyphens, spaces).
- **email** (string) - Required - Contact email address (valid format).
- **description** (string|null) - Optional - Partner description.
- **compensationCard** (CompensationCard|null) - Optional - Card details for payouts. Provide exactly one compensation method.
- **compensationAccount** (CompensationAccount|null) - Optional - Bank account details for payouts. Provide exactly one compensation method.
- **compensationCardToken** (string|null) - Optional - Tokenized card for payouts. Provide exactly one compensation method.

### Throws
`InvalidArgumentException` for invalid URL, email, or phone format.

### Note
Provide exactly ONE of: `compensationCard`, `compensationAccount`, or `compensationCardToken`.

### Example
```php
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationCard;

$partner = new Partner(
    partnerCode: 'PARTNER_001',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    description: 'Partner shop description',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111',
        expMonth: '12',
        expYear: '25',
        cvv: '123',
        holderName: 'PARTNER NAME'
    )
);
```
```

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

### Use MMS Facade or Constructor Injection

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Access the Marketplace Management System (MMS) API either through the `Mms` facade or by injecting the `MmsServiceInterface` into your controllers.

```php
use AratKruglik\WayForPay\Facades\Mms;

// Facade
Mms::addPartner($partner);
```

```php
use AratKruglik\WayForPay\Contracts\MmsServiceInterface;

class PartnerController extends Controller
{
    public function __construct(
        private readonly MmsServiceInterface $mms
    ) {}
}
```

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

### Password-Authenticated Operation Example (Regular API)

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/adr/0006-dual-authentication-modes.md

This snippet shows how to authenticate a request to the WayForPay Regular API using the merchant's secret key directly as the merchantPassword. This method is exclusively used for recurring subscription operations.

```php
$data = [
    'merchantPassword' => $this->secretKey,
    // ...
];
$response = $this->http->post('https://api.wayforpay.com/regularApi', $data);
```

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

### Process Payment using Widget

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/README.md

Initiates a payment transaction and generates an HTML form for the user to complete the payment. Ensure the necessary WayForPay facade and domain classes are imported.

```php
use AratKruglik\WayForPay\Facades\WayForPay;
use AratKruglik\WayForPay\Domain\Transaction;
use AratKruglik\WayForPay\Domain\Product;
use AratKruglik\WayForPay\Domain\Client;

// Create transaction
$transaction = new Transaction(
    orderReference: 'ORDER_' . time(),
    amount: 100.50,
    currency: 'UAH',
    orderDate: time(),
    client: new Client(
        nameFirst: 'John',
        nameLast: 'Doe',
        email: 'john@example.com',
        phone: '+380501234567'
    )
);

$transaction->addProduct(new Product('Item', 100.50, 1));

// Generate payment form
$html = WayForPay::purchase(
    $transaction,
    returnUrl: 'https://myshop.com/success',
    serviceUrl: 'https://myshop.com/api/wayforpay/callback'
);

return response($html);
```

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

### Client Constructor

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/client.md

Defines the constructor for the Client DTO, accepting various customer details as optional parameters. It includes type hints and default null values.

```php
public function __construct(
    public ?string $nameFirst = null,
    public ?string $nameLast = null,
    public ?string $email = null,
    public ?string $phone = null,
    public ?string $address = null,
    public ?string $city = null,
    public ?string $country = null
)
```

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

### Testing Commands

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/docs/PRD.md

Provides common commands for running tests with the Pest testing framework, including options for test suites and mutation testing.

```bash
vendor/bin/pest                    # Run all tests
vendor/bin/pest --testsuite=Unit   # Unit tests only
vendor/bin/pest --testsuite=Feature # Feature tests only
vendor/bin/pest --mutate           # Mutation testing
```

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

### Access Product Properties

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/product.md

Demonstrates direct read-only access to the 'name', 'price', and 'count' properties of a Product object.

```php
$product->name;    // string
$product->price;   // float
$product->count;   // int
```

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

### Complete WayForPay Configuration File

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

The default WayForPay configuration file (`config/wayforpay.php`) defines all available settings, including merchant credentials, API timeout, and debug mode, often referencing environment variables.

```php
// config/wayforpay.php

return [
    /*
    |--------------------------------------------------------------------------
    | WayForPay Merchant Credentials
    |--------------------------------------------------------------------------
    |
    | These credentials are used to authenticate with the WayForPay API.
    | You can find them in your WayForPay merchant cabinet.
    |
    */

    'merchant_account' => env('WAYFORPAY_MERCHANT_ACCOUNT', ''),
    'secret_key' => env('WAYFORPAY_SECRET_KEY', ''),
    'merchant_domain' => env('WAYFORPAY_MERCHANT_DOMAIN', ''),

    /*
    |--------------------------------------------------------------------------
    | Timeout
    |--------------------------------------------------------------------------
    |
    | The timeout for API requests in seconds.
    |
    */

    'timeout' => env('WAYFORPAY_TIMEOUT', 30),

    /*
    |--------------------------------------------------------------------------
    | Debug Mode
    |--------------------------------------------------------------------------
    |
    | If enabled, the package will log requests and responses.
    |
    */

    'debug' => env('WAYFORPAY_DEBUG', false),
];
```

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

### Register a New Partner with Bank Account Compensation

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Register a new partner with compensation details provided via bank account information. This includes IBAN, OKPO, and account holder name.

```php
use AratKruglik\WayForPay\Facades\Mms;
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationAccount;

// Option 2: Compensation via bank account
$partner = new Partner(
    partnerCode: 'PARTNER_002',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    compensationAccount: new CompensationAccount(
        iban: 'UA213223130000026007233566001',
        okpo: '12345678',
        name: 'FOP Partner Name'
    )
);

$response = Mms::addPartner($partner);
```

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

### Register a New Merchant

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/mms-service.md

Create a new sub-merchant account in the system. The Merchant object should contain registration details, and the response will provide the new sub-merchant's account ID and secret key.

```php
use AratKruglik\WayForPay\Domain\Merchant;
use AratKruglik\WayForPay\Domain\CompensationCard;

$merchant = new Merchant(
    site: 'https://sub-merchant.com',
    phone: '+380501234567',
    email: 'merchant@example.com',
    description: 'Sub-merchant description',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111'
    )
);

$response = Mms::addMerchant($merchant);

// Response contains merchantAccount and secretKey for the new sub-merchant
echo $response['merchantAccount']; // Account ID for sub-merchant
echo $response['secretKey'];       // Secret key for sub-merchant API access
```

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

### Register a New Partner

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/mms-service.md

Use this method to register a new partner (sub-merchant) in your marketplace. Ensure the Partner object includes all necessary registration details and compensation method information.

```php
use AratKruglik\WayForPay\Facades\Mms;
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationCard;

$partner = new Partner(
    partnerCode: 'PARTNER_001',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    description: 'Partner shop description',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111',
        expMonth: '12',
        expYear: '25',
        cvv: '123',
        holderName: 'PARTNER NAME'
    )
);

$response = Mms::addPartner($partner);
```

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

### Add Merchant with MmsService

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/merchant.md

Demonstrates how to register a new sub-merchant using the MmsService. This involves creating a Merchant object with compensation details and passing it to the addMerchant method.

```APIDOC
## Add Merchant

### Description
Registers a new sub-merchant using the MmsService. This process requires a fully configured Merchant object.

### Method
`MmsService::addMerchant(Merchant $merchant)`

### Endpoint
N/A (This is an SDK method call)

### Parameters
* **$merchant** (Merchant) - Required - The Merchant object to register.

### Request Example
```php
use AratKruglik\WayForPay\Facades\Mms;
use AratKruglik\WayForPay\Domain\Merchant;
use AratKruglik\WayForPay\Domain\CompensationCard;

$merchant = new Merchant(
    site: 'https://sub-merchant.com',
    phone: '+380501234567',
    email: 'merchant@example.com',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111'
    )
);

$response = Mms::addMerchant($merchant);
```

### Response
#### Success Response
* **merchantAccount** (string) - Account ID for the new sub-merchant
* **secretKey** (string) - API key for the sub-merchant
```

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

### Cache Configuration Command

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/configuration.md

Clear and cache your application's configuration files using the Artisan command. This is a common troubleshooting step for missing configuration errors.

```bash
php artisan config:cache
```

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

### Create a Recurring Payment Subscription

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/README.md

Initiate a recurring payment subscription by providing regular payment details during the initial purchase. This is used for monthly subscriptions.

```php
use AratKruglik\WayForPay\Transaction;
use AratKruglik\WayForPay\WayForPay;

$transaction = new Transaction(
    orderReference: 'SUB_123',
    amount: 100.00,
    currency: 'UAH',
    orderDate: time(),
    regularMode: 'monthly',
    regularAmount: 100.00,
    dateNext: '25.05.2025',
    dateEnd: '25.05.2026'
);

$html = WayForPay::purchase($transaction);
```

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

### HMAC-MD5 Signature Generation Algorithm

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/signature-generator.md

Demonstrates the HMAC-MD5 algorithm used for generating signatures. Parameters are joined by a semicolon and hashed with a secret key.

```php
hash_hmac('md5', implode(';', $params), $secretKey)
```

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

### addPartner()

Source: https://github.com/aratkruglik/wayforpay-laravel/blob/main/_autodocs/api-reference/mms-service.md

Registers a new partner (sub-merchant) in the marketplace. Requires a Partner object containing registration details and compensation method.

```APIDOC
## addPartner()

### Description
Register a new partner (sub-merchant) in the marketplace.

### Method
POST (Assumed, as it creates a resource)

### Endpoint
`/mms/partners` (Assumed, based on common RESTful practices)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **partner** (`Partner` object) - Required - Partner object with registration details and compensation method

### Request Example
```php
use AratKruglik\WayForPay\Facades\Mms;
use AratKruglik\WayForPay\Domain\Partner;
use AratKruglik\WayForPay\Domain\CompensationCard;

$partner = new Partner(
    partnerCode: 'PARTNER_001',
    site: 'https://partner-shop.com',
    phone: '+380501234567',
    email: 'partner@example.com',
    description: 'Partner shop description',
    compensationCard: new CompensationCard(
        cardNumber: '4111111111111111',
        expMonth: '12',
        expYear: '25',
        cvv: '123',
        holderName: 'PARTNER NAME'
    )
);

$response = Mms::addPartner($partner);
```

### Response
#### Success Response (200)
- **array** - API response with partner registration status and partner code

#### Response Example
(Example not provided in source, but would typically include status and partner code)
```