### Install WebToPay via Composer

Source: https://github.com/paysera/lib-webtopay/blob/master/README.md

Install the WebToPay library using Composer. Different versions are available, including the latest, oldest supported, and versions with a new interface.

```bash
// to install the latest version
"composer require webtopay/libwebtopay
```

```bash
// to install the oldest supported version (in some projects)
"composer require webtopay/libwebtopay "^1.6"
```

```bash
// to install version with new interface
"composer require webtopay/libwebtopay "^2.0"
```

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

### Include WebToPay.php

Source: https://github.com/paysera/lib-webtopay/blob/master/README.md

Include the main WebToPay.php file for a simple setup. This is the easiest way to use the library.

```php
<?php

require_once('WebToPay.php');
```

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

### Use WebToPay Namespace

Source: https://github.com/paysera/lib-webtopay/blob/master/README.md

After installing via Composer, use the WebToPay namespace in your PHP code. This is required for using the library's classes.

```php
<?php

use WebToPay;
```

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

### Getting Available Payment Methods

Source: https://context7.com/paysera/lib-webtopay/llms.txt

This section explains how to use the `WebToPay::getPaymentMethodList()` method to fetch a list of available payment methods from Paysera. This list can be filtered by currency and amount, and it provides a hierarchical structure of countries, groups, and individual payment options.

```APIDOC
## Getting Available Payment Methods

The `WebToPay::getPaymentMethodList()` method retrieves available payment methods for your project, filtered by currency and optionally by amount. Returns a hierarchical structure of countries, groups, and individual payment methods.

### Method
`WebToPay::getPaymentMethodList(projectId, amount = null, currency = null)`

### Parameters
- **projectId** (int) - Required - Your Paysera project ID.
- **amount** (int) - Optional - The amount in cents to filter payment methods by minimum and maximum limits.
- **currency** (string) - Optional - The ISO currency code (e.g., 'EUR') to filter payment methods.

### Request Example
```php
<?php
require_once('WebToPay.php');

try {
    // Get all payment methods for EUR currency
    $paymentMethods = WebToPay::getPaymentMethodList(
        12345,      // Project ID
        1000,       // Amount in cents (optional, filters by min/max)
        'EUR'       // Currency
    );

    // Set display language
    $paymentMethods->setDefaultLanguage('en');

    // Iterate through countries, groups, and methods
    foreach ($paymentMethods->getCountries() as $country) {
        echo '<h2>' . $country->getTitle('en') . ' (' . $country->getCode() . ')</h2>';
        foreach ($country->getGroups() as $group) {
            echo '<h3>' . $group->getTitle('en') . '</h3>';
            echo '<ul>';
            foreach ($group->getPaymentMethods() as $method) {
                $logoUrl = $method->getLogoUrl('en');
                $title = $method->getTitle('en');
                $key = $method->getKey();
                $minAmount = $method->getMinAmountAsString();
                $maxAmount = $method->getMaxAmountAsString();

                echo '<li>';
                if ($logoUrl) {
                    echo '<img src="' . $logoUrl . '" alt="' . $title . '">';
                }
                echo '<label>';
                echo '<input type="radio" name="payment" value="' . $key . '">';
                echo $title;
                if ($minAmount) echo ' (Min: ' . $minAmount . ')';
                if ($maxAmount) echo ' (Max: ' . $maxAmount . ')';
                echo '</label>';
                echo '</li>';
            }
            echo '</ul>';
        }
    }

    // Filter methods for a specific amount
    $filteredMethods = $paymentMethods->filterForAmount(5000, 'EUR');

    // Get specific country's methods
    $ltMethods = $paymentMethods->getCountry('LT');
    if ($ltMethods) {
        foreach ($ltMethods->getPaymentMethods() as $method) {
            echo $method->getTitle() . "\n";
        }
    }

} catch (WebToPayException $e) {
    echo 'Error loading payment methods: ' . $e->getMessage();
}
?>
```

### Response
#### Success Response
Returns a hierarchical object representing payment methods, organized by country, group, and individual payment method. Each method object contains details like title, key, logo URL, minimum and maximum amounts.

#### Response Example (Conceptual Structure)
```json
{
  "countries": [
    {
      "code": "LT",
      "title": {"en": "Lithuania"},
      "groups": [
        {
          "title": {"en": "Banks"},
          "paymentMethods": [
            {
              "key": "swedbank",
              "title": {"en": "Swedbank"},
              "logoUrl": {"en": "/path/to/swedbank.png"},
              "minAmount": "1.00",
              "maxAmount": "10000.00"
            }
            // ... other payment methods
          ]
        }
        // ... other groups
      ]
    }
    // ... other countries
  ]
}
```

#### Error Responses
- **WebToPayException**: Thrown if there is an error retrieving the payment methods (e.g., network issues, invalid project ID).
```

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

