Hosted Checkout
Створіть сесію Checkout, переспрямуйте клієнта та перевірте платіж на своєму сервері.
Переспрямуйте клієнта на платіжну сторінку, розміщену Tapaya, для оплати картками, Apple Pay і Google Pay, а потім перевірте результат на своєму сервері. Ваша сторінка ніколи не працює з даними картки, і вам не потрібно додавати поля картки до свого магазину.
- 1. Your backend to Tapaya: Create session.
- 2. Tapaya to Your backend: Session ID and URL.
- 3. Your backend to Your frontend: Redirect to Checkout.
- 4. Your frontend to Tapaya: Open Checkout and pay.
- 5. Tapaya to Your frontend: Return to your shop.
- 6. Your backend to Tapaya: Retrieve session.
- 7. Tapaya to Your backend: Payment status.
- 8. Your backend to Your frontend: Show verified result.
Перш ніж почати
Виберіть ключ залежно від того, хто керує вашим бекендом. Будь-який із ключів зберігайте на своєму сервері; серверні правила наведено в розділі Безпека Checkout.
Один магазин
Використовуйте checkout-ключ мерчанта. Він сам визначає свого мерчанта, і приклади на цій сторінці використовують саме його.
Багато мерчантів
Використовуйте Secret key організації та надсилайте токен мерчанта з кожним запитом.
Потім у розділі Checkout у Tapaya Platform:
- Додайте свого мерчанта та перевірте, що він має статус Ready. Див. Налаштування Checkout.
- Зареєструйте свій магазин як дозволений вебсайт із типовими URL успіху та скасування для вибраного ключа. У
прикладах використовується
https://shop.example.
URL повернення залежать від ключа
Сесії, створені ключем мерчанта, використовують URL повернення мерчанта. Сесії, створені за допомогою Secret key організації, натомість використовують адреси повернення організації. Ці два набори ніколи не поєднуються.
Прийом платежу
Усі три варіанти створюють однакові сесії Checkout з тими самими обліковими даними. Виберіть один; кожен крок нижче враховує ваш вибір.
Налаштуйте свій сервер
Задайте для TAPAYA_CHECKOUT_API_URL значення https://api.sandbox.tapaya.com і збережіть свій ключ у TAPAYA_CHECKOUT_API_KEY.
Викликайте API через fetch свого серверного середовища, ніколи з браузера клієнта. Приклади зчитують ці значення
через process.env; адаптуйте це зчитування, якщо ваше середовище використовує інший інтерфейс для секретів.
Створіть допоміжну функцію, яка перевіряє HTTP-помилки, перш ніж повернути тіло відповіді:
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();
}Створіть сесію
Обчисліть суму замовлення на своєму сервері, включно з податком і доставкою. Збережіть замовлення та унікальний
checkoutAttemptKey до надсилання запиту й завантажуйте order із цього збереженого знімка. Поле merchantOrderId
обов'язкове.
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',
}),
});Відповідь містить id сесії та url сторінки Hosted Checkout. Про підсумки позицій, розбивку податків, дані клієнта
та всі поля відповіді див. Створення сесії Checkout.
Якщо запит не вдався або завершився тайм-аутом, повторіть його з тим самим ключем і незмінним тілом. Ніколи не генеруйте новий ключ через невизначений результат: змінене тіло з тим самим ключем повертає HTTP 409.
| Варіант | Автоматичні повторні спроби |
|---|---|
| HTTP (fetch), cURL | Ні. Повторіть запит самостійно. Див. Ідемпотентність і помилки. |
| Node.js SDK | До двох разів після помилки з'єднання, тайм-ауту або HTTP 429, 502, 503 чи 504, з тим самим ключем і тілом. Див. Ідемпотентність і повторні спроби. Між окремими викликами чи перезапусками передавайте свій збережений ключ: якщо його не вказати, для кожного виклику генерується новий. |
Переспрямуйте клієнта
Збережіть session.id разом із замовленням як його checkoutSessionId, а потім переспрямуйте браузер на session.url за допомогою HTTP
303. Використовуйте URL без змін, а не формуйте його самостійно.
// First persist session.id as the order's checkoutSessionId.
return Response.redirect(session.url, 303);Якщо ваш фреймворк використовує інший API для відповідей, надішліть HTTP 303 із session.url у заголовку Location. З
cURL відкрийте повернений url у браузері, щоб протестувати платіж вручну.
Перевірте платіж
У своєму обробнику повернення визначте замовлення з автентифікованого контексту оформлення замовлення вашого застосунку та отримайте його збережену сесію на своєму сервері. Робіть це й на URL скасування: відвідування будь-якого з цих URL нічого не доводить.
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';Виконуйте замовлення один раз і лише після оплати
Записуйте платіж і виконуйте замовлення лише тоді, коли сесія відповідає вашому збереженому замовленню, а paymentStatus має значення
successful, і записуйте це атомарно, щоб це відбулося лише один раз. Якщо отримати сесію не вдається або результат платежу ще не визначено, збережіть
ID сесії та перевірте знову. Див. Статус платежу.
Обробка результатів платежу
Безпека Checkout описує, що перевіряти і як повторити запит із невідомим результатом, не створюючи другої сесії.
| Результат | Що показує сесія | Що робити |
|---|---|---|
| Відхилено | open з paymentStatus: failed | Нічого. Клієнт може спробувати іншу картку чи гаманець на тій самій сторінці. |
| Ще невідомо | open і unpaid, поки Tapaya підтверджує результат | Отримайте сесію знову пізніше. |
| Нова сесія для того самого замовлення | Попередня неоплачена сесія повідомляє expired | Використовуйте нову сесію. Оплачене замовлення або замовлення, платіж за яким триває, повертає HTTP 409. Див. Один платіж на замовлення. |
| Термін дії минув | Припиняє приймати нові платежі через 30 хвилин після створення | Створіть нову сесію, якщо замовлення все ще не оплачено. Платіж, надісланий до закінчення терміну дії, однаково завершується. |
Вебхуків поки немає
Вебхуків Checkout поки немає. Запустіть на сервері завдання звірки, яке отримує сесії для замовлень, чиї клієнти так і не повертаються.
Перевірка інтеграції
Тестові картки
Перевірте кожен результат платежу в пісочниці.
Контрольний список QA
Перевірте повторні спроби, перервані оформлення замовлень і закінчення терміну дії, перш ніж переходити в робочий режим.