### Process Payment with Saved Card - Payment Order Binding

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This example shows how to process a payment using a previously saved card binding. It involves two main steps: first, registering an order with the `bindingId` and `clientId`, and second, calling `paymentOrderBinding` with the `mdOrder`, `bindingId`, and customer IP. The code includes steps to check the final order status and complete the order if successful.

```php
<?php

// Step 1: Create order with binding
$orderResponse = $client->register([
    'orderNumber' => 'BINDING_ORDER_' . time(),
    'amount' => 75000,
    'returnUrl' => 'https://myshop.com/payment/success',
    'bindingId' => '07a90a5d-cc60-4d1b-a9e6-ffd15974a74f',
    'description' => 'Payment with saved card',
    'clientId' => 'customer_12345'
]);

// Step 2: Process payment with the binding
$paymentResponse = $client->paymentOrderBinding([
    'mdOrder' => $orderResponse['orderId'],
    'bindingId' => '07a90a5d-cc60-4d1b-a9e6-ffd15974a74f',
    'ip' => $_SERVER['REMOTE_ADDR'],
    'cvc' => '123', // Optional: CVC for additional security
    'email' => 'customer@example.com',
    'language' => 'ru'
]);

if (isset($paymentResponse['errorCode']) && $paymentResponse['errorCode'] === '0') {
    echo "Payment successful with saved card!\n";
    echo "Order ID: {$orderResponse['orderId']}\n";

    // Check final status
    $finalStatus = $client->getOrderStatus([
        'orderId' => $orderResponse['orderId']
    ]);

    if ($finalStatus['OrderStatus'] === 2) {
        completeOrder($orderResponse['orderId']);
        sendConfirmationEmail('customer@example.com');
    }
} else {
    echo "Payment failed: " . ($paymentResponse['errorMessage'] ?? 'Unknown error') . "\n";
}

```

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

### Get Bindings by Card or ID - PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Searches for card bindings using either a partial card number (PAN) or a specific binding ID. It can filter by expired bindings and iterates through the results to display binding details. Dependencies include the Alfabank API client. It takes card PAN or binding ID as input and returns a list of binding objects.

```php
<?php

// Search by partial card number
$byCardResponse = $client->getBindingsByCardOrId([
    'pan' => 411111111111, // First 12 digits
    'showExpired' => false
]);

// Or search by binding ID
$byIdResponse = $client->getBindingsByCardOrId([
    'bindingId' => '07a90a5d-cc60-4d1b-a9e6-ffd15974a74f',
    'showExpired' => true
]);

foreach ($byCardResponse as $binding) {
    echo "Found binding:\n";
    echo "  ID: {$binding['bindingId']}\n";
    echo "  Pan: {$binding['pan']}\n";
    echo "  Expiry: {$binding['expiryDate']}\n";
    echo "  Client ID: {$binding['clientId']}\n";
    echo "  Active: " . ($binding['active'] ? 'Yes' : 'No') . "\n";
}

```

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

### Get Order Status with PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This PHP code retrieves the current status of a payment order using its ID. It maps numerical status codes to human-readable descriptions and provides details about successful or declined payments.

```php
<?php

$alfabankOrderId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

$statusResponse = $client->getOrderStatus([
    'orderId' => $alfabankOrderId,
    'language' => 'ru'
]);

// Order status codes mapping
$statusCodes = [
    0 => 'Registered, not paid',
    1 => 'Pre-authorized (funds on hold)',
    2 => 'Fully authorized (payment completed)',
    3 => 'Authorization cancelled',
    4 => 'Refund processed',
    5 => 'ACS authorization initiated',
    6 => 'Authorization declined'
];

$status = $statusResponse['OrderStatus'] ?? null;
$statusText = $statusCodes[$status] ?? 'Unknown status';

echo "Order Status: {$statusText}\n";
echo "Error Code: {$statusResponse['ErrorCode']}\n";
echo "Error Message: {$statusResponse['ErrorMessage']}\n";

if ($status === 2) {
    echo "Payment successful!\n";
    echo "Amount: " . ($statusResponse['Amount'] / 100) . " RUB\n";
    echo "Pan: {$statusResponse['Pan']}\n";
    processSuccessfulOrder($alfabankOrderId);
} elseif ($status === 6) {
    echo "Payment declined\n";
    notifyCustomerOfFailure($alfabankOrderId);
}

// Expected response:
// {
//     "OrderStatus": 2,
//     "ErrorCode": "0",
//     "ErrorMessage": "Success",
//     "Amount": 150000,
//     "currency": "643",
//     "Pan": "411111**1111",
//     "expiration": "202512",
//     "cardholderName": "IVAN PETROV",
//     "approvalCode": "123456"
// }

```

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