### Initialize and use WebToPay_Factory

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Demonstrates creating a factory instance, enabling sandbox mode, building payment requests, validating callbacks, and retrieving payment methods.

```php
<?php
require_once('libwebtopay/src/includes.php');

// Create factory with configuration
$factory = new WebToPay_Factory([
    WebToPay_Config::PARAM_PROJECT_ID => 12345,
    WebToPay_Config::PARAM_PASSWORD => 'your_project_password',
]);

// Enable sandbox for testing
$factory->useSandbox(true);

// Build payment request using factory
$requestBuilder = $factory->getRequestBuilder();
$request = $requestBuilder->buildRequest([
    'orderid'     => 'TEST-' . time(),
    'amount'      => 100,
    'currency'    => 'EUR',
    'accepturl'   => 'https://yoursite.com/success',
    'cancelurl'   => 'https://yoursite.com/cancel',
    'callbackurl' => 'https://yoursite.com/callback',
    'test'        => 1,
]);

// Get full redirect URL
$paymentUrl = $requestBuilder->buildRequestUrlFromData([
    'orderid'     => 'TEST-' . time(),
    'amount'      => 500,
    'currency'    => 'EUR',
    'accepturl'   => 'https://yoursite.com/success',
    'cancelurl'   => 'https://yoursite.com/cancel',
    'callbackurl' => 'https://yoursite.com/callback',
]);

echo "Payment URL: " . $paymentUrl;
// https://sandbox.paysera.com/pay/?data=...&sign=...

// Validate callback using factory
$validator = $factory->getCallbackValidator();
try {
    $response = $validator->validateAndParseData($_GET);

    // Verify expected fields match
    $validator->checkExpectedFields($response, [
        'orderid' => 'TEST-123',
        'amount'  => '500',
        'currency'=> 'EUR',
    ]);

    echo 'OK';
} catch (WebToPay_Exception_Callback $e) {
    http_response_code(400);
    echo 'Callback error: ' . $e->getMessage();
}

// Get payment methods via factory
$methodProvider = $factory->getPaymentMethodListProvider();
$methods = $methodProvider->getPaymentMethodList(1000, 'EUR');
```

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

### Build repeat payment requests

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Shows how to create a signed request for repeating a previous payment using static methods or the factory builder.

```php
<?php
require_once('WebToPay.php');

// Repeat a previous payment
try {
    $repeatRequest = WebToPay::buildRepeatRequest([
        'projectid'     => 12345,
        'sign_password' => 'your_project_password',
        'orderid'       => 'ORIGINAL-ORDER-123',
    ]);

    // Build form for repeat payment
    $payUrl = WebToPay::getPaymentUrl('ENG');

    echo '<form method="POST" action="' . $payUrl . '">';
    echo '<input type="hidden" name="data" value="' . $repeatRequest['data'] . '">';
    echo '<input type="hidden" name="sign" value="' . $repeatRequest['sign'] . '">';
    echo '<button type="submit">Repeat Payment</button>';
    echo '</form>';

} catch (WebToPayException $e) {
    echo 'Error: ' . $e->getMessage();
}

// Using factory to build repeat request URL directly
$factory = new WebToPay_Factory([
    WebToPay_Config::PARAM_PROJECT_ID => 12345,
    WebToPay_Config::PARAM_PASSWORD => 'your_project_password',
]);

$requestBuilder = $factory->getRequestBuilder();
$repeatUrl = $requestBuilder->buildRepeatRequestUrlFromOrderId(123);

header('Location: ' . $repeatUrl);
```

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

