Embedded Checkout

Розмістіть захищені поля картки у власному оформленні замовлення. Форма та кнопка надсилання належать вам; Tapaya виконує валідацію картки, токенізацію та 3-D Secure. Вбудовані платежі працюють для схвалених мерчантів, а для тестування доступна пісочниця (sandbox). Цей посібник використовує Tapaya.js 0.2.0 і Node.js SDK 0.3.0.

Перш ніж почати

Встановіть SDK

Один пакет містить серверний клієнт, браузерний SDK і React-хук:

npm install @tapayadot/checkout

Налаштуйте свій сервер

Вбудованим платежам URL повернення не потрібні. Наведені нижче серверні приклади мають версії HTTP (fetch), Node.js SDK і cURL, які всі викликають той самий API мерчанта й не змінюють поля картки в браузері.

Checkout-ключу мерчанта більше нічого не потрібно. У режимі платформи використовуйте Secret key організації, а бекенд, який обслуговує кількох мерчантів, має брати токен з автентифікованого замовлення. Див. автентифікацію Checkout. Client secret видається окремо для кожного платежу.

Пройдіть онбординг з онлайн-платежами та перевірте в налаштуваннях Checkout, що мерчант має статус Ready.

Дозвольте Tapaya у своїй CSP

Завантажувач отримує Tapaya.js 0.2.0 з https://js.tapaya.com/checkout/0.2.0/checkout.js; версія браузерного скрипта не залежить від версії Node.js SDK. Додайте origin ресурсів Tapaya до своєї наявної Content Security Policy:

script-src https://js.tapaya.com
frame-src https://js.tapaya.com

Браузер отримує publishable key і client secret конкретного платежу. Ваш секретний API-ключ мерчанта залишається на вашому сервері, а дані картки та скрипти платіжного провайдера залишаються у фреймі Tapaya. Для локального тестування розмістіть Tapaya.js на власному сервері та передайте його origin завантажувачу, наприклад loadTapaya(publishableKey, { apiOrigin, origin: 'http://localhost:4191' }).

Як це працює

1. Ваша сторінка розміщує поля картки Tapaya та спрямовує їх на ендпоінт на вашому сервері.
2. Під час завантаження сторінки та коли клієнт платить, поля картки викликають цей ендпоінт. Він повертає платіж замовлення як clientSecret: облікові дані для одного платежу, якими поля картки підтверджують платіж безпосередньо в Tapaya. Код вашої сторінки ніколи його не зчитує.
3. Ваша сторінка стежить за outcome платежу. Коли платіж завершено, ваш сервер перевіряє його, перш ніж ви виконаєте замовлення.

Прийом платежу

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 };

<form id="checkout">
	<!-- Your other checkout inputs go here. -->
	<div id="card-fields"></div>
	<button type="submit" disabled>Pay</button>
	<p id="message" role="status"></p>
</form>

import { loadTapaya } from '@tapayadot/checkout/client'
import { config } from './config' // { publishableKey, apiOrigin } from your server

const form = document.querySelector<HTMLFormElement>('#checkout')!
const button = form.querySelector<HTMLButtonElement>('button')!
const message = document.querySelector<HTMLElement>('#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')

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' } },
	);
}

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.
	})
})

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);

Додавання Apple Pay і Google Pay

Гаманці з'являються у фреймі Tapaya поруч із полями картки. Щоб вони відобразилися, перевірте, що:

• Гаманці увімкнено в налаштуваннях Checkout.
• Apple Pay: магазин має активний домен магазину.
• Google Pay у робочому середовищі: налаштовано Google Pay merchant ID.
• Пристрій, браузер і гаманець клієнта підтримують цей спосіб оплати.

Передайте wallets із сумою оформлення замовлення в мінімальних одиницях. Tapaya показує доступні способи оплати, а непідтримувані чи вимкнені гаманці залишаються прихованими. Використовуйте цей приклад замість прикладу createPayment() лише для карток:

