{"_id":"@alliance-bank/payment-sdk","_rev":"5-f75df634fabdb363c575b0e2f8e9be06","name":"@alliance-bank/payment-sdk","dist-tags":{"latest":"1.4.0"},"versions":{"1.0.0":{"name":"@alliance-bank/payment-sdk","version":"1.0.0","author":{"name":"Alliance Bank"},"license":"MIT","_id":"@alliance-bank/payment-sdk@1.0.0","maintainers":[{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"}],"homepage":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk#readme","bugs":{"url":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk/issues"},"dist":{"shasum":"f048bc68ff63f701bef7023295358c0710b987de","tarball":"https://registry.npmjs.org/@alliance-bank/payment-sdk/-/payment-sdk-1.0.0.tgz","fileCount":7,"integrity":"sha512-w5cbeqnLWSPqyW74nOiwxn5kmxKd8ituHNQkbIuwj/3TqEZD68FmCVc2dijpDWLW4Sc2CD1LpVl/rQHylTasNA==","signatures":[{"sig":"MEYCIQDp+kwuVSjdJFjZoBcGPkK/AArZsgvZeQQKkvhMFdfajgIhAL/oqTY0IJPKUCufYkQPiA0KcLegUCK23yPJBPoUtu1D","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alliance-bank%2fpayment-sdk@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":84109},"main":"./dist/client.cjs","type":"module","types":"./dist/client.d.ts","module":"./dist/client.js","exports":{".":{"types":"./dist/client.d.ts","import":"./dist/client.js","require":"./dist/client.cjs"}},"gitHead":"c8cb4507770b1b4b701a5320d77f45a1a216f5a7","scripts":{"dev":"ts-node-dev --respawn index.ts","test":"vitest run","build":"tsup src/client.ts --format cjs,esm --dts --clean","prepare":"npm run build","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"},"repository":{"url":"git+https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Alliance Bank Payment HPP Integration SDK","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^4.3.6","jose":"^6.2.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^4.1.0","typescript":"^5.0.0","@types/node":"^22.19.15","@vitest/coverage-v8":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/payment-sdk_1.0.0_1776330731998_0.498628886437432","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@alliance-bank/payment-sdk","version":"1.1.0","author":{"name":"Alliance Bank"},"license":"MIT","_id":"@alliance-bank/payment-sdk@1.1.0","maintainers":[{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"}],"homepage":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk#readme","bugs":{"url":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk/issues"},"dist":{"shasum":"a7c061fb6dd1d99adfb560c278b30c8d2990fb9e","tarball":"https://registry.npmjs.org/@alliance-bank/payment-sdk/-/payment-sdk-1.1.0.tgz","fileCount":7,"integrity":"sha512-VHvBMiozqETlsyUKulviunME1mVnSquCXhM/nUysEJ3afUlWaOf3ZminAyywC3WWYrGOvAsywzCaqPEoABXhMg==","signatures":[{"sig":"MEYCIQD73+4zjMgIMhtcH4n4BvPnD70ZfqyQXgHJxAR8AlYwVQIhAIwkQh8UtDkyqzMthUG/yiPPaBp2b8KS09Cu//egIuLK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alliance-bank%2fpayment-sdk@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":90954},"main":"./dist/client.cjs","type":"module","types":"./dist/client.d.ts","module":"./dist/client.js","exports":{".":{"types":"./dist/client.d.ts","import":"./dist/client.js","require":"./dist/client.cjs"}},"gitHead":"d4981ae2bfd488619b45fb3db5e14773920bfdcd","scripts":{"dev":"ts-node-dev --respawn index.ts","test":"vitest run","build":"tsup src/client.ts --format cjs,esm --dts --clean","prepare":"npm run build","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"},"repository":{"url":"git+https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Alliance Bank Payment HPP Integration SDK","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^4.3.6","jose":"^6.2.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^4.1.0","typescript":"^5.0.0","@types/node":"^22.19.15","@vitest/coverage-v8":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/payment-sdk_1.1.0_1779265935797_0.8495008242596653","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@alliance-bank/payment-sdk","version":"1.2.0","author":{"name":"Alliance Bank"},"license":"MIT","_id":"@alliance-bank/payment-sdk@1.2.0","maintainers":[{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"}],"homepage":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk#readme","bugs":{"url":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk/issues"},"dist":{"shasum":"3dda0bc82813e17ae149dff5fb7d4833fa9694f6","tarball":"https://registry.npmjs.org/@alliance-bank/payment-sdk/-/payment-sdk-1.2.0.tgz","fileCount":7,"integrity":"sha512-CBcde7wcxEr1txC851QYORtdehYlKQj/x4z1QRfxOEeCDrXIi6nNDpcm6tbcR80WC2XpF2kT0yBcJy6gfSsdZA==","signatures":[{"sig":"MEQCIDbQRxOawL6/KJ2C6e4gZntffF3fw+3adkTp7QhiuB1oAiASB3dCj1Y0OtyPKkMG74R0NMvMqrZnpeNjyT7nIG/ppQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alliance-bank%2fpayment-sdk@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":101456},"main":"./dist/client.cjs","type":"module","types":"./dist/client.d.ts","module":"./dist/client.js","exports":{".":{"types":"./dist/client.d.ts","import":"./dist/client.js","require":"./dist/client.cjs"}},"gitHead":"6f8d11b35b38767161e15738306864af3e0e99b3","scripts":{"dev":"ts-node-dev --respawn index.ts","test":"vitest run","build":"tsup src/client.ts --format cjs,esm --dts --clean","prepare":"npm run build","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"},"repository":{"url":"git+https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Alliance Bank Payment HPP Integration SDK","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^4.3.6","jose":"^6.2.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^4.1.0","typescript":"^5.0.0","@types/node":"^22.19.15","@vitest/coverage-v8":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/payment-sdk_1.2.0_1783003672110_0.4460376380114015","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@alliance-bank/payment-sdk","version":"1.3.0","author":{"name":"Alliance Bank"},"license":"MIT","_id":"@alliance-bank/payment-sdk@1.3.0","maintainers":[{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"}],"homepage":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk#readme","bugs":{"url":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk/issues"},"dist":{"shasum":"71cdd73fc58c85da2f45de0bd0380db5baa6a2b4","tarball":"https://registry.npmjs.org/@alliance-bank/payment-sdk/-/payment-sdk-1.3.0.tgz","fileCount":7,"integrity":"sha512-ena6L62Zp72/3pX0n3a8rj3hDdTggPxvolQaNXLkaWq9jzdc5imNXJmnhB5cfAq6Y3rmhwofU7OcVgmPocG9Cg==","signatures":[{"sig":"MEQCIAH7pz+aMn0b9Gincs+iT1jm9FrkXAKNTr8Jr4tZ9QvGAiA0mSLQIFUMfXWWNyBQTpa29ULPrdg4DEtE0EiyeUHlFw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alliance-bank%2fpayment-sdk@1.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":143939},"main":"./dist/client.cjs","type":"module","types":"./dist/client.d.ts","module":"./dist/client.js","exports":{".":{"types":"./dist/client.d.ts","import":"./dist/client.js","require":"./dist/client.cjs"}},"gitHead":"0297c388ff5e708e6c42ff19aed64abf978f3e0d","scripts":{"dev":"ts-node-dev --respawn index.ts","test":"vitest run","build":"tsup src/client.ts --format cjs,esm --dts --clean","prepare":"npm run build","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"},"repository":{"url":"git+https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"Alliance Bank Payment HPP Integration SDK","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^4.3.6","jose":"^6.2.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^4.1.0","typescript":"^5.0.0","@types/node":"^22.19.15","@vitest/coverage-v8":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/payment-sdk_1.3.0_1786028038184_0.4839119460023731","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"@alliance-bank/payment-sdk","version":"1.4.0","license":"MIT","author":{"name":"Alliance Bank"},"type":"module","description":"Alliance Bank Payment HPP Integration SDK","main":"./dist/client.cjs","module":"./dist/client.js","types":"./dist/client.d.ts","exports":{".":{"types":"./dist/client.d.ts","import":"./dist/client.js","require":"./dist/client.cjs"}},"repository":{"type":"git","url":"git+https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk.git"},"bugs":{"url":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk/issues"},"homepage":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk#readme","scripts":{"build":"tsup src/client.ts --format cjs,esm --dts --clean","dev":"ts-node-dev --respawn index.ts","test":"vitest run","test:coverage":"vitest run --coverage","prepare":"npm run build"},"dependencies":{"jose":"^6.2.1","zod":"^4.3.6"},"devDependencies":{"@types/node":"^22.19.15","@vitest/coverage-v8":"^4.1.0","tsup":"^8.0.0","typescript":"^5.0.0","vitest":"^4.1.0"},"publishConfig":{"access":"public","provenance":true},"_id":"@alliance-bank/payment-sdk@1.4.0","gitHead":"a19647b159b975c3ac4dbd706eddee907b2939a6","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-XUrUMV4ZFJLpwlyBcKU0IqVpYHZ2A1HZneo/84Ag546kI4JLpKTQYFB0P8hPAU1CfoqWxnNnVhjGbnYMEVO1Gw==","shasum":"b280c3f5f42f8be332379a462c705613d228ec0c","tarball":"https://registry.npmjs.org/@alliance-bank/payment-sdk/-/payment-sdk-1.4.0.tgz","fileCount":7,"unpackedSize":157856,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alliance-bank%2fpayment-sdk@1.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCx0gKSqLUVW/+PewRDGqVctJAoqeRclBIZUAtMxJjrAQIgA3vHxYZYcUVai22kXHma4TFZ/Ev7R4ZK0aXp5gA4uwM="}]},"_npmUser":{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"},"directories":{},"maintainers":[{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/payment-sdk_1.4.0_1787817220087_0.8674710179455112"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-16T09:12:11.898Z","modified":"2026-08-27T07:53:40.847Z","1.0.0":"2026-04-16T09:12:12.127Z","1.1.0":"2026-05-20T08:32:15.940Z","1.2.0":"2026-07-02T14:47:52.229Z","1.3.0":"2026-08-06T14:53:58.323Z","1.4.0":"2026-08-27T07:53:40.231Z"},"bugs":{"url":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk/issues"},"author":{"name":"Alliance Bank"},"license":"MIT","homepage":"https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk#readme","repository":{"type":"git","url":"git+https://github.com/alliancedigital-tech/alliancepay-nodejs-sdk.git"},"description":"Alliance Bank Payment HPP Integration SDK","maintainers":[{"name":"alliancebank","email":"msb-tech@alliancebank.org.ua"}],"readme":"# AlliancePay NodeJS SDK\n\nЦе офіційне NodeJS SDK для інтеграції з платіжними методами HPP сервісу https://docs.merchant.alb.ua/platizhni-metodi-hpp **AlliancePay**. SDK дозволяє легко виконувати авторизацію, створювати замовлення, обробляти вебхуки та керувати транзакціями через єдину точку входу — клас `AllianceBankClient`.\n\n---\n\n## Технічні вимоги\n\nПеред початком роботи переконайтеся, що ваше середовище відповідає наступним вимогам:\n\n* **Node.js:** версія `18.x` або вище.\n* **TypeScript:** рекомендовано для повної підтримки типізації.\n\n---\n\n## Встановлення\n\nВстановіть пакет за допомогою вашого пакетного менеджера:\n\n```bash\nnpm install alliance-payment-hpp-integration-sdk\n```\n\n### 1. Ініціалізація та Авторизація\nДля роботи з SDK необхідно створити екземпляр класу AllianceBankClient. Він автоматично керує станом токенів та їх оновленням за допомогою `RetryHttpClient` та внутрішнього сервісу авторизації.\n\nПриклад ініціалізації:\n```typescript\nimport { AllianceBankClient, AllianceSDKConfig } from 'alliance-payment-hpp-integration-sdk';\n\nconst config: AllianceSDKConfig = {\n    authentificationData: {\n        baseUrl: 'https://api-ecom-prod.bankalliance.ua/', // Базовий URL сервісу надається банком\n        merchantId: 'YOUR_MERCHANT_ID', \n        serviceCode: 'YOUR_SERVICE_CODE', \n        authenticationKey: 'YOUR_AUTH_KEY' // Надається банком\n    },\n    // ВАЖЛИВО: Використовуйте цей колбек для збереження оновлених токенів у вашій базі даних\n    onTokenUpdate: async (updatedAuth) => {\n        // Наприклад: await db.saveAuthToken(updatedAuth);\n    }\n};\n\nconst client = new AllianceBankClient(config);\n```\n#### Особливість архітектури: \nSDK використовує Lazy Loading (ліниву ініціалізацію). \nВнутрішні сервіси створюються лише в момент першого виклику, що робить клієнт максимально легким та економить пам'ять.\n\n### 2. Створення замовлення\nДля створення платежу використовуйте метод `createOrder`. \nSDK автоматично додає ваш `merchantId` та генерує унікальний `merchantRequestId` для кожного запиту.\n\n#### Приклад коду:\n```typescript\nconst orderData = {\n    coinAmount: 10050, // Сума в копійках\n    hppPayType: 'PURCHASE',\n    paymentMethods: ['CARD', 'APPLE_PAY', 'GOOGLE_PAY'],\n    successUrl: 'https://your-site.com/success',\n    failUrl: 'https://your-site.com/fail',\n    statusPageType: 'STATUS_TIMER_PAGE',\n    customerData: { senderCustomerId: 'customer_id_1' },\n};\n\ntry {\n    const response = await client.createOrder(orderData);\n    console.log('Redirect to payment:', response.redirectUrl);\n} catch (error) {\n    console.error('Order creation failed:', error);\n}\n```\n\n#### Вибір валюти (UAH / USD / EUR)\nЗа замовчуванням замовлення створюється в **UAH**. Щоб створити замовлення в іншій валюті, передайте\nопціональне поле `currencyCode`:\n\n| Валюта | `currencyCode` |\n|--------|-----------------|\n| UAH (за замовчуванням) | `980` |\n| USD | `840` |\n| EUR | `978` |\n\n```typescript\n// Замовлення в USD\nconst orderDataUsd = {\n    coinAmount: 1050, // Сума в мінімальних одиницях валюти (тут — центи USD)\n    currencyCode: 840, // USD\n    hppPayType: 'PURCHASE',\n    paymentMethods: ['CARD', 'APPLE_PAY', 'GOOGLE_PAY'],\n    successUrl: 'https://your-site.com/success',\n    failUrl: 'https://your-site.com/fail',\n    statusPageType: 'STATUS_TIMER_PAGE',\n    customerData: { senderCustomerId: 'customer_id_1' },\n};\n\n// Замовлення в EUR — так само, лише інший код валюти\nconst orderDataEur = { ...orderDataUsd, currencyCode: 978 }; // EUR\n\ntry {\n    const response = await client.createOrder(orderDataUsd);\n    console.log('Redirect to payment:', response.redirectUrl);\n} catch (error) {\n    console.error('Order creation failed:', error);\n}\n```\n\n> **Важливо:** платежі типу `hppPayType: 'A2A'` підтримують лише UAH (`currencyCode: 980`).\n> Якщо передати `840`/`978` разом з `A2A`, SDK кине `ValidationException` ще до відправки запиту в банк.\n\n### 3. Обробка зворотних викликів (Callback/Webhook)\nДля автоматичної обробки повідомлень від платіжного шлюзу використовуйте метод `handleCallback`. \nВін бере на себе перевірку валідності даних та їх дешифрування.\n\nПоле `callbackDto.operation.type` визначає тип операції: `'PURCHASE'`, `'REFUND'`, `'PREAUTH'`, `'COMPLETION'` або `'ACCOUNT_2_ACCOUNT'`.\n\n#### Приклад використання (Express.js):\n```typescript\napp.post('/api/payment/callback', async (req, res) => {\n    try {\n        // Очікується, що req.body вже є розпарсеним JSON об'єктом\n        const callbackDto = await client.handleCallback(req.body);\n        const { operation } = callbackDto;\n\n        if (operation.type === 'PURCHASE' && operation.status === 'SUCCESS') {\n            // Обробіть успішний платіж у вашій системі\n            console.log('Payment successful for order:', callbackDto.ecomOrderId);\n        }\n\n        if (operation.type === 'PREAUTH' && operation.status === 'SUCCESS') {\n            // Кошти заморожено — збережіть operationId для виконання COMPLETION\n            console.log('PREAUTH successful, operationId:', operation.operationId);\n            // await db.savePreauthOperationId(callbackDto.hppOrderId, operation.operationId);\n        }\n\n        if (operation.type === 'COMPLETION' && operation.status === 'SUCCESS') {\n            // Кошти успішно списано\n            console.log('COMPLETION successful for order:', callbackDto.ecomOrderId);\n            console.log('Original PREAUTH operationId:', operation.preauthOperationId);\n            console.log('Original PREAUTH amount (coins):', operation.preauthCoinAmount);\n        }\n\n        // Повертаємо 200 OK сервісу AlliancePay\n        res.status(200).send('OK');\n    } catch (error) {\n        // Логування помилки та відповідь з помилкою\n        console.error('Callback handling error:', error);\n        res.status(400).send('Error');\n    }\n});\n```\n\n### 4. Повернення коштів (Refund)\nМетод `createRefund` автоматично формує дату у потрібному форматі та ініціює запит на повернення коштів.\nВи можете ініціювати як повне, так і часткове повернення.\n\n#### Приклад виконання Refund:\n```typescript\ntry {\n    const refundResponse = await client.createRefund({\n        operationId: 'ORIGINAL_OPERATION_ID', // ID успішної операції по створенню замовлення\n        coinAmount: 500, // Сума повернення в копійках\n        merchantComment: 'Повернення товару клієнтом'\n    });\n    console.log('Refund status:', refundResponse.status);\n} catch (error) {\n    console.error('Refund failed:', error);\n}\n```\n\n#### Повернення суми в іноземній валюті\nЯкщо оригінальний платіж був у USD/EUR, замість `coinAmount` можна передати `sourceAmount`\n(сума в основних одиницях валюти, напр. `10.5` USD) та `conversionRate` (курс до UAH) — SDK сам\nпорахує суму повернення в копійках UAH: `coinAmount = round(sourceAmount * conversionRate * 100)`.\n\n```typescript\ntry {\n    const refundResponse = await client.createRefund({\n        operationId: 'ORIGINAL_OPERATION_ID',\n        sourceAmount: 10.5,     // Сума повернення в USD/EUR\n        conversionRate: 41.2,   // Курс конвертації в UAH на момент операції\n        merchantComment: 'Повернення товару клієнтом'\n    });\n    console.log('Refund status:', refundResponse.status);\n} catch (error) {\n    console.error('Refund failed:', error);\n}\n```\n\n> `coinAmount` та пара `sourceAmount`/`conversionRate` — взаємовиключні способи задати суму.\n> Якщо передані обидва `sourceAmount` і `conversionRate`, вони мають пріоритет і `coinAmount`\n> обчислюється з них автоматично.\n\n### 5. Попередня авторизація (PREAUTH)\nPREAUTH дозволяє заморозити кошти на картці клієнта без їх фактичного списання. Кошти утримуються до моменту виконання COMPLETION або закінчення терміну дії авторизації.\n\nДля ініціювання передайте `hppPayType: 'PREAUTH'` у метод `createOrder`. SDK автоматично встановить `preAuthExpDate` (поточний час + 2 години 30 секунд), якщо ви не передасте це поле явно.\n\n> **`preAuthExpDate`** — необов'язковий параметр. Якщо передаєте вручну, дотримуйтеся формату `YYYY-MM-DD HH:mm:ss.SS±HH:MM` (наприклад, `2025-11-13 15:01:54.56+02:00`). Значення має бути не раніше ніж через 2 години та не пізніше ніж через 28 днів від поточного моменту.\n\n#### Приклад ініціювання PREAUTH:\n```typescript\n// SDK автоматично встановить preAuthExpDate = тепер + 2год 30сек\nconst orderData = {\n    coinAmount: 25000, // Сума в копійках\n    hppPayType: 'PREAUTH',\n    paymentMethods: ['CARD'],\n    successUrl: 'https://your-site.com/success',\n    failUrl: 'https://your-site.com/fail',\n    statusPageType: 'STATUS_TIMER_PAGE',\n    customerData: { senderCustomerId: 'customer_id_1' },\n};\n\n// Або із явно заданим терміном дії авторизації (від +2год до +28 днів від поточного моменту):\nconst orderDataWithExpDate = {\n    ...orderData,\n    preAuthExpDate: '2025-11-13 15:01:54.56+02:00',\n};\n\ntry {\n    const response = await client.createOrder(orderData);\n    console.log('Redirect to payment page:', response.redirectUrl);\n    // Зберігаємо hppOrderId для подальшої перевірки статусу\n    console.log('HPP Order ID:', response.hppOrderId);\n} catch (error) {\n    console.error('PREAUTH order creation failed:', error);\n}\n```\n\nПісля того як клієнт підтвердить авторизацію на сторінці оплати, сервіс надішле callback із `operation.type === 'PREAUTH'`. Збережіть `operationId` з тіла callback — він знадобиться для виконання COMPLETION (див. розділ 3).\n\n### 6. Завершення авторизації (COMPLETION)\nCOMPLETION списує кошти, заморожені попередньою PREAUTH-операцією. Сума списання може відрізнятися від суми попередньої авторизації не більше ніж на **±20%**.\n\nМетод `createCompletion` приймає два аргументи:\n1. Об'єкт із даними операції — `originalOperationId`, `coinAmount` та опціонально `notificationUrl`.\n2. `originalCoinAmount` — сума оригінальної PREAUTH-операції в копійках. Використовується для перевірки допустимого діапазону списання.\n\nSDK автоматично додає `merchantId`, `merchantRequestId` та `date`.\n\n#### Приклад виконання COMPLETION:\n```typescript\nimport { CompletionAmountException, AllianceSdkException } from 'alliance-payment-hpp-integration-sdk';\n\nconst originalCoinAmount = 25000; // Сума оригінальної PREAUTH в копійках\n\ntry {\n    const completionResponse = await client.createCompletion(\n        {\n            originalOperationId: 'PREAUTH_OPERATION_ID', // operationId з callback PREAUTH\n            coinAmount: 24000, // Сума списання (в межах ±20% від 25000: 20000–30000)\n            notificationUrl: 'https://your-site.com/api/completion-callback', // Опціонально\n        },\n        originalCoinAmount\n    );\n\n    console.log('Completion status:', completionResponse.status);\n    console.log('ecomOperationId:', completionResponse.ecomOperationId);\n    console.log('Original PREAUTH operationId:', completionResponse.preauthOperationId);\n    console.log('Original PREAUTH amount (coins):', completionResponse.preauthCoinAmount);\n} catch (error) {\n    if (error instanceof CompletionAmountException) {\n        // Сума виходить за межі ±20% від оригінальної PREAUTH\n        console.error('Amount out of allowed range:', error.message);\n    } else if (error instanceof AllianceSdkException) {\n        console.error(`Bank Error Code: ${error.code}`);\n        console.error(`Message: ${error.message}`);\n    } else {\n        console.error('Unexpected error:', error);\n    }\n}\n```\n\n#### Списання суми в іноземній валюті\nТак само, як і для Refund, замість `coinAmount` можна передати `sourceAmount` + `conversionRate` —\nSDK автоматично конвертує суму списання в копійки UAH перед перевіркою діапазону ±20% та відправкою запиту.\n\n```typescript\nconst originalCoinAmount = 25000; // Сума оригінальної PREAUTH в копійках UAH\n\ntry {\n    const completionResponse = await client.createCompletion(\n        {\n            originalOperationId: 'PREAUTH_OPERATION_ID',\n            sourceAmount: 9.6,      // Сума списання в USD/EUR\n            conversionRate: 41.2,   // Курс конвертації в UAH на момент операції\n            notificationUrl: 'https://your-site.com/api/completion-callback', // Опціонально\n        },\n        originalCoinAmount\n    );\n\n    console.log('Completion status:', completionResponse.status);\n} catch (error) {\n    if (error instanceof CompletionAmountException) {\n        console.error('Amount out of allowed range:', error.message);\n    } else {\n        console.error('Unexpected error:', error);\n    }\n}\n```\n\n> **`originalCoinAmount`** (другий аргумент) завжди залишається в копійках **UAH** — незалежно від\n> валюти списання, це сума оригінальної PREAUTH-операції, і саме з нею SDK порівнює\n> UAH-еквівалент суми COMPLETION при перевірці діапазону ±20%.\n\n### 7. Перевірка статусу замовлення\nЯкщо вам потрібно вручну перевірити поточний стан транзакції \n(наприклад, за кроном або якщо користувач закрив сторінку оплати), \nвикористовуйте метод `checkOrderData` з передачею `hppOrderId`.\n\n#### Приклад перевірки статусу:\n```typescript\ntry {\n    const orderData = await client.checkOrderData('HPP_ORDER_ID_HERE');\n    \n    console.log('Current order status:', orderData.orderStatus);\n    console.log('Operations history:', orderData.operations); // Масив усіх спроб оплати та повернень\n} catch (error) {\n    console.error('Status check failed:', error);\n}\n```\n\n### 8. Обробка специфічних помилок (Exceptions)\nSDK використовує типізовані помилки для точного визначення причини відмови.\n\n| Клас помилки                 | Опис |\n|------------------------------| -------- |\n| `ValidationException`        | Дані не пройшли перевірку за схемою DTO (відсутні обов'язкові поля або невірний тип).  |\n| `AuthorizationException`     | Помилки авторизації, невірні ключі або прострочені сесії. |\n| `PaymentException`           | Помилки на рівні платіжної логіки (наприклад, недостатньо коштів для повернення). |\n| `CompletionException`        | Помилки HTTP, шифрування або API під час виконання COMPLETION. |\n| `CompletionAmountException`  | Сума COMPLETION виходить за межі ±20% від суми оригінальної PREAUTH. |\n| `AllianceSdkException`       | Базовий клас для всіх кастомних помилок SDK. |\n\n#### Приклад перевірки помилок:\n```typescript\nimport { ValidationException, AllianceSdkException } from 'alliance-payment-hpp-integration-sdk';\n\ntry {\n    await client.createOrder(orderData);\n} catch (error) {\n    if (error instanceof ValidationException) {\n        // error.errors містить масив усіх знайдених помилок валідації DTO\n        console.error('Validation errors:', error.errors);\n    } else if (error instanceof AllianceSdkException) {\n        // Обробка бізнес-помилок банку\n        console.error(`Bank Error Code: ${error.code}`); // напр. 'b_terminal_not_found'\n        console.error(`Message: ${error.message}`);\n        console.error(`Raw Response Data:`, error.originalError); // Тіло відповіді банку\n    } else {\n        console.error('Unexpected system error:', error);\n    }\n}\n```\n","readmeFilename":"README.md"}