### Catching WebToPay Exceptions

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Demonstrates how to handle various exception types including validation, callback, and configuration errors when building a payment request.

```php
<?php
require_once('WebToPay.php');

try {
    $request = WebToPay::buildRequest([
        'projectid'     => 12345,
        'sign_password' => 'secret',
        'orderid'       => str_repeat('x', 50), // Too long - max 40 chars
        'amount'        => 'invalid',           // Should be numeric
        'currency'      => 'EURO',              // Should be 3 chars
        'accepturl'     => '',                  // Required field missing
        'cancelurl'     => 'https://example.com/cancel',
        'callbackurl'   => 'https://example.com/callback',
    ]);

} catch (WebToPay_Exception_Validation $e) {
    // Validation-specific error
    echo 'Validation error: ' . $e->getMessage() . "\n";
    echo 'Field: ' . $e->getField() . "\n";
    echo 'Code: ' . $e->getCode() . "\n";

    // Error codes:
    // WebToPayException::E_MISSING = 1  (Required field missing)
    // WebToPayException::E_INVALID = 2  (Invalid value)
    // WebToPayException::E_MAXLEN = 3   (Value too long)
    // WebToPayException::E_REGEXP = 4   (Pattern mismatch)

} catch (WebToPay_Exception_Callback $e) {
    // Callback validation error
    echo 'Callback error: ' . $e->getMessage();

} catch (WebToPay_Exception_Configuration $e) {
    // Configuration error (missing project ID, password, etc.)
    echo 'Configuration error: ' . $e->getMessage();

} catch (WebToPayException $e) {
    // General error
    echo 'Payment error: ' . $e->getMessage();

    // Additional error codes:
    // WebToPayException::E_USER_PARAMS = 5
    // WebToPayException::E_LOG = 6
    // WebToPayException::E_SMS_ANSWER = 7
    // WebToPayException::E_STATUS = 8
    // WebToPayException::E_LIBRARY = 9
    // WebToPayException::E_SERVICE = 10
    // WebToPayException::E_DEPRECATED_USAGE = 11
}
```

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

### Constructing a Signed Payment Request

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Uses WebToPay::buildRequest to generate the necessary data and signature for a payment form submission.

```php
<?php
require_once('WebToPay.php');

try {
    $requestData = WebToPay::buildRequest([
        'projectid'     => 12345,
        'sign_password' => 'your_project_password',
        'orderid'       => 'ORDER-' . time(),
        'amount'        => 1000,            // Amount in cents (10.00 EUR)
        'currency'      => 'EUR',
        'accepturl'     => 'https://yoursite.com/payment/success',
        'cancelurl'     => 'https://yoursite.com/payment/cancel',
        'callbackurl'   => 'https://yoursite.com/payment/callback',
        'test'          => 1,               // Enable test mode
        'lang'          => 'ENG',
        'payment'       => 'hanza',         // Optional: specific payment method
        'country'       => 'LT',            // Optional: buyer country
        'paytext'       => 'Payment for order [order_nr]',
        'p_firstname'   => 'John',
        'p_lastname'    => 'Doe',
        'p_email'       => 'john@example.com',
    ]);

    // Result contains 'data' and 'sign' parameters for form submission
    print_r($requestData);
    // Array (
    //     [data] => encoded_base64_payment_data...
    //     [sign] => md5_signature_hash
    // )

    // Create payment form
    echo '<form method="POST" action="https://bank.paysera.com/pay/">';
    echo '<input type="hidden" name="data" value="' . $requestData['data'] . '">';
    echo '<input type="hidden" name="sign" value="' . $requestData['sign'] . '">';
    echo '<button type="submit">Pay Now</button>';
    echo '</form>';

} catch (WebToPayException $e) {
    echo 'Payment error: ' . $e->getMessage();
    echo 'Field: ' . $e->getField(); // If validation error on specific field
}
```

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