### Get Extended Order Status Details with PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This PHP code retrieves comprehensive details about a payment order, including transaction specifics. The extracted information is logged to a file and displayed in a formatted manner.

```php
<?php

$detailedStatus = $client->getOrderStatusExtended([
    'orderId' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'orderNumber' => 'ORDER_12345',
    'language' => 'en'
]);

// Extract comprehensive order information
$orderInfo = [
    'order_number' => $detailedStatus['OrderNumber'] ?? '',
    'order_status' => $detailedStatus['OrderStatus'] ?? '',
    'pan' => $detailedStatus['Pan'] ?? '',
    'expiration' => $detailedStatus['expiration'] ?? '',
    'cardholder' => $detailedStatus['cardholderName'] ?? '',
    'amount' => ($detailedStatus['Amount'] ?? 0) / 100,
    'deposit_amount' => ($detailedStatus['depositAmount'] ?? 0) / 100,
    'currency' => $detailedStatus['currency'] ?? '',
    'approval_code' => $detailedStatus['approvalCode'] ?? '',
    'auth_code' => $detailedStatus['authCode'] ?? '',
    'client_id' => $detailedStatus['clientId'] ?? '',
    'binding_id' => $detailedStatus['bindingId'] ?? ''
];

// Log transaction details
file_put_contents('transactions.log', json_encode($orderInfo, JSON_PRETTY_PRINT) . "\n", FILE_APPEND);

// Display formatted information
foreach ($orderInfo as $key => $value) {
    echo ucfirst(str_replace('_', ' ', $key)) . ": {$value}\n";
}

```

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

### Get Last Orders for Merchants - PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Retrieves a list of recent orders for merchants within a specified date range and transaction states. It allows filtering by merchant and sorting by creation date. The response includes order details, which can be further processed or exported. Dependencies include the Alfabank API client and a hypothetical `exportOrdersToCSV` function.

```php
<?php

$ordersResponse = $client->getLastOrdersForMerchants([
    'size' => 50,
    'page' => 0,
    'from' => '2025-01-01T00:00:00',
    'to' => '2025-01-31T23:59:59',
    'transactionStates' => 'DEPOSITED,APPROVED,REFUNDED',
    'merchants' => 'merchant_login_name',
    'searchByCreatedDate' => 'true',
    'language' => 'en'
]);

if (isset($ordersResponse['orderStatuses'])) {
    echo "Found " . count($ordersResponse['orderStatuses']) . " orders\n\n";

    foreach ($ordersResponse['orderStatuses'] as $order) {
        echo "Order Number: {$order['orderNumber']}\n";
        echo "Amount: " . ($order['amount'] / 100) . " RUB\n";
        echo "Status: {$order['orderStatus']}\n";
        echo "Date: {$order['date']}\n";
        echo "Pan: {$order['Pan']}\n";
        echo "---\n";
    }

    // Export to CSV for reporting
    exportOrdersToCSV($ordersResponse['orderStatuses'], 'orders_january_2025.csv');
} else {
    echo "No orders found for the specified period\n";
}

```

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

### Update Card Expiration - Extend Binding

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This example demonstrates how to update the expiration date of a saved card binding using the `extendBinding` method. It requires the `bindingId` and the `newExpiry` date in `YYYYMM` format. The code handles success and error scenarios and includes placeholders for updating the expiration date in the local database.

```php
<?php

$bindingId = '07a90a5d-cc60-4d1b-a9e6-ffd15974a74f';
$newExpiryDate = 202612; // YYYYMM format (December 2026)

$extendResponse = $client->extendBinding([
    'bindingId' => $bindingId,
    'newExpiry' => $newExpiryDate,
    'language' => 'en'
]);

if ($extendResponse['errorCode'] === '0') {
    echo "Card expiration date updated successfully\n";
    echo "New expiry: " . substr($newExpiryDate, 0, 4) . "/" . substr($newExpiryDate, 4) . "\n";

    // Update in database
    updateCardExpiry($bindingId, $newExpiryDate);
} else {
    echo "Failed to update expiration: {$extendResponse['errorMessage']}\n";
}

```

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

