### Налаштуйте свій сервер [#set-up-your-server] HTTP (fetch) Node.js SDK cURL Задайте для `TAPAYA_CHECKOUT_API_URL` значення `https://api.sandbox.tapaya.com` і збережіть свій ключ у `TAPAYA_CHECKOUT_API_KEY`. Викликайте API через `fetch` свого серверного середовища, ніколи з браузера клієнта. Приклади зчитують ці значення через `process.env`; адаптуйте це зчитування, якщо ваше середовище використовує інший інтерфейс для секретів. Створіть допоміжну функцію, яка перевіряє HTTP-помилки, перш ніж повернути тіло відповіді: ```js title="server/checkout.js" const apiUrl = process.env.TAPAYA_CHECKOUT_API_URL; const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY; async function checkoutRequest(path, options = {}) { const response = await fetch(new URL(path, apiUrl), { ...options, headers: { ...options.headers, Authorization: `Bearer ${apiKey}`, }, redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(8000), }); if (!response.ok) { throw new Error(`Checkout request failed (${response.status})`); } return response.json(); } ``` Використовуйте Node.js 22.13.0 або новішу версію та встановіть ESM-пакет на своєму сервері: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` Збережіть свій ключ у `TAPAYA_SECRET_KEY` і виберіть середовище пісочниці (sandbox). SDK сам не завантажує файли `.env`, тому завантажте ці значення в середовище свого сервера перед створенням клієнта. ```sh title=".env" TAPAYA_SECRET_KEY=tapaya_test_... TAPAYA_ENVIRONMENT=sandbox ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); // reads TAPAYA_SECRET_KEY ``` Без `TAPAYA_ENVIRONMENT` ключ `tapaya_live_` вибирає робоче середовище, а інші ключі типово використовують пісочницю. У режимі платформи передайте токен мерчанта: `new Tapaya(key, { merchantToken })` або `merchantToken` у кожному виклику. Якщо ваш ключ зберігається під іншою назвою, передайте його як перший аргумент. [Довідник Node.js SDK](/online/integration/node_sdk) описує власні URL API, тайм-аути, повторні спроби та помилки. Виконуйте ці команди на своєму сервері або в довіреному терміналі. Завантажте свій ключ у `TAPAYA_CHECKOUT_API_KEY`, не допускайте його потрапляння в код браузера чи систему контролю версій і спрямуйте URL API на пісочницю: ```bash export TAPAYA_CHECKOUT_API_URL='https://api.sandbox.tapaya.com' ``` ### Створіть сесію [#create-a-session] Обчисліть суму замовлення на своєму сервері, включно з податком і доставкою. Збережіть замовлення та унікальний `checkoutAttemptKey` **до** надсилання запиту й завантажуйте `order` із цього збереженого знімка. Поле `merchantOrderId` обов'язкове. HTTP (fetch) Node.js SDK cURL ```js const session = await checkoutRequest('/merchant/checkout-sessions', { method: 'POST', headers: { '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', }), }); ``` ```ts 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 }, ); ``` Приклад стягує 121,00 EUR за `order-1001`, включно з 21,00 EUR ПДВ і 6,05 EUR за доставку, зі збереженим idempotency key `order-1001-checkout-1`. Замініть ці значення даними свого збереженого замовлення. ```bash curl --request POST \ "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "tax": 2100, "shipping": 605, "taxRate": 21, "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Відповідь містить `id` сесії та `url` сторінки Hosted Checkout. Про підсумки позицій, розбивку податків, дані клієнта та всі поля відповіді див. [Створення сесії Checkout](/online/integration/api_integration#create-a-checkout-session). **Якщо запит не вдався або завершився тайм-аутом,** повторіть його з тим самим ключем і незмінним тілом. Ніколи не генеруйте новий ключ через невизначений результат: змінене тіло з тим самим ключем повертає HTTP 409. | Варіант | Автоматичні повторні спроби | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP (fetch), cURL | Ні. Повторіть запит самостійно. Див. [Ідемпотентність і помилки](/online/integration/api_integration#idempotency-and-errors). | | Node.js SDK | До двох разів після помилки з'єднання, тайм-ауту або HTTP 429, 502, 503 чи 504, з тим самим ключем і тілом. Див. [Ідемпотентність і повторні спроби](/online/integration/node_sdk#idempotency-and-retries). Між окремими викликами чи перезапусками передавайте свій збережений ключ: якщо його не вказати, для кожного виклику генерується новий. | ### Переспрямуйте клієнта [#redirect-the-customer] Збережіть `session.id` разом із замовленням як його `checkoutSessionId`, а потім переспрямуйте браузер на `session.url` за допомогою HTTP 303\. Використовуйте URL без змін, а не формуйте його самостійно. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Якщо ваш фреймворк використовує інший API для відповідей, надішліть HTTP 303 із `session.url` у заголовку `Location`. З cURL відкрийте повернений `url` у браузері, щоб протестувати платіж вручну. ### Перевірте платіж [#verify-the-payment] У своєму обробнику повернення визначте замовлення з автентифікованого контексту оформлення замовлення вашого застосунку та отримайте його збережену сесію на своєму сервері. Робіть це й на URL скасування: відвідування будь-якого з цих URL нічого не доводить. HTTP (fetch) Node.js SDK cURL ```js const current = await checkoutRequest( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, ); if ( current.id !== order.checkoutSessionId || current.merchantOrderId !== order.id || current.amount !== order.totalInMinorUnits || current.currency !== order.currency ) { throw new Error('Checkout session does not match the order'); } const paid = current.paymentStatus === 'successful'; ``` ```ts const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); if ( current.id !== order.checkoutSessionId || current.merchantOrderId !== order.id || current.amount !== order.totalInMinorUnits || current.currency !== order.currency ) { throw new Error('Checkout session does not match the order'); } const paid = current.paymentStatus === 'successful'; ``` Завантажте ID сесії, збережений разом із замовленням, у `CHECKOUT_SESSION_ID`: ```bash curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/$CHECKOUT_SESSION_ID" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" ``` Для прикладу замовлення перевірте, що `id` збігається зі збереженим ID сесії, `merchantOrderId` має значення `order-1001`, `amount` має значення `12100`, `currency` має значення `EUR`, а `paymentStatus` має значення `successful`. Сама лише відповідь HTTP 200 не доводить оплату. Записуйте платіж і виконуйте замовлення лише тоді, коли сесія відповідає вашому збереженому замовленню, а `paymentStatus` має значення `successful`, і записуйте це атомарно, щоб це відбулося лише один раз. Якщо отримати сесію не вдається або результат платежу ще не визначено, збережіть ID сесії та перевірте знову. Див. [Статус платежу](/online/integration/api_integration#payment-status).