### Include src/includes.php

Source: https://github.com/paysera/lib-webtopay/blob/master/README.md

Include the includes.php file from the src directory if you are using individual files. Ensure your autoloader is set up or use this include.

```php
<?php

require_once('libwebtopay/src/includes.php');
// Your code goes here
```

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

### Retrieve Available Payment Methods with PHP

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Fetches a hierarchical list of payment methods filtered by currency and amount. Use the returned object to iterate through countries, groups, and methods to build a payment selection UI.

```php
<?php
require_once('WebToPay.php');

try {
    // Get all payment methods for EUR currency
    $paymentMethods = WebToPay::getPaymentMethodList(
        12345,      // Project ID
        1000,       // Amount in cents (optional, filters by min/max)
        'EUR'       // Currency
    );

    // Set display language
    $paymentMethods->setDefaultLanguage('en');

    // Iterate through countries
    foreach ($paymentMethods->getCountries() as $country) {
        echo '<h2>' . $country->getTitle('en') . ' (' . $country->getCode() . ')</h2>';

        // Iterate through payment groups (e.g., "Banks", "Cards")
        foreach ($country->getGroups() as $group) {
            echo '<h3>' . $group->getTitle('en') . '</h3>';
            echo '<ul>';

            // Iterate through payment methods
            foreach ($group->getPaymentMethods() as $method) {
                $logoUrl = $method->getLogoUrl('en');
                $title = $method->getTitle('en');
                $key = $method->getKey();
                $minAmount = $method->getMinAmountAsString();
                $maxAmount = $method->getMaxAmountAsString();

                echo '<li>';
                if ($logoUrl) {
                    echo '<img src="' . $logoUrl . '" alt="' . $title . '">';
                }
                echo '<label>';
                echo '<input type="radio" name="payment" value="' . $key . '">';
                echo $title;
                if ($minAmount) echo ' (Min: ' . $minAmount . ')';
                if ($maxAmount) echo ' (Max: ' . $maxAmount . ')';
                echo '</label>';
                echo '</li>';
            }
            echo '</ul>';
        }
    }

    // Filter methods for specific amount
    $filteredMethods = $paymentMethods->filterForAmount(5000, 'EUR');

    // Get specific country's methods
    $ltMethods = $paymentMethods->getCountry('LT');
    if ($ltMethods) {
        foreach ($ltMethods->getPaymentMethods() as $method) {
            echo $method->getTitle() . "\n";
        }
    }

} catch (WebToPayException $e) {
    echo 'Error loading payment methods: ' . $e->getMessage();
}
```

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

### Validate Payment Callbacks with PHP

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Parses and verifies incoming callback data from Paysera using project credentials. Ensure the script returns 'OK' to acknowledge receipt and handles exceptions for invalid signatures.

```php
<?php
require_once('WebToPay.php');

// callback.php - Handle payment notification from Paysera
try {
    $response = WebToPay::validateAndParseData(
        $_GET,                  // Callback parameters (data, ss1/ss2/ss3)
        12345,                  // Your project ID
        'your_project_password' // Your project password
    );

    // Callback validated successfully
    $orderId = $response['orderid'];
    $status = $response['status'];
    $amount = $response['amount'];
    $currency = $response['currency'];
    $paymentType = $response['type'];  // 'macro' or 'micro'

    // Check payment status
    // Status: 0 = payment not executed
    //         1 = payment successful
    //         2 = payment accepted but pending
    //         3 = additional payment info
    if ($status == 1) {
        // Payment successful - update order status
        updateOrderStatus($orderId, 'paid');

        // Verify amount matches expected
        $expectedAmount = getOrderAmount($orderId);
        if ($amount != $expectedAmount || $currency != 'EUR') {
            error_log("Amount mismatch for order $orderId");
        }
    } elseif ($status == 0) {
        // Payment cancelled
        updateOrderStatus($orderId, 'cancelled');
    }

    // Return OK to acknowledge callback
    echo 'OK';

} catch (WebToPay_Exception_Callback $e) {
    // Invalid signature or callback data
    error_log('Callback validation failed: ' . $e->getMessage());
    http_response_code(400);
    echo 'Invalid callback';
} catch (WebToPayException $e) {
    error_log('Payment error: ' . $e->getMessage());
    http_response_code(500);
}
```

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