### Client Initialization

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Initialize the Alfabank acquiring client with either token-based or username/password authentication. Supports production and sandbox environments.

```APIDOC
## Client Initialization

Initialize the Alfabank acquiring client with authentication credentials.

### Method
N/A (Constructor)

### Parameters
#### Constructor Parameters
- **baseUrl** (string) - Required - The base URL for the Alfabank API.
- **token** (string) - Required (if userName/password not provided) - Your API token for authentication.
- **userName** (string) - Required (if token not provided) - Your merchant username.
- **password** (string) - Required (if token not provided) - Your merchant password.
- **timeout** (int) - Optional - The timeout in seconds for API requests. Defaults to 30.
- **connect_timeout** (int) - Optional - The connection timeout in seconds for API requests. Defaults to 10.

### Request Example
```php
<?php

require_once 'vendor/autoload.php';

use kostikpenzin\AlfabankApiAcquiring\Client;

// Token-based authentication (recommended)
$client = new Client([
    'baseUrl' => 'https://alfa.rbsuat.com',
    'token' => 'your-api-token-here'
]);

// Or username/password authentication
$client = new Client([
    'baseUrl' => 'https://web.rbsuat.com',
    'userName' => 'merchant_username',
    'password' => 'merchant_password',
    'timeout' => 30,
    'connect_timeout' => 10
]);

// Production environment configuration
$productionClient = new Client([
    'baseUrl' => 'https://web.rbsuat.com',
    'token' => $_ENV['ALFABANK_TOKEN']
]);
?>
```

### Response
N/A (This is a client initialization, not an API endpoint call.)

```

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

### Initialize Alfabank Acquiring Client (PHP)

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Initializes the Alfabank acquiring client using either token-based or username/password authentication. It requires the `baseUrl` and appropriate authentication credentials. Optional parameters like `timeout` and `connect_timeout` can also be set. The client is built on Guzzle HTTP and adheres to PSR standards.

```php
<?php

require_once 'vendor/autoload.php';

use kostikpenzin\AlfabankApiAcquiring\Client;

// Token-based authentication (recommended)
$client = new Client([
    'baseUrl' => 'https://alfa.rbsuat.com',
    'token' => 'your-api-token-here'
]);

// Or username/password authentication
$client = new Client([
    'baseUrl' => 'https://web.rbsuat.com',
    'userName' => 'merchant_username',
    'password' => 'merchant_password',
    'timeout' => 30,
    'connect_timeout' => 10
]);

// Production environment configuration
$productionClient = new Client([
    'baseUrl' => 'https://web.rbsuat.com',
    'token' => $_ENV['ALFABANK_TOKEN']
]);
```

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

### POST /register

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Register a new payment order and receive a payment form URL for customer redirection. This is the first step in processing a payment.

```APIDOC
## POST /register

Register a new payment order and receive a payment form URL for customer redirection.

### Method
POST

### Endpoint
`/register`

### Parameters
#### Query Parameters
None

#### Request Body
- **orderNumber** (string) - Required - Unique identifier for the order within your system.
- **amount** (integer) - Required - The payment amount in the smallest currency unit (e.g., kopecks for RUB).
- **currency** (integer) - Required - ISO 4217 currency code (e.g., 643 for RUB).
- **returnUrl** (string) - Required - URL to redirect the customer to upon successful payment.
- **failUrl** (string) - Required - URL to redirect the customer to upon failed payment.
- **description** (string) - Optional - A description of the order.
- **language** (string) - Optional - Language for the payment page (e.g., 'ru', 'en'). Defaults to 'ru'.
- **pageView** (string) - Optional - Preferred view for the payment page ('DESKTOP', 'MOBILE').
- **clientId** (string) - Optional - Identifier for the customer.
- **email** (string) - Optional - Customer's email address.
- **jsonParams** (object) - Optional - Additional parameters in JSON format (e.g., for custom fields).
    - **email** (string) - Customer's email.
    - **phone** (string) - Customer's phone number.
    - **customer_name** (string) - Customer's full name.
- **sessionTimeoutSecs** (integer) - Optional - Timeout for the payment session in seconds.
- **expirationDate** (string) - Optional - Expiration date for the order in ISO 8601 format (YYYY-MM-DDTHH:MM:SS).

### Request Example
```php
<?php

