Embedded Checkout

Vložte zabezpečená pole pro kartu přímo do své pokladny. Formulář i odesílací tlačítko máte ve své režii; Tapaya zajišťuje validaci karty, tokenizaci a 3-D Secure. Vložené platby jsou dostupné v ostrém provozu pro schválené obchodníky a pro testování je k dispozici sandbox. Tento průvodce používá Tapaya.js 0.2.0 a Node.js SDK 0.3.0.

Než začnete

Instalace SDK

Jeden balíček obsahuje serverového klienta, SDK pro prohlížeč i React hook:

npm install @tapayadot/checkout

Konfigurace serveru

Vložené platby nepotřebují návratové URL. Serverové příklady níže jsou ve verzích HTTP (fetch), Node.js SDK a cURL. Všechny volají stejné API obchodníka a pole pro kartu v prohlížeči nechávají beze změny.

Checkout klíč obchodníka nic dalšího nepotřebuje. V režimu platformy použijte Secret key organizace a backend obsluhující více obchodníků nechte vybírat token podle autentizované objednávky. Viz Autentizace Checkoutu. Client secrety jsou specifické pro každou platbu.

Dokončete onboarding s online platbami a ověřte, že je obchodník v nastavení Checkoutu ve stavu Ready.

Povolení Tapaya ve vaší CSP

Loader stahuje Tapaya.js 0.2.0 z https://js.tapaya.com/checkout/0.2.0/checkout.js; verze prohlížečového skriptu je nezávislá na verzi Node.js SDK. Přidejte origin assetů Tapaya do své stávající Content Security Policy:

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

Prohlížeč dostane publishable key a client secret specifický pro danou platbu. Váš tajný API klíč obchodníka zůstává na vašem serveru a údaje o kartě i skripty poskytovatele plateb zůstávají uvnitř rámce Tapaya. Pro lokální testování hostujte Tapaya.js sami a jeho origin předejte loaderu, například loadTapaya(publishableKey, { apiOrigin, origin: 'http://localhost:4191' }).

Jak to funguje

1. Vaše stránka připojí pole pro kartu od Tapaya a nasměruje je na endpoint na vašem serveru.
2. Při načtení stránky a při platbě zákazníka volají pole pro kartu tento endpoint. Ten vrátí platbu objednávky jako clientSecret: přihlašovací údaj pro jednu platbu, pomocí kterého pole pro kartu potvrdí platbu přímo u Tapaya. Kód vaší stránky ho nikdy nečte.
3. Vaše stránka sleduje outcome platby. Když se platba dokončí, váš server ji ověří a teprve potom objednávku vyřídíte.

Přijetí platby

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

Přidání Apple Pay a Google Pay

Peněženky se zobrazují uvnitř rámce Tapaya vedle polí pro kartu. Aby se zobrazily, ověřte, že:

• Peněženky jsou povolené v nastavení Checkoutu.
• Apple Pay: obchod má aktivní doménu obchodu.
• Google Pay v produkčním prostředí: je nakonfigurované Google Pay merchant ID.
• Zařízení, prohlížeč a peněženka zákazníka danou metodu podporují.

Předejte wallets s celkovou částkou pokladny v nejmenších jednotkách měny. Tapaya zobrazí dostupné metody a nepodporované nebo vypnuté peněženky zůstanou skryté. Použijte tento kód místo příkladu createPayment() pouze pro karty:

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

Celková částka zobrazená v prohlížeči musí pocházet z vašeho serveru, který ji při přípravě platby i tak sám vypočítá a ověří.

Kliknutí na peněženku

Oficiální tlačítko peněženky otevře nativní okno peněženky na základě kliknutí zákazníka. onWalletClick zvaliduje vaši pokladnu a rezervuje její platbu ve chvíli, kdy se na toto tlačítko klikne, nikdy při připojení ani při výběru metody. Bez tohoto callbacku používají peněženky prepare nebo clientSecret. Pokud objednávku rezervujete až při kliknutí, zajistěte, aby callback prepare volaný při připojení navázal na existující objednávku, aniž by vytvořil novou.

Vlastní tlačítko Zaplatit nechte viditelné pouze tehdy, když je snapshot.paymentMethod rovno card; peněženky místo payment.submit() používají svá značková tlačítka. Výsledky plateb peněženkou procházejí stejným postupem ověření a obnovy jako karty. Zavření okna peněženky ponechá pokladnu dostupnou; nejistá platba zůstane ve stavu pending a zablokuje další platbu.

Aktualizace celkové částky

Dokud nejsou vyplněné povinné údaje pokladny, předávejte wallets: { amount, currency, disabled: true }. Celkovou částku aktualizujte nebo tlačítka povolte bez opětovného připojení:

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

Předáním wallets: null peněženky skryjete, dokud nebude celková částka připravena. Tapaya odmítne potvrzení, pokud se připravená platba liší od celkové částky peněženky. React hook usePayment() tyto možnosti přijímá a celkovou částku aktualizuje, když se wallets změní.

Vlastní výběr metody

Pokud výběr metody spravuje vaše stránka, předejte paymentMethod: 'card', 'apple_pay' nebo 'google_pay', aby se vykreslila pouze tato metoda. Nedostupná vybraná peněženka zobrazí popisek walletUnavailable a nahlásí snapshot.error.code: 'wallet_unavailable', pokud lze bezpečně zahájit jinou platbu; nabídněte ve svém výběru jinou metodu. Výběr zamkněte, dokud je snapshot.busy true nebo je platba ve stavu pending či action_required.

Rámce a CSP

SDK přidává ke svému rámci allow="payment". Pokud je váš obchod uvnitř jiného rámce, musí platby povolit i tento vnější rámec. Apple Pay napříč originy vyžaduje Safari 17 nebo novější. Skripty poskytovatelů peněženek zůstávají uvnitř rámce Tapaya, takže vaše stránka nepotřebuje ve své CSP žádné další originy poskytovatelů.

Řešení vypršeného přístupu prohlížeče

Client secret vyprší po 24 hodinách a clientSecret je pak null. Platba, která nebyla nikdy odeslána, je pak zrušena a další prepare() zahájí pro stejnou objednávku nový pokus. Čekající platba zůstává v prohlížeči pending a SDK nadále volá váš endpoint, dokud váš server nenahlásí její výsledek jako status. Čtení na serveru stále funguje, takže ji vaše plánovaná úloha v každém případě dokončí.

Diagnostika chyb serveru

Node SDK vyhazuje u odmítnutých požadavků na API PaymentsApiError. Na svém serveru zkontrolujte jeho status, code, message, fieldErrors a requestId. Přihlašovací údaje a client secrety nezapisujte do logů a zákazníkovi zobrazujte vlastní texty.

Přizpůsobení vaší značce

Pole pro kartu používají jako barvu zvýraznění při fokusu (colorFocus) výslednou barvu pokladny obchodníka z nastavení Checkoutu. Hodnoty, které předáte v appearance.variables, ji přepíšou, a odesílají se pouze proměnné, které nastavíte.