@alliance-bank/payment-sdk

AlliancePay NodeJS SDK

Це офіційне NodeJS SDK для інтеграції з платіжними методами HPP сервісу https://docs.merchant.alb.ua/platizhni-metodi-hpp AlliancePay. SDK дозволяє легко виконувати авторизацію, створювати замовлення, обробляти вебхуки та керувати транзакціями через єдину точку входу — клас AllianceBankClient.

---

Технічні вимоги

Перед початком роботи переконайтеся, що ваше середовище відповідає наступним вимогам:

• Node.js: версія 20.x або вище.
• TypeScript: рекомендовано для повної підтримки типізації.

---

Встановлення

Встановіть пакет за допомогою вашого пакетного менеджера:

npm install @alliance-bank/payment-sdk

1. Ініціалізація та Авторизація

Для роботи з SDK необхідно створити екземпляр класу AllianceBankClient. Він автоматично керує станом токенів та їх оновленням за допомогою RetryHttpClient та внутрішнього сервісу авторизації.

Приклад ініціалізації:

import { AllianceBankClient, AllianceSDKConfig } from '@alliance-bank/payment-sdk';

const config: AllianceSDKConfig = {
    authentificationData: {
        baseUrl: 'https://api-ecom-prod.bankalliance.ua/', // Базовий URL сервісу надається банком
        merchantId: 'YOUR_MERCHANT_ID', 
        serviceCode: 'YOUR_SERVICE_CODE', 
        authenticationKey: 'YOUR_AUTH_KEY' // Надається банком
    },
    // ВАЖЛИВО: Використовуйте цей колбек для збереження оновлених токенів у вашій базі даних
    onTokenUpdate: async (updatedAuth) => {
        // Наприклад: await db.saveAuthToken(updatedAuth);
    }
};

const client = new AllianceBankClient(config);

2. Створення замовлення

Для створення платежу використовуйте метод createOrder. SDK автоматично додає ваш merchantId та генерує унікальний merchantRequestId для кожного запиту.

Приклад коду:

const orderData = {
    coinAmount: 10050, // Сума в копійках
    hppPayType: 'PURCHASE',
    paymentMethods: ['CARD', 'APPLE_PAY', 'GOOGLE_PAY'],
    successUrl: 'https://your-site.com/success',
    failUrl: 'https://your-site.com/fail',
    statusPageType: 'STATUS_TIMER_PAGE',
    customerData: { senderCustomerId: 'customer_id_1' },
};

try {
    const response = await client.createOrder(orderData);
    console.log('Redirect to payment:', response.redirectUrl);
} catch (error) {
    console.error('Order creation failed:', error);
}

3. Обробка зворотних викликів (Callback/Webhook)

Для автоматичної обробки повідомлень від платіжного шлюзу використовуйте метод handleCallback. Він бере на себе перевірку валідності даних та їх дешифрування.

Приклад використання (Express.js):

app.post('/api/payment/callback', async (req, res) => {
    try {
        // Очікується, що req.body вже є розпарсеним JSON об'єктом
        const callbackDto = await client.handleCallback(req.body);
        
        if (callbackDto.orderStatus === 'SUCCESS') {
            // Обробіть успішний платіж у вашій системі
            console.log('Payment successful for order:', callbackDto.ecomOrderId);
        }
        
        // Повертаємо 200 OK сервісу AlliancePay
        res.status(200).send('OK');
    } catch (error) {
        // Логування помилки та відповідь з помилкою
        console.error('Callback handling error:', error);
        res.status(400).send('Error');
    }
});

4. Повернення коштів (Refund)

Метод createRefund автоматично формує дату у потрібному форматі та ініціює запит на повернення коштів. Ви можете ініціювати як повне, так і часткове повернення.

Приклад виконання Refund:

try {
    const refundResponse = await client.createRefund({
        operationId: 'ORIGINAL_OPERATION_ID', // ID успішної операції по створенню замовлення
        coinAmount: 500, // Сума повернення в копійках
        merchantComment: 'Повернення товару клієнтом'
    });
    console.log('Refund status:', refundResponse.status);
} catch (error) {
    console.error('Refund failed:', error);
}

5. Перевірка статусу замовлення

Якщо вам потрібно вручну перевірити поточний стан транзакції (наприклад, за кроном або якщо користувач закрив сторінку оплати), використовуйте метод checkOrderData з передачею hppOrderId.

Приклад перевірки статусу:

try {
    const orderData = await client.checkOrderData('HPP_ORDER_ID_HERE');
    
    console.log('Current order status:', orderData.orderStatus);
    console.log('Operations history:', orderData.operations); // Масив усіх спроб оплати та повернень
} catch (error) {
    console.error('Status check failed:', error);
}

6. Обробка специфічних помилок (Exceptions)

SDK використовує типізовані помилки для точного визначення причини відмови.

Клас помилки	Опис
ValidationException	Дані не пройшли перевірку за схемою DTO (відсутні обов'язкові поля або невірний тип).
AuthorizationException	Помилки авторизації, невірні ключі або прострочені сесії.
PaymentException	Помилки на рівні платіжної логіки (наприклад, недостатньо коштів для повернення).
AllianceSdkException	Базовий клас для всіх кастомних помилок SDK.

Приклад перевірки помилок:

import { ValidationException, AllianceSdkException } from '@alliance-bank/payment-sdk';

try {
    await client.createOrder(orderData);
} catch (error) {
    if (error instanceof ValidationException) {
        // error.errors містить масив усіх знайдених помилок валідації DTO
        console.error('Validation errors:', error.errors);
    } else if (error instanceof AllianceSdkException) {
        // Обробка бізнес-помилок банку
        console.error(`Bank Error Code: ${error.code}`); // напр. 'b_terminal_not_found'
        console.error(`Message: ${error.message}`);
        console.error(`Raw Response Data:`, error.originalError); // Тіло відповіді банку
    } else {
        console.error('Unexpected system error:', error);
    }
}