### Redirecting Users to the Payment Gateway

Source: https://context7.com/paysera/lib-webtopay/llms.txt

Uses WebToPay::redirectToPayment to automatically build the request and redirect the user to the Paysera payment window.

```php
<?php
require_once('WebToPay.php');

// Process order and redirect to payment
$orderId = $_POST['order_id'];
$amount = $_POST['amount'];

try {
    WebToPay::redirectToPayment([
        'projectid'     => 12345,
        'sign_password' => 'your_project_password',
        'orderid'       => $orderId,
        'amount'        => $amount * 100,   // Convert to cents
        'currency'      => 'EUR',
        'accepturl'     => 'https://yoursite.com/success?order=' . $orderId,
        'cancelurl'     => 'https://yoursite.com/cancel?order=' . $orderId,
        'callbackurl'   => 'https://yoursite.com/callback',
        'test'          => 0,               // Production mode
        'lang'          => 'LIT',
        'p_email'       => $_POST['email'],
    ], true);  // true = exit after redirect

} catch (WebToPayException $e) {
    // Handle validation errors
    error_log('Payment redirect failed: ' . $e->getMessage());
    header('Location: /checkout?error=payment_failed');
}
```

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

### Validating Payment Callbacks

Source: https://context7.com/paysera/lib-webtopay/llms.txt

This section details how to use the `WebToPay::validateAndParseData()` method to securely validate callback data received from Paysera after a payment. It ensures the cryptographic signature is correct and provides parsed payment details.

```APIDOC
## Validating Payment Callbacks

The `WebToPay::validateAndParseData()` method parses and validates callback data received from Paysera after payment completion. It verifies the cryptographic signature (SS1/SS2/SS3 or GCM-encrypted) and returns parsed payment details.

### Method
`WebToPay::validateAndParseData()`

### Parameters
- **callbackData** (array) - Required - The callback parameters received from Paysera (e.g., `$_GET` or `$_POST` data).
- **projectId** (int) - Required - Your Paysera project ID.
- **projectPassword** (string) - Required - Your Paysera project password.

### Request Example
```php
<?php
require_once('WebToPay.php');

try {
    $response = WebToPay::validateAndParseData(
        $_GET,                  // Callback parameters (data, ss1/ss2/ss3)
        12345,                  // Your project ID
        'your_project_password' // Your project password
    );

    // Process validated data
    $orderId = $response['orderid'];
    $status = $response['status'];
    // ... other fields like amount, currency, type

    if ($status == 1) {
        // Payment successful
        updateOrderStatus($orderId, 'paid');
        // Verify amount and currency
    } elseif ($status == 0) {
        // Payment cancelled
        updateOrderStatus($orderId, 'cancelled');
    }

    echo 'OK'; // Acknowledge callback

} catch (WebToPay_Exception_Callback $e) {
    // Invalid signature or callback data
    error_log('Callback validation failed: ' . $e->getMessage());
    http_response_code(400);
    echo 'Invalid callback';
} catch (WebToPayException $e) {
    // General payment error
    error_log('Payment error: ' . $e->getMessage());
    http_response_code(500);
}
?>
```

### Response
#### Success Response (200 OK)
Returns 'OK' if the callback is successfully validated and processed.

#### Error Responses
- **400 Bad Request**: Returned if the callback signature is invalid or data is malformed.
- **500 Internal Server Error**: Returned for other general payment processing errors.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.