$orderId = 'ORDER_' . time() . '_' . uniqid();

try {
    $response = $client->register([
        'orderNumber' => $orderId,
        'amount' => 150000, // Amount in kopecks (1500.00 RUB)
        'currency' => 643, // RUB currency code (ISO 4217)
        'returnUrl' => 'https://myshop.com/payment/success',
        'failUrl' => 'https://myshop.com/payment/failed',
        'description' => 'Order #' . $orderId . ' - Electronics Purchase',
        'language' => 'ru',
        'pageView' => 'DESKTOP',
        'clientId' => 'customer_12345',
        'email' => 'customer@example.com',
        'jsonParams' => [
            'email' => 'customer@example.com',
            'phone' => '+79001234567',
            'customer_name' => 'Ivan Petrov'
        ],
        'sessionTimeoutSecs' => 1200,
        'expirationDate' => '2025-12-31T23:59:59'
    ]);

    if (isset($response['formUrl']) && isset($response['orderId'])) {
        // Store orderId in database for future reference
        saveOrderToDatabase($orderId, $response['orderId']);

        // Redirect customer to payment page
        header('Location: ' . $response['formUrl']);
        exit;
    } else {
        throw new Exception('Payment order creation failed: ' . 
            ($response['errorMessage'] ?? 'Unknown error'));
    }

} catch (Exception $e) {
    error_log('Alfabank register error: ' . $e->getMessage());
    echo 'Payment initialization failed. Please try again.';
}
?>
```

### Response
#### Success Response (200)
- **orderId** (string) - The unique identifier for the order created by Alfabank.
- **formUrl** (string) - The URL of the payment form that the customer needs to be redirected to.

#### Error Response
- **errorCode** (string) - Error code.
- **errorMessage** (string) - Description of the error.

#### Response Example (Success)
{
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "formUrl": "https://alfa.rbsuat.com/payment/merchants/test/payment_ru.html?mdOrder=..."
}

```

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

### Process Refund - Full or Partial

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This snippet demonstrates how to process a full or partial refund for a completed payment using the Alfabank API. It requires the order ID and the amount in kopecks for the refund. The code handles success and error logging, and includes placeholders for updating the database and notifying the customer.

```php
<?php

// Full refund example
$fullRefundResponse = $client->refund([
    'orderId' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'amount' => 150000 // Full amount in kopecks
]);

if ($fullRefundResponse['errorCode'] === '0') {
    echo "Full refund processed successfully\n";
}

// Partial refund example
$partialRefundResponse = $client->refund([
    'orderId' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'amount' => 50000 // Partial refund: 500.00 RUB
]);

if ($partialRefundResponse['errorCode'] === '0') {
    echo "Partial refund of 500.00 RUB processed\n";

    // Update order in database
    $refundData = [
        'order_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        'refund_amount' => 50000,
        'refund_date' => date('Y-m-d H:i:s'),
        'status' => 'partially_refunded'
    ];
    saveRefundToDatabase($refundData);

    // Notify customer
    sendRefundNotification('customer@example.com', 500.00);
} else {
    error_log('Refund failed: ' . $partialRefundResponse['errorMessage']);
}

```

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

### POST /registerPreAuth

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Create a pre-authorization order, which holds funds on the customer's card without charging them immediately. Useful for bookings or reservations.

```APIDOC
## POST /registerPreAuth

Create a pre-authorization order that holds funds without immediate charge.

### Method
POST

### Endpoint
`/registerPreAuth`

### Parameters
#### Query Parameters
None

#### Request Body
- **orderNumber** (string) - Required - Unique identifier for the order within your system.
- **amount** (integer) - Required - The amount to hold in the smallest currency unit (e.g., kopecks for RUB).
- **returnUrl** (string) - Required - URL to redirect the customer to upon successful pre-authorization.
- **failUrl** (string) - Required - URL to redirect the customer to upon failed pre-authorization.
- **description** (string) - Optional - A description of the order.
- **language** (string) - Optional - Language for the payment page (e.g., 'ru', 'en'). Defaults to 'ru'.
- **clientId** (string) - Optional - Identifier for the customer.
- **jsonParams** (object) - Optional - Additional parameters in JSON format.
    - **booking_id** (string) - Example: Identifier for a hotel booking.
    - **check_in** (string) - Example: Check-in date.
    - **check_out** (string) - Example: Check-out date.

### Request Example
```php
<?php

