Hosted Checkout

Vytvorte reláciu Checkoutu, presmerujte zákazníka a overte platbu zo svojho servera.

Pošlite zákazníka na platobnú stránku hostovanú spoločnosťou Tapaya pre karty, Apple Pay a Google Pay a potom overte výsledok na svojom serveri. Vaša stránka nikdy nepracuje s údajmi o karte a do svojho obchodu nepridávate žiadne polia pre 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.

Skôr ako začnete

Zvoľte kľúč podľa toho, kto prevádzkuje váš backend. Nech zvolíte ktorýkoľvek, uchovávajte ho na svojom serveri; pravidlá na strane servera uvádza stránka Zabezpečenie Checkoutu.

Jeden obchod

Použite checkout kľúč obchodníka. Určuje svojho obchodníka a používajú ho aj tunajšie príklady.

Mnoho obchodníkov

Použite Secret key organizácie a s každou požiadavkou posielajte token obchodníka.

Potom v časti Checkout v Tapaya Platform:

Pridajte svojho obchodníka a overte, že sa zobrazuje ako Ready. Pozrite si Nastavenia Checkoutu.
Zaregistrujte svoj obchod ako povolený web s predvolenými URL úspechu a zrušenia, a to pre kľúč, ktorý ste zvolili. Príklady používajú https://shop.example.

Návratové URL sa riadia kľúčom

Relácie vytvorené kľúčom obchodníka používajú návratové URL obchodníka. Relácie vytvorené pomocou Secret key organizácie namiesto toho používajú návratové ciele organizácie. Tieto dve nastavenia sa nikdy nekombinujú.

Prijatie platby

Všetky tri možnosti vytvárajú rovnaké relácie Checkoutu s rovnakými prihlasovacími údajmi. Zvoľte jednu; každý nasledujúci krok sa riadi vašou voľbou.

Nastavte svoj server

Nastavte TAPAYA_CHECKOUT_API_URL na https://api.sandbox.tapaya.com a svoj kľúč uložte do TAPAYA_CHECKOUT_API_KEY. API volajte pomocou fetch v serverovom behovom prostredí, nikdy z prehliadača zákazníka. Príklady čítajú tieto hodnoty cez process.env; ak vaše behové prostredie používa iné rozhranie pre tajné údaje, toto načítanie upravte.

Vytvorte pomocnú funkciu, ktorá pred vrátením tela odpovede skontroluje 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();
}

Vytvorte reláciu

Vypočítajte celkovú sumu objednávky na svojom serveri vrátane dane a dopravy. Objednávku a jedinečný checkoutAttemptKey uložte pred odoslaním požiadavky a order načítajte z tejto uloženej snímky. 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',
	}),
});

Odpoveď obsahuje id relácie a hostovanú url. Súhrny položiek, rozpisy daní, údaje o zákazníkovi a všetky polia odpovede opisuje časť Vytvorenie relácie Checkoutu.

Ak požiadavka zlyhá alebo vyprší jej časový limit, zopakujte ju s rovnakým kľúčom a nezmeneným telom. Pri neistom výsledku nikdy negenerujte nový kľúč: zmenené telo s rovnakým kľúčom vráti HTTP 409.

Možnosť	Automatické opakovanie
HTTP (fetch), cURL	Nie. Požiadavku zopakujte sami. Pozrite si Idempotencia a chyby.
Node.js SDK	Až dvakrát po chybe pripojenia, vypršaní časového limitu alebo HTTP 429, 502, 503 či 504, s rovnakým kľúčom a telom. Pozrite si Idempotencia a opakovanie požiadaviek. Medzi samostatnými volaniami alebo po reštartoch odovzdávajte svoj uložený kľúč: ak ho vynecháte, pre každé volanie sa vygeneruje nový.

Presmerujte zákazníka

Uložte session.id k objednávke ako jej checkoutSessionId a potom pošlite prehliadač na session.url pomocou HTTP 303. URL použite bez zmeny, nezostavujte ju sami.

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

Ak váš framework používa iné API pre odpovede, pošlite HTTP 303 so session.url v hlavičke Location. S cURL otvorte vrátenú url v prehliadači a platbu otestujte ručne.

Overte platbu

V handleri návratovej URL dohľadajte objednávku z autentifikovaného kontextu pokladne vo vašej aplikácii a načítajte jej uloženú reláciu zo svojho servera. Urobte to aj na URL zrušenia: návšteva ktorejkoľvek z oboch URL nič 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 vybavte iba raz a iba po zaplatení

Platbu zaznamenajte a objednávku vybavte iba vtedy, keď relácia zodpovedá vašej uloženej objednávke a paymentStatus je successful, a zaznamenajte ju atomicky, aby k tomu došlo iba raz. Ak načítanie zlyhá alebo výsledok platby ešte nie je rozhodnutý, ponechajte si ID relácie a stav overte znova. Pozrite si Stav platby.

Spracovanie výsledkov platby

Stránka Zabezpečenie Checkoutu opisuje, čo overiť a ako zopakovať požiadavku s neznámym výsledkom bez toho, aby ste vytvorili druhú reláciu.

Výsledok	Čo relácia ukazuje	Čo urobiť
Zamietnutie	`open` s `paymentStatus: failed`	Nič. Zákazník môže na tej istej stránke skúsiť inú kartu alebo peňaženku.
Zatiaľ neznámy výsledok	`open` a `unpaid`, kým Tapaya potvrdzuje výsledok	Načítajte reláciu neskôr znova.
Nová relácia pre tú istú objednávku	Predchádzajúca nezaplatená relácia hlási `expired`	Použite novú reláciu. Zaplatená objednávka alebo objednávka s prebiehajúcou platbou vráti HTTP 409. Pozrite si Jedna platba na objednávku.
Vypršanie platnosti	Prestane prijímať nové platby 30 minút po vytvorení	Ak objednávka stále nie je zaplatená, vytvorte novú reláciu. Platba odoslaná pred vypršaním sa aj tak dokončí.

Webhooky zatiaľ nie sú k dispozícii

Webhooky pre Checkout zatiaľ neexistujú. Spúšťajte na strane servera úlohu na odsúhlasenie, ktorá načítava relácie objednávok, ktorých zákazníci sa nikdy nevrátia.