### Отримайте налаштування для браузера [#get-the-browser-settings]
Один раз отримайте налаштування для браузера на своєму сервері та додайте їх до конфігурації свого фронтенду.
HTTP (fetch)
Node.js SDK
cURL
Тримайте цю допоміжну функцію на своєму сервері. Вона перевіряє HTTP-помилки, за запитом повертає `null`, якщо платежу замовлення немає,
і не виконує повторних спроб автоматично.
```js title="server/tapaya.js"
const apiOrigin = new URL(process.env.TAPAYA_CHECKOUT_API_URL).origin;
const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY;
const merchantToken = process.env.TAPAYA_MERCHANT_TOKEN;
export async function paymentRequest(path, { method = 'GET', body, key, allowMissing = false } = {}) {
const response = await fetch(new URL(path, apiOrigin), {
method,
headers: {
Authorization: `Bearer ${apiKey}`,
...(merchantToken ? { 'X-Tapaya-Merchant-Token': merchantToken } : {}),
...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
...(key ? { 'Idempotency-Key': key } : {}),
},
...(body === undefined ? {} : { body: JSON.stringify(body) }),
redirect: 'error',
cache: 'no-store',
signal: AbortSignal.timeout(35000),
});
if (allowMissing && response.status === 404) return null;
if (!response.ok) throw new Error(`Payment request failed (${response.status})`);
return response.json();
}
const { publishableKey } = await paymentRequest('/merchant/payments/configuration');
export const config = { publishableKey, apiOrigin };
```
API повертає `publishableKey` і `environment`. Задайте `apiOrigin` на основі URL API, який ви викликали; це не поле
відповіді з конфігурацією.
```ts title="server/config.ts"
import { Tapaya } from '@tapayadot/checkout'
const tapaya = new Tapaya()
const { publishableKey, apiOrigin } = await tapaya.checkout.configuration()
// Sandbox: publishableKey: 'pk_test_…', apiOrigin: 'https://api.sandbox.tapaya.com'
// Production: publishableKey: 'pk_live_…', apiOrigin: 'https://api.tapaya.com'
```
Виконайте це на своєму сервері або в довіреному терміналі. У режимі платформи додайте
`--header "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"` до кожної команди cURL у цьому посібнику.
```bash
curl "$TAPAYA_CHECKOUT_API_URL/merchant/payments/configuration" \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY"
```
Використовуйте повернений `publishableKey` і origin вашого `TAPAYA_CHECKOUT_API_URL` як конфігурацію для браузера.
Обидва значення можна безпечно включати у свою сторінку. Publishable key використовують `pk_test_` з тестовими ключами шлюзу та `pk_live_`
з ключами шлюзу робочого режиму. Завжди передавайте завантажувачу `apiOrigin`, повернений вашим сервером, щоб браузер і сервер
працювали в тому самому середовищі.
### Додайте поля картки [#add-the-card-fields]
Додайте контейнер до своєї наявної форми оформлення замовлення:
```html title="checkout.html"
```
Завантажте Tapaya та розмістіть поля. `prepare` є ендпоінтом, який ви додасте на наступному кроці.
```ts title="checkout.ts"
import { loadTapaya } from '@tapayadot/checkout/client'
import { config } from './config' // { publishableKey, apiOrigin } from your server
const form = document.querySelector
('#checkout')!
const button = form.querySelector('button')!
const message = document.querySelector('#message')!
const tapaya = await loadTapaya(config.publishableKey, { apiOrigin: config.apiOrigin })
const payment = tapaya.createPayment({
prepare: '/api/payments',
onChange: ({ canSubmit, outcome }) => {
button.disabled = !canSubmit
if (outcome === 'completed') location.assign('/checkout/confirmation')
if (outcome === 'ended') message.textContent = 'This payment cannot be completed. Start a new checkout.'
},
})
await payment.mount('#card-fields')
```
Коли поля розміщуються, вони викликають `prepare`, щоб продовжити наявний платіж замовлення. Перезавантаження під час платежу ніколи
не призводить до повторного стягнення оплати: натомість сторінка показує поточний стан платежу.
### Поверніть платіж замовлення [#return-the-orders-payment]
Підключіть цей обробник до `POST /api/payments`. `getCheckoutOrder()` є функцією вашого власного застосунку: автентифікуйте
клієнта, перевірте доступ до його замовлення та поверніть збережені `id`, `amount`, `currency` і `status` цього замовлення. Застосуйте
до маршруту свій звичайний захист від CSRF.
HTTP (fetch)
Node.js SDK
cURL
Перш ніж створювати спробу, прочитайте наявний платіж. Повторно використовуйте невизначений платіж, а нову спробу створюйте
лише після відмови або скасування з `retryAllowed: true`.
```js title="server/payments.js"
import { paymentRequest } from './tapaya.js';
import { getCheckoutOrder } from './orders.js';
export async function findPayment(order) {
const query = new URLSearchParams({ merchantOrderId: order.id });
const payment = await paymentRequest(`/merchant/payments?${query}`, { allowMissing: true });
if (payment && (payment.merchantOrderId !== order.id ||
payment.amount !== order.amount || payment.currency !== order.currency)) {
throw new Error('Payment does not match the order');
}
return payment;
}
export function browserStatus(payment) {
if (payment.status === 'successful') return 'completed';
if (['declined', 'cancelled'].includes(payment.status) && !payment.retryAllowed) return 'ended';
return 'open';
}
export async function POST(request) {
const order = await getCheckoutOrder(request);
const payable = order.status === 'pending_payment';
let payment = await findPayment(order);
if (payable && (!payment ||
(['declined', 'cancelled'].includes(payment.status) && payment.retryAllowed))) {
// Derive the same key on retries, including after a lost creation response.
let key = `${order.id}:${payment ? `after:${payment.id}` : 'initial'}`;
if (/[^\x21-\x7e]/.test(key)) {
const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key));
key = `prepare:${Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')}`;
}
payment = await paymentRequest('/merchant/payments', {
method: 'POST', key,
body: { merchantOrderId: order.id, amount: order.amount, currency: order.currency },
});
if (payment.merchantOrderId !== order.id || payment.amount !== order.amount || payment.currency !== order.currency) {
throw new Error('Payment does not match the order');
}
}
if (!payment) return Response.json({ error: 'Order cannot accept payment' }, { status: 409 });
return Response.json(
{ clientSecret: payable ? payment.clientSecret : null, status: browserStatus(payment) },
{ headers: { 'Cache-Control': 'no-store' } },
);
}
```
Використовуйте код валюти у верхньому регістрі та збережений ID замовлення довжиною щонайбільше 200 символів. Не змінюйте дані замовлення
після початку платежу. У разі тайм-ауту знову прочитайте платіж замовлення, перш ніж вирішувати, чи потрібна нова спроба.
Ніколи не генеруйте новий ключ лише тому, що відповідь було втрачено.
```ts title="server/payments.ts"
import { Tapaya } from '@tapayadot/checkout'
import type { PreparedPayment } from '@tapayadot/checkout'
import { getCheckoutOrder } from './orders'
const tapaya = new Tapaya()
export async function POST(request: Request) {
const order = await getCheckoutOrder(request)
const details = { merchantOrderId: order.id, amount: order.amount, currency: order.currency }
// Only an order awaiting payment gets a payable session. Other orders report their payment's outcome.
const payable = order.status === 'pending_payment'
const session = payable
? await tapaya.checkout.sessions.prepare(details)
: await tapaya.checkout.sessions.verify(details)
if (!session) return Response.json({ error: 'Order cannot accept payment' }, { status: 409 })
// The card fields read both values. Your page code never handles them.
return Response.json(
{ clientSecret: payable ? session.clientSecret : null, status: session.status } satisfies PreparedPayment,
{ headers: { 'Cache-Control': 'no-store' } },
)
}
```
`prepare()` повертає платіж замовлення. Він створює першу спробу, повертає невизначену спробу без змін і
створює наступну спробу після відмови. Він сам формує idempotency key, тому виклик під час кожного завантаження сторінки та
надсилання ніколи не призводить до другого стягнення оплати. Зафіксуйте суму, щойно почнеться платіж: `prepare()` викидає
`TapayaOrderMismatchError`, якщо сума або валюта замовлення більше не відповідають його платежу.
Спочатку знайдіть платіж замовлення. Ці приклади використовують замовлення на 121,00 EUR, збережене на вашому сервері. `404` означає,
що платіж не знайдено; інші HTTP-помилки не дають підстав створювати ще одну спробу.
```bash
curl --get "$TAPAYA_CHECKOUT_API_URL/merchant/payments" \
--data-urlencode 'merchantOrderId=order-1001' \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY"
```
Якщо платежу немає, а замовлення ще може прийняти оплату, створіть першу спробу:
```bash
curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/payments" \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-1001:initial' \
--data '{"merchantOrderId":"order-1001","amount":12100,"currency":"EUR"}'
```
Повторно використовуйте наявний невизначений платіж. Після `declined` або `cancelled` створюйте нову спробу лише тоді, коли
`retryAllowed` має значення `true`. Для цієї спроби повторіть POST з тими самими даними замовлення та ключем
`order-1001:after:`, замінивши заповнювач поверненим `id`. Використовуйте цей ключ і для
повторних спроб. Після тайм-ауту знову знайдіть замовлення; не вважайте, що POST не вдався.
cURL демонструє виклики API. Автентифікований обробник `POST /api/payments` вашого застосунку має повертати
`{ clientSecret, status }` для полів картки. Зіставте статус API за таблицею нижче й надсилайте
`clientSecret: null`, коли ваше замовлення більше не приймає оплату. Ніколи не записуйте ці відповіді в спільні журнали термінала.
REST API повертає стани платежу. Node SDK зіставляє їх зі `status`, якого очікують поля картки; інтеграції через fetch і cURL
застосовують те саме зіставлення у власному ендпоінті prepare:
| `status` API | `status` ендпоінта prepare |
| ----------------------------------------------------------------------------------------------------- | -------------------------- |
| `successful` | `completed` |
| `declined` або `cancelled` з `retryAllowed: false` | `ended` |
| `ready`, `pending`, `action_required` або відмова чи скасування, після яких дозволено повторну спробу | `open` |
* **Беріть суму зі збереженого замовлення** в цілих мінімальних одиницях, ніколи з браузера. Зафіксуйте суму, щойно
почнеться платіж.
* **Відповідайте і для завершених замовлень.** Для замовлення, яке вже оплачено або яке завершило ваше заплановане завдання, ендпоінт однаково повертає
`status` його платежу, тож перезавантаження показує результат, а не помилку. Таке замовлення ніколи не отримує client secret,
тож клієнт не може оплатити замовлення, за яке ви більше не приймаєте оплату.
* **Один успішний платіж на замовлення.** Кожна відмова встановлює `retryAllowed`, тож клієнт може спробувати іншу картку для
того самого замовлення. Це обмеження спільне з [Hosted Checkout](/online/integration/api_integration#one-payment-per-order).
* **Захищайте client secret.** Надсилайте його лише клієнту, уповноваженому оплатити це замовлення, і ніколи не записуйте його в журнали.
* **Очікуйте POST без тіла.** Поля картки надсилають POST на `prepare` у вашому власному origin з cookie і без тіла. Вони відхиляють
переспрямування й ніколи не повторюють запит автоматично. Для власних заголовків, CSRF-токенів чи тіла запиту передайте замість URL
функцію, яка повертає той самий JSON: `prepare: async () => (await fetch(…)).json()`.
### Надсилайте оплату зі свого обробника [#submit-from-your-handler]
Додайте це до того самого скрипта. Ваш обробник валідує вашу форму та викликає `submit()`:
```ts title="checkout.ts"
form.addEventListener('submit', async (event) => {
event.preventDefault()
if (!form.reportValidity() || !payment.snapshot.canSubmit) return
await payment.submit().catch(() => {
// The card fields show the reason. The shopper can try again when canSubmit allows it.
})
})
```
`submit()` викликає `prepare` для платежу, потім валідує картку, виконує 3-D Secure і підтверджує платіж
у Tapaya.
### Покажіть результат [#show-the-outcome]
`onChange` отримує `snapshot` платежу щоразу, коли він змінюється, зокрема коли сторінка завантажується з платежем, який
уже завершено. Орієнтуйтеся на `snapshot.outcome`:
| `outcome` | Що показувати |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Кнопку оплати, активну, поки `canSubmit` має значення true. Після відмови стан залишається `open`, і наступний `submit()` отримує нову спробу. |
| `pending` | Індикатор виконання. Результат ще невідомий, тож повторно оплатити нічого не можна. SDK автоматично перевіряє статус, поки сторінка видима. |
| `completed` | Вашу сторінку підтвердження. Там ваш сервер перевіряє замовлення. |
| `ended` | Нове оформлення замовлення. Для цього замовлення більше спроб неможливо. |
Викликайте `payment.destroy()`, коли компонент оформлення замовлення демонтується. Для React використовуйте `usePayment()` з
`@tapayadot/checkout/react`. Він приймає ті самі параметри плюс `publishableKey` і `apiOrigin` і повертає
`fieldRef` для контейнера, поточний `snapshot` і `submit()`.
### Перевіряйте перед виконанням замовлення [#verify-before-fulfilling]
Результат у браузері призначений лише для відображення. На сторінці підтвердження прочитайте платіж замовлення на своєму сервері й виконуйте замовлення
лише тоді, коли платіж завершено:
HTTP (fetch)
Node.js SDK
cURL
```js title="server/confirmation.js"
import { findPayment } from './payments.js';
const order = await getCheckoutOrder(request);
const payment = await findPayment(order); // Checks order ID, amount, and currency.
if (payment?.status === 'successful') await markOrderPaid(order.id, payment.id);
```
```ts title="server/confirmation.ts"
const order = await getCheckoutOrder(request)
const session = await tapaya.checkout.sessions.verify({
merchantOrderId: order.id,
amount: order.amount,
currency: order.currency,
})
if (session?.status === 'completed') await markOrderPaid(order.id, session.id)
```
`verify()` ніколи не створює платіж і повертає `null` до першої спроби. Він викидає
`TapayaOrderMismatchError`, коли сума або валюта відрізняються від вашого замовлення.
Отримайте поточний платіж замовлення після завершення в браузері або під час перевірки невизначеного результату:
```bash
curl --get "$TAPAYA_CHECKOUT_API_URL/merchant/payments" \
--data-urlencode 'merchantOrderId=order-1001' \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY"
```
Перш ніж виконати приклад замовлення, перевірте `merchantOrderId: "order-1001"`, `amount: 12100`, `currency: "EUR"`
і `status: "successful"`. Збережіть повернений `id` платежу разом із замовленням. Сама лише відповідь HTTP 200 не доводить оплату.
Подбайте, щоб `markOrderPaid()` записувала платіж лише один раз, навіть якщо її викликають повторно, і запускайте виконання замовлення на основі цього
збереженого стану.
Клієнт може закрити вкладку до того, як відкриється сторінка підтвердження. Запустіть заплановане завдання, яке для неоплачених замовлень викликає `verify()` або
читає `GET /merchant/payments?merchantOrderId=...` з тими самими перевірками. Відхилені та
скасовані спроби дозволяють нову спробу, тож неоплачене замовлення залишається `open`: знімайте з нього резервування за власним розкладом, і
лише тоді, коли його `paymentStatus` не має значення `pending`. Невдалий запит чи тайм-аут не є відмовою, тому тримайте замовлення
зарезервованим, доки результат платежу не стане відомим.