const payment = tapaya.createPayment({
	prepare: '/api/payments',
	wallets: { amount: order.totalInMinorUnits, currency: order.currency },
	onWalletClick: async () => {
		if (!form.reportValidity()) throw new Error('Complete the checkout details.')
		// Validate the cart and reserve the order on your server.
		const response = await fetch('/api/payments', { method: 'POST' })
		if (!response.ok) throw new Error('Could not prepare the payment.')
		return response.json() // { clientSecret, status }
	},
	onChange: (snapshot) => {
		button.hidden = snapshot.paymentMethod !== 'card'
		button.disabled = !snapshot.canSubmit
		if (snapshot.outcome === 'completed') location.assign('/checkout/confirmation')
	},
})
await payment.mount('#card-fields')

Сума, що відображається в браузері, має надходити з вашого сервера, який однаково обчислює та валідує суму, коли готує платіж.

Натискання кнопок гаманців

Офіційна кнопка гаманця відкриває нативне платіжне вікно гаманця після натискання клієнтом. onWalletClick валідує ваше оформлення замовлення та резервує його платіж, коли натиснуто цю кнопку, ніколи під час розміщення полів чи вибору способу оплати. Без цієї функції callback гаманці використовують prepare або clientSecret. Якщо ви резервуєте замовлення лише після натискання, подбайте, щоб функція callback prepare, яка викликається під час розміщення, продовжувала наявне замовлення, не створюючи нового.

Залишайте власну кнопку оплати видимою лише тоді, коли snapshot.paymentMethod має значення card; гаманці використовують свої фірмові кнопки замість payment.submit(). Результати оплати гаманцем проходять той самий процес перевірки та відновлення, що й картки. Закриття платіжного вікна гаманця залишає оформлення замовлення доступним; невизначений платіж залишається в очікуванні й блокує повторне стягнення оплати.

Оновлення суми

Передавайте wallets: { amount, currency, disabled: true }, поки обов'язкові дані оформлення замовлення не заповнено. Оновлюйте суму або вмикайте кнопки без повторного розміщення:

payment.update({ wallets: { amount: 2450, currency: 'EUR', disabled: false } })

Передайте wallets: null, щоб приховати гаманці, доки сума не буде готова. Tapaya відмовляє в підтвердженні, якщо підготовлений платіж відрізняється від суми в гаманці. React-хук usePayment() приймає ці параметри й оновлює суму, коли змінюється wallets.

Власний вибір способу оплати

Якщо вибір способу оплати реалізує ваша сторінка, передайте paymentMethod: 'card', 'apple_pay' або 'google_pay', щоб відобразити лише цей спосіб. Недоступний вибраний гаманець показує напис walletUnavailable і повідомляє snapshot.error.code: 'wallet_unavailable', коли можна безпечно почати інший платіж; запропонуйте у своєму виборі інший спосіб оплати. Блокуйте вибір, поки snapshot.busy має значення true або платіж має стан pending чи action_required.

Фрейми та CSP

SDK додає до свого фрейму allow="payment". Якщо ваш магазин розміщено в іншому фреймі, цей зовнішній фрейм також має дозволяти оплату. Apple Pay між різними origin потребує Safari 17 або новішої версії. Скрипти провайдерів гаманців залишаються у фреймі Tapaya, тож вашій сторінці не потрібні додаткові origin провайдерів у CSP.

Обробка простроченого доступу браузера

Термін дії client secret спливає через 24 години, і тоді clientSecret має значення null. Платіж, який так і не було надіслано, тоді скасовується, а наступний prepare() починає нову спробу для того самого замовлення. Платіж в очікуванні залишається pending у браузері, а SDK продовжує викликати ваш ендпоінт, доки ваш сервер не повідомить його результат як status. Читання на сервері й далі працює, тож ваше заплановане завдання в будь-якому разі його завершить.

Діагностика серверних помилок

Node SDK викидає PaymentsApiError для відхилених запитів до API. Перевіряйте його status, code, message, fieldErrors і requestId на своєму сервері. Не допускайте потрапляння облікових даних і client secret до журналів і показуйте власний текст для клієнтів.

Відповідність вашому брендингу

Поля картки використовують чинний колір Checkout мерчанта з налаштувань Checkout як акцент фокуса (colorFocus). Значення, які ви передаєте в appearance.variables, його перевизначають, і надсилаються лише задані вами змінні.