$preAuthOrderId = 'PREAUTH_' . time();

$response = $client->registerPreAuth([
    'orderNumber' => $preAuthOrderId,
    'amount' => 500000, // Hold 5000.00 RUB
    'returnUrl' => 'https://myshop.com/payment/success',
    'failUrl' => 'https://myshop.com/payment/failed',
    'description' => 'Hotel booking pre-authorization',
    'language' => 'en',
    'clientId' => 'customer_67890',
    'jsonParams' => [
        'booking_id' => 'HOTEL_12345',
        'check_in' => '2025-01-15',
        'check_out' => '2025-01-20'
    ]
]);

if (isset($response['orderId'])) {
    $_SESSION['preauth_order_id'] = $response['orderId'];
    header('Location: ' . $response['formUrl']);
    exit;
}
?>
```

### Response
#### Success Response (200)
- **orderId** (string) - The unique identifier for the pre-authorization order created by Alfabank.
- **formUrl** (string) - The URL of the payment form that the customer needs to be redirected to.

#### Error Response
- **errorCode** (string) - Error code.
- **errorMessage** (string) - Description of the error.

#### Response Example (Success)
{
    "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "formUrl": "https://alfa.rbsuat.com/payment/merchants/test/payment_ru.html?mdOrder=..."
}

```

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

### Register Pre-Authorization Order (PHP)

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Creates a pre-authorization payment order, which holds funds without immediately charging the customer. This is useful for services like hotel bookings or rentals. The function requires `orderNumber`, `amount`, `returnUrl`, and `failUrl`. It returns a `formUrl` for the customer to complete the pre-authorization step.

```php
<?php

$preAuthOrderId = 'PREAUTH_' . time();

$response = $client->registerPreAuth([
    'orderNumber' => $preAuthOrderId,
    'amount' => 500000, // Hold 5000.00 RUB
    'returnUrl' => 'https://myshop.com/payment/success',
    'failUrl' => 'https://myshop.com/payment/failed',
    'description' => 'Hotel booking pre-authorization',
    'language' => 'en',
    'clientId' => 'customer_67890',
    'jsonParams' => [
        'booking_id' => 'HOTEL_12345',
        'check_in' => '2025-01-15',
        'check_out' => '2025-01-20'
    ]
]);

if (isset($response['orderId'])) {
    $_SESSION['preauth_order_id'] = $response['orderId'];
    header('Location: ' . $response['formUrl']);
    exit;
}

// Expected response:
// {
//     "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
//     "formUrl": "https://alfa.rbsuat.com/payment/merchants/test/payment_ru.html?mdOrder=..."
// }
```

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

### Register Payment Order (PHP)

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Registers a new payment order with Alfabank's acquiring service. This function requires order details such as `orderNumber`, `amount`, `currency`, `returnUrl`, and `failUrl`. It returns a `formUrl` for customer redirection upon successful registration or an `errorMessage` on failure. Error handling is included for exceptions during the process.

```php
<?php

$orderId = 'ORDER_' . time() . '_' . uniqid();

try {
    $response = $client->register([
        'orderNumber' => $orderId,
        'amount' => 150000, // Amount in kopecks (1500.00 RUB)
        'currency' => 643, // RUB currency code (ISO 4217)
        'returnUrl' => 'https://myshop.com/payment/success',
        'failUrl' => 'https://myshop.com/payment/failed',
        'description' => 'Order #' . $orderId . ' - Electronics Purchase',
        'language' => 'ru',
        'pageView' => 'DESKTOP',
        'clientId' => 'customer_12345',
        'email' => 'customer@example.com',
        'jsonParams' => [
            'email' => 'customer@example.com',
            'phone' => '+79001234567',
            'customer_name' => 'Ivan Petrov'
        ],
        'sessionTimeoutSecs' => 1200,
        'expirationDate' => '2025-12-31T23:59:59'
    ]);

    if (isset($response['formUrl']) && isset($response['orderId'])) {
        // Store orderId in database for future reference
        saveOrderToDatabase($orderId, $response['orderId']);

        // Redirect customer to payment page
        header('Location: ' . $response['formUrl']);
        exit;
    } else {
        throw new Exception('Payment order creation failed: ' .
            ($response['errorMessage'] ?? 'Unknown error'));
    }

} catch (Exception $e) {
    error_log('Alfabank register error: ' . $e->getMessage());
    echo 'Payment initialization failed. Please try again.';
}
```

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

