### Проведіть онбординг мерчанта [#onboard-your-merchant] Пройдіть [онбординг мерчанта](/merchants/onboarding) з можливістю онлайн-платежів або одночасно онлайн-платежів і платежів у торговій точці. Мерчанту, який використовує лише Checkout, термінал не потрібен. Надайте адресу вебсайту магазину та відомості про онлайн-бізнес і дочекайтеся схвалення платіжного процесора. Саме лише створення запису мерчанта чи API-ключа не вмикає платежі. Відкрийте **Checkout** у [Tapaya Platform](https://platform.tapaya.com/checkout-settings). Мерчанти, які запитують онлайн-платежі, з'являються автоматично, зокрема ті, що очікують схвалення. Продовжуйте, коли мерчант матиме статус **Ready**. Відкрийте **Settings** мерчанта. У розділі **Merchant API key redirects** додайте свій магазин до **Allowed websites** і задайте типові URL успіху та скасування. Платформа, яка використовує Secret key організації, натомість задає їх в **Organization defaults**. У прикладах використовується `https://shop.example`. Про гаманці та брендинг див. [Налаштування Checkout](/online/integration/checkout_settings). ### Збережіть ключ на сервері [#store-your-key-on-the-server] У **Settings** мерчанта виберіть **Create merchant key** і скопіюйте ключ `tapaya_test_…`. Він показується лише один раз. Зберігайте його тільки в серверній конфігурації. Йому ніколи не місце в коді браузера чи системі контролю версій. ```bash title=".env" TAPAYA_ENVIRONMENT=sandbox TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com TAPAYA_SECRET_KEY=tapaya_test_... ``` SDK автоматично зчитує `TAPAYA_SECRET_KEY` і `TAPAYA_ENVIRONMENT`. Наведені нижче HTTP-приклади використовують `TAPAYA_CHECKOUT_API_URL`. Завантажте змінні в процес свого сервера; SDK не завантажує файли `.env`. Надсилайте ключ як `Authorization: Bearer `. Ключ мерчанта сам визначає свого мерчанта, тому інші заголовки не потрібні. Платформа, яка обслуговує багато мерчантів, натомість використовує Secret key організації та надсилає `X-Tapaya-Merchant-Token` у кожному запиті. Див. [автентифікацію Checkout](/online/integration/api_integration#authentication). ### Створіть сесію Checkout [#create-a-checkout-session] Коли клієнт натискає **Checkout** у вашому магазині, обчисліть остаточну суму на своєму сервері, збережіть замовлення з унікальним ключем спроби та створіть сесію. Поле `merchantOrderId` обов'язкове, а замовлення можна оплатити лише один раз. Суми вказуються в мінімальних одиницях валюти, тож `12100` означає 121,00 EUR. Для Node.js 22.13.0 або новішої версії встановіть ESM SDK, перш ніж використовувати приклад **Node.js SDK**: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` HTTP (fetch) Node.js SDK cURL ```js title="server/checkout.js" const response = await fetch( new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL), { method: 'POST', headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': order.checkoutAttemptKey, }, body: JSON.stringify({ merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }), }, ); if (!response.ok) throw new Error(`Checkout failed (${response.status})`); const session = await response.json(); ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const session = await tapaya.checkout.sessions.create( { merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }, { idempotencyKey: order.checkoutAttemptKey }, ); ``` ```bash title="Terminal" curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Якщо запит завершився тайм-аутом, повторіть його з **тим самим** ключем і тілом. API повертає початкову сесію замість того, щоб створювати другу. ### Переспрямуйте клієнта [#redirect-the-customer] Збережіть `session.id` разом із замовленням, а потім переспрямуйте браузер на `session.url` за допомогою HTTP 303. Використовуйте URL точно в тому вигляді, у якому його повернуто. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Tapaya показує підсумок замовлення та захищену платіжну форму, а також виконує токенізацію, 3-D Secure і стягнення оплати. Після відмови клієнт може спробувати іншу картку на тій самій сторінці. Сесії приймають нові платежі протягом 30 хвилин. ### Перевірте платіж на своєму сервері [#verify-the-payment-on-your-server] Коли клієнт потрапляє на ваш URL успіху або скасування, отримайте сесію за допомогою свого Secret key і порівняйте її зі збереженим замовленням. Саме лише переспрямування ніколи не доводить оплату. HTTP (fetch) Node.js SDK ```js title="server/return.js" const response = await fetch( new URL( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, process.env.TAPAYA_CHECKOUT_API_URL, ), { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } }, ); if (!response.ok) throw new Error(`Status check failed (${response.status})`); const current = await response.json(); ``` ```ts title="server/return.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); ``` Для обох інтеграцій порівняйте результат зі збереженим замовленням, перш ніж його виконувати: ```ts const matches = current.id === order.checkoutSessionId && current.merchantOrderId === order.id && current.amount === order.totalInMinorUnits && current.currency === order.currency; if (matches && current.paymentStatus === 'successful') { await fulfillOnce(order); // idempotent, safe on repeated visits } ``` Якщо статус усе ще `unpaid` або отримати сесію не вдається, збережіть ID сесії та перевірте знову. Вебхуків поки немає, тому запускайте завдання звірки для клієнтів, які закривають вкладку до повернення.