Hosted Checkout

Vytvořte relaci Checkoutu, přesměrujte zákazníka a ověřte platbu ze svého serveru.

Pošlete zákazníka na platební stránku hostovanou společností Tapaya pro karty, Apple Pay a Google Pay a poté ověřte výsledek na svém serveru. Vaše stránka nikdy nepracuje s údaji o kartě a do svého obchodu nepřidáváte žádná pole pro kartu.

Your frontend

Your backend

Tapaya

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.

Než začnete

Zvolte klíč podle toho, kdo provozuje váš backend. Ať zvolíte kterýkoli, uchovávejte jej na svém serveru; pravidla pro stranu serveru uvádí stránka Zabezpečení Checkoutu.

Jeden obchod

Použijte Checkout klíč obchodníka. Určuje svého obchodníka a používají jej i zdejší příklady.

Mnoho obchodníků

Použijte Secret key organizace a s každým požadavkem posílejte token obchodníka.

Poté v části Checkout v Tapaya Platform:

Přidejte svého obchodníka a ověřte, že se zobrazuje jako Ready. Viz Nastavení Checkoutu.
Zaregistrujte svůj obchod jako povolený web s výchozími URL pro úspěch a zrušení, a to pro klíč, který jste zvolili. Příklady používají https://shop.example.

Návratové URL se řídí klíčem

Relace vytvořené klíčem obchodníka používají návratové URL obchodníka. Relace vytvořené pomocí Secret key organizace místo toho používají návratové cíle organizace. Tato dvě nastavení se nikdy nekombinují.

Přijetí platby

Všechny tři možnosti vytvářejí stejné relace Checkoutu se stejnými přihlašovacími údaji. Zvolte jednu; každý následující krok se řídí vaší volbou.

Nastavte svůj server

Nastavte TAPAYA_CHECKOUT_API_URL na https://api.sandbox.tapaya.com a svůj klíč uložte do TAPAYA_CHECKOUT_API_KEY. API volejte pomocí fetch v serverovém běhovém prostředí, nikdy z prohlížeče zákazníka. Příklady čtou tyto hodnoty přes process.env; pokud vaše běhové prostředí používá jiné rozhraní pro tajné údaje, toto načítání upravte.

Vytvořte pomocnou funkci, která před vrácením těla odpovědi zkontroluje chyby HTTP:

server/checkout.js

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

Vytvořte relaci

Vypočítejte celkovou částku objednávky na svém serveru, včetně daně a dopravy. Objednávku a jedinečný checkoutAttemptKey uložte před odesláním požadavku a order načtěte z tohoto uloženého stavu. Pole merchantOrderId je povinné.

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

Odpověď obsahuje id relace a hostovanou url. Souhrny položek, rozpisy daní, údaje o zákazníkovi a všechna pole odpovědi popisuje část Vytvoření relace Checkoutu.

Pokud požadavek selže nebo vyprší jeho časový limit, zopakujte jej se stejným klíčem a nezměněným tělem. Při nejistém výsledku nikdy negenerujte nový klíč: změněné tělo se stejným klíčem vrátí HTTP 409.

Možnost	Automatické opakování
HTTP (fetch), cURL	Ne. Požadavek zopakujte sami. Viz Idempotence a chyby.
Node.js SDK	Až dvakrát po chybě připojení, vypršení časového limitu nebo HTTP 429, 502, 503 či 504, se stejným klíčem a tělem. Viz Idempotence a opakované pokusy. Mezi samostatnými voláními a po restartech předávejte svůj uložený klíč: pokud jej vynecháte, vygeneruje se pro každé volání nový.

Přesměrujte zákazníka

Uložte session.id k objednávce jako její checkoutSessionId a poté pošlete prohlížeč na session.url pomocí HTTP 303. URL použijte beze změny, nesestavujte ji sami.

// First persist session.id as the order's checkoutSessionId.
return Response.redirect(session.url, 303);

Pokud váš framework používá jiné API pro odpovědi, pošlete HTTP 303 se session.url v hlavičce Location. S cURL otevřete vrácenou url v prohlížeči a platbu otestujte ručně.

Ověřte platbu

V handleru návratové URL dohledejte objednávku z autentizovaného kontextu platby ve vaší aplikaci a načtěte její uloženou relaci ze svého serveru. Udělejte to i na URL pro zrušení: návštěva kterékoli z obou URL nic nedokazuje.

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

Objednávku vyřiďte jen jednou a jen po zaplacení

Platbu zaznamenejte a objednávku vyřiďte pouze tehdy, když relace odpovídá vaší uložené objednávce a paymentStatus je successful, a zaznamenejte ji atomicky, aby k tomu došlo jen jednou. Pokud načtení selže nebo výsledek platby ještě není rozhodnutý, ponechte si ID relace a stav ověřte znovu. Viz Stav platby.

Zpracování výsledků platby

Stránka Zabezpečení Checkoutu popisuje, co ověřit a jak zopakovat požadavek s neznámým výsledkem, aniž byste vytvořili druhou relaci.

Výsledek	Co relace ukazuje	Co udělat
Zamítnutí	`open` s `paymentStatus: failed`	Nic. Zákazník může na stejné stránce zkusit jinou kartu nebo peněženku.
Zatím neznámý výsledek	`open` a `unpaid`, zatímco Tapaya potvrzuje výsledek	Načtěte relaci později znovu.
Nová relace pro stejnou objednávku	Předchozí nezaplacená relace hlásí `expired`	Použijte novou relaci. Zaplacená objednávka nebo objednávka s probíhající platbou vrátí HTTP 409. Viz Jedna platba na objednávku.
Vypršení platnosti	Přestane přijímat nové platby 30 minut po vytvoření	Pokud objednávka stále není zaplacená, vytvořte novou relaci. Platba odeslaná před vypršením se i tak dokončí.

Webhooky zatím nejsou k dispozici

Webhooky pro Checkout zatím neexistují. Spouštějte na straně serveru úlohu pro odsouhlasení, která načítá relace objednávek, jejichž zákazníci se nikdy nevrátí.