### Complete Pre-Authorization Payment with PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This PHP code completes a pre-authorized payment by charging the held amount. It requires the pre-authorization order ID and the amount to charge. The function returns a success or error message based on the API response.

```php
<?php

// After customer completes pre-authorization, deposit the funds
$preAuthOrderId = $_SESSION['preauth_order_id'];

try {
    $depositResponse = $client->deposit([
        'orderId' => $preAuthOrderId,
        'amount' => 300000 // Charge only 3000.00 RUB (less than pre-auth amount)
    ]);

    if ($depositResponse['errorCode'] === '0') {
        echo 'Payment successfully charged: ' . ($depositResponse['amount'] / 100) . ' RUB';
        updateOrderStatus($preAuthOrderId, 'completed');
    } else {
        echo 'Deposit failed: ' . $depositResponse['errorMessage'];
    }

} catch (Exception $e) {
    error_log('Deposit error: ' . $e->getMessage());
}

// Expected success response:
// {
//     "errorCode": "0",
//     "errorMessage": "Success"
// }

```

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

### Verify 3D-Secure Enrollment - PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Checks if a given card number is enrolled in 3D-Secure authentication. It takes the card number (PAN) as input and returns an enrollment status ('Y' for enrolled, 'N' for not enrolled, 'U' for unable to verify). This is crucial for determining the payment flow. Dependencies include the Alfabank API client.

```php
<?php

$cardNumber = 4111111111111111;

$enrollmentResponse = $client->verifyEnrollment([
    'pan' => $cardNumber
]);

$enrolled = $enrollmentResponse['enrolled'] ?? 'U';

$enrollmentStatus = [
    'Y' => 'Card supports 3D-Secure',
    'N' => 'Card does not support 3D-Secure',
    'U' => 'Unable to verify enrollment'
];

echo $enrollmentStatus[$enrolled] ?? 'Unknown enrollment status';

if ($enrolled === 'Y') {
    echo "\n3D-Secure authentication will be required for this card\n";
    // Proceed with secure payment flow
} else {
    echo "\nStandard payment flow will be used\n";
}

// Expected response:
// {
//     "enrolled": "Y",
//     "acsUrl": "https://acs.bank.com/3ds",
//     "paReq": "eJx..."
// }

```

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

### Retrieve Saved Cards - List Bindings

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This PHP code retrieves all saved card bindings for a given customer ID. It makes a call to the `getBindings` method of the client and iterates through the response to display card details such as binding ID, masked PAN, expiry date, and status. It handles cases where no saved cards are found.

```php
<?php

$customerId = 'customer_12345';

$bindingsResponse = $client->getBindings([
    'clientId' => $customerId
]);

if (is_array($bindingsResponse) && count($bindingsResponse) > 0) {
    echo "Saved cards for customer {$customerId}:\n\n";

    foreach ($bindingsResponse as $index => $binding) {
        echo "Card " . ($index + 1) . ":\n";
        echo "  Binding ID: {$binding['bindingId']}\n";
        echo "  Card Number: {$binding['pan']}\n";
        echo "  Expiry Date: {$binding['expiryDate']}\n";
        echo "  Status: " . ($binding['active'] ? 'Active' : 'Inactive') . "\n";
        echo "\n";
    }
} else {
    echo "No saved cards found for this customer\n";
}

// Expected response:
// [
//     {
//         "bindingId": "07a90a5d-cc60-4d1b-a9e6-ffd15974a74f",
//         "pan": "411111**1111",
//         "expiryDate": "202512",
//         "cardholderName": "IVAN PETROV",
//         "active": true
//     }
// ]

```

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

### Callback Handler for Payment Notifications - PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Processes incoming webhook notifications from Alfabank regarding payment status changes. It validates the incoming request, fetches the order status, updates the order in the local database based on the status (e.g., paid, failed, refunded), and triggers appropriate subsequent actions like sending confirmations or initiating fulfillment. Dependencies include the Alfabank API client, database interaction functions (`updateOrderInDatabase`), and notification functions (`sendPaymentConfirmation`, `notifyCustomerOfFailure`, `sendRefundConfirmation`).

