Embedded Checkout

Vložte zabezpečené polia pre kartu priamo do svojej pokladne. Formulár aj odosielacie tlačidlo máte vo svojej réžii; Tapaya zabezpečuje validáciu karty, tokenizáciu a 3-D Secure. Vložené platby sú dostupné v ostrej prevádzke pre schválených obchodníkov a na testovanie je k dispozícii sandbox. Tento sprievodca používa Tapaya.js 0.2.0 a Node.js SDK 0.3.0.

Skôr ako začnete

Inštalácia SDK

Jeden balík obsahuje serverového klienta, SDK pre prehliadač aj React hook:

npm install @tapayadot/checkout

Konfigurácia servera

Vložené platby nepotrebujú návratové URL. Serverové príklady nižšie sú vo verziách HTTP (fetch), Node.js SDK a cURL. Všetky volajú to isté API obchodníka a polia pre kartu v prehliadači nechávajú bez zmeny.

Checkout kľúč obchodníka nič ďalšie nepotrebuje. V režime platformy použite Secret key organizácie a backend, ktorý obsluhuje viacerých obchodníkov, nechajte vyberať token podľa objednávky z autentifikovanej relácie zákazníka. Pozrite si Autentifikácia Checkoutu. Client secrets sú špecifické pre každú platbu.

Dokončite onboarding s online platbami a overte, že je obchodník v nastaveniach Checkoutu v stave Ready.

Povolenie Tapaya vo vašej CSP

Loader sťahuje Tapaya.js 0.2.0 z https://js.tapaya.com/checkout/0.2.0/checkout.js; verzia skriptu pre prehliadač je nezávislá od verzie Node.js SDK. Pridajte origin assetov Tapaya do svojej existujúcej Content Security Policy:

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

Prehliadač dostane publishable key a client secret špecifický pre danú platbu. Váš tajný API kľúč obchodníka zostáva na vašom serveri a údaje o karte aj skripty poskytovateľa platieb zostávajú vnútri rámca Tapaya. Na lokálne testovanie hostujte Tapaya.js sami a jeho origin odovzdajte loaderu, napríklad loadTapaya(publishableKey, { apiOrigin, origin: 'http://localhost:4191' }).

Ako to funguje

1. Vaša stránka pripojí polia pre kartu od Tapaya a nasmeruje ich na endpoint na vašom serveri.
2. Pri načítaní stránky a pri platbe zákazníka volajú polia pre kartu tento endpoint. Ten vráti platbu objednávky ako clientSecret: prihlasovací údaj pre jednu platbu, pomocou ktorého polia pre kartu potvrdia platbu priamo v Tapaya. Kód vašej stránky ho nikdy nečíta.
3. Vaša stránka sleduje outcome platby. Keď sa platba dokončí, váš server ju overí a až potom objednávku vybavíte.

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

Pridanie Apple Pay a Google Pay

Peňaženky sa zobrazujú vnútri rámca Tapaya vedľa polí pre kartu. Aby sa zobrazili, overte, že:

• Peňaženky sú povolené v nastaveniach Checkoutu.
• Apple Pay: obchod má aktívnu doménu obchodu.
• Google Pay v produkčnom prostredí: je nakonfigurované Google Pay merchant ID.
• Zariadenie, prehliadač a peňaženka zákazníka danú metódu podporujú.

Odovzdajte wallets s celkovou sumou pokladne v najmenších jednotkách meny. Tapaya zobrazí dostupné metódy a nepodporované alebo vypnuté peňaženky zostanú skryté. Použite tento kód namiesto príkladu createPayment() iba pre 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á suma zobrazená v prehliadači musí pochádzať z vášho servera, ktorý ju pri príprave platby aj tak sám vypočíta a overí.

Kliknutia na peňaženku

Oficiálne tlačidlo peňaženky otvorí natívne platobné okno peňaženky na základe kliknutia zákazníka. onWalletClick zvaliduje vašu pokladňu a rezervuje jej platbu vo chvíli, keď sa na toto tlačidlo klikne, nikdy pri pripojení ani pri výbere metódy. Bez tohto callbacku používajú peňaženky prepare alebo clientSecret. Ak objednávku rezervujete až pri kliknutí, zabezpečte, aby callback prepare volaný pri pripojení nadviazal na existujúcu objednávku bez toho, aby vytvoril novú.

Vlastné tlačidlo Pay nechajte viditeľné iba vtedy, keď je snapshot.paymentMethod rovné card; peňaženky namiesto payment.submit() používajú svoje značkové tlačidlá. Výsledky platieb peňaženkou prechádzajú rovnakým postupom overenia a obnovy ako karty. Zatvorenie platobného okna peňaženky ponechá pokladňu dostupnú; neistá platba zostane čakajúca a zablokuje ďalšie zaťaženie karty.

Aktualizácia celkovej sumy

Kým nie sú vyplnené povinné údaje pokladne, odovzdávajte wallets: { amount, currency, disabled: true }. Celkovú sumu aktualizujte alebo tlačidlá povoľte bez opätovného pripojenia:

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

Odovzdaním wallets: null peňaženky skryjete, kým nebude celková suma pripravená. Tapaya odmietne potvrdenie, ak sa pripravená platba líši od celkovej sumy peňaženky. React hook usePayment() tieto možnosti prijíma a celkovú sumu aktualizuje, keď sa wallets zmení.

Vlastný výber metódy

Ak výber metódy spravuje vaša stránka, odovzdajte paymentMethod: 'card', 'apple_pay' alebo 'google_pay', aby sa vykreslila iba táto metóda. Nedostupná vybraná peňaženka zobrazí popisok walletUnavailable a nahlási snapshot.error.code: 'wallet_unavailable', ak možno bezpečne začať inú platbu; ponúknite vo svojom výbere inú metódu. Výber zamknite, kým je snapshot.busy true alebo je platba v stave pending či action_required.

Rámce a CSP

SDK pridáva k svojmu rámcu allow="payment". Ak je váš obchod vnútri iného rámca, musí platby povoliť aj tento vonkajší rámec. Apple Pay naprieč originmi vyžaduje Safari 17 alebo novší. Skripty poskytovateľov peňaženiek zostávajú vnútri rámca Tapaya, takže vaša stránka nepotrebuje vo svojej CSP žiadne ďalšie originy poskytovateľov.

Spracovanie vypršaného prístupu prehliadača

Client secret vyprší po 24 hodinách a clientSecret je potom null. Platba, ktorá nebola nikdy odoslaná, sa potom zruší a ďalšie prepare() začne pre tú istú objednávku nový pokus. Čakajúca platba zostáva v prehliadači pending a SDK naďalej volá váš endpoint, kým váš server nenahlási jej výsledok ako status. Čítanie na serveri stále funguje, takže ju vaša plánovaná úloha v každom prípade dokončí.

Diagnostika chýb servera

Node SDK pri odmietnutých požiadavkách na API vyhadzuje PaymentsApiError. Na svojom serveri skontrolujte jeho status, code, message, fieldErrors a requestId. Prihlasovacie údaje a client secrets nezapisujte do logov a zákazníkovi zobrazujte vlastné texty.

Prispôsobenie vašej značke

Polia pre kartu používajú ako farbu zvýraznenia pri fokuse (colorFocus) výslednú farbu pokladne obchodníka z nastavení Checkoutu. Hodnoty, ktoré odovzdáte v appearance.variables, ju prepíšu, a posielajú sa iba premenné, ktoré nastavíte.