```php
<?php

// callback.php - Webhook endpoint
$orderId = $_POST['orderId'] ?? null;
$orderNumber = $_POST['orderNumber'] ?? null;

if (!$orderId) {
    http_response_code(400);
    exit('Missing orderId');
}

try {
    // Verify order status
    $status = $client->getOrderStatus(['orderId' => $orderId]);

    switch ($status['OrderStatus']) {
        case 2: // Payment successful
            updateOrderInDatabase($orderId, 'paid', [
                'pan' => $status['Pan'],
                'amount' => $status['Amount'],
                'approval_code' => $status['approvalCode']
            ]);

            sendPaymentConfirmation($status['clientId']);
            processOrderFulfillment($orderNumber);
            break;

        case 6: // Payment declined
            updateOrderInDatabase($orderId, 'failed');
            notifyCustomerOfFailure($status['clientId']);
            break;

        case 4: // Refunded
            updateOrderInDatabase($orderId, 'refunded');
            sendRefundConfirmation($status['clientId']);
            break;

        default:
            error_log("Unhandled order status: {$status['OrderStatus']}");
    }

    // Respond to Alfabank
    http_response_code(200);
    echo 'OK';

} catch (Exception $e) {
    error_log('Callback processing error: ' . $e->getMessage());
    http_response_code(500);
    echo 'Error processing callback';
}

```

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

### Add Custom Parameters to Order - PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

Adds custom parameters to an existing order identified by its ID. It accepts the order ID and a map of key-value pairs for the parameters, along with a language code. The function returns an error code and message to indicate success or failure. Dependencies include the Alfabank API client.

```php
<?php

$orderId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

$addParamsResponse = $client->addParams([
    'orderId' => $orderId,
    'params' => [
        'delivery_type' => 'express',
        'warehouse_id' => 'WH_001',
        'promo_code' => 'SUMMER2025',
        'customer_note' => 'Please call before delivery',
        'gift_wrap' => 'true'
    ],
    'language' => 'ru'
]);

if ($addParamsResponse['errorCode'] === '0') {
    echo "Custom parameters added successfully\n";
} else {
    echo "Failed to add parameters: {$addParamsResponse['errorMessage']}\n";
}

```

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

### Reverse Authorization with PHP

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This PHP code cancels an authorized payment before it settles. It requires the order ID to be cancelled and returns a success or failure message based on the API response.

```php
<?php

$orderIdToCancel = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

try {
    $reverseResponse = $client->reverse([
        'orderId' => $orderIdToCancel,
        'language' => 'ru'
    ]);

    if ($reverseResponse['errorCode'] === '0') {
        echo "Authorization successfully cancelled\n";
        updateOrderStatus($orderIdToCancel, 'cancelled');
        notifyCustomer($orderIdToCancel, 'Your payment has been cancelled');
    } else {
        echo "Cancellation failed: {$reverseResponse['errorMessage']}\n";
        echo "Error code: {$reverseResponse['errorCode']}\n";
    }

} catch (Exception $e) {
    error_log('Reverse operation failed: ' . $e->getMessage());
    echo 'Unable to cancel authorization';
}

// Expected success response:
// {
//     "errorCode": "0",
//     "errorMessage": "Success"
// }

```

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

### Remove Saved Card - Unbind Card

Source: https://context7.com/kostikpenzin/alfabank-api-acquiring/llms.txt

This PHP snippet shows how to remove a card binding from the system by calling the `unBindCard` method. It requires the `bindingId` of the card to be removed. The code includes checks for successful unbinding and placeholders for updating the local database and notifying the customer.

```php
<?php

$bindingIdToRemove = '07a90a5d-cc60-4d1b-a9e6-ffd15974a74f';

$unbindResponse = $client->unBindCard([
    'bindingId' => $bindingIdToRemove
]);

if ($unbindResponse['errorCode'] === '0') {
    echo "Card successfully removed\n";

    // Update database
    deleteCardBindingFromDatabase($bindingIdToRemove);

    // Notify customer
    echo "Your saved card has been removed from the system\n";
} else {
    echo "Failed to remove card: {$unbindResponse['errorMessage']}\n";
}

// Expected success response:
// {
//     "errorCode": "0",
//     "errorMessage": "Success"
// }

```

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