Hosted Checkout

Crei una sessione di checkout, reindirizzi il cliente e verifichi il pagamento dal Suo server.

Invii il cliente a una pagina di pagamento ospitata da Tapaya per carte, Apple Pay e Google Pay, poi verifichi l'esito sul Suo server. La Sua pagina non gestisce mai i dati della carta e Lei non aggiunge alcun campo della carta al Suo negozio.

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.

Prima di iniziare

Scelga la chiave in base a chi gestisce il Suo backend. In entrambi i casi conservi la chiave sul Suo server; Sicurezza di Checkout elenca le regole lato server.

Un solo negozio

Usi una chiave checkout dell'esercente. Identifica il proprio esercente ed è quella usata negli esempi di questa pagina.

Molti esercenti

Usi la Secret key dell'organizzazione e invii un token dell'esercente con ogni richiesta.

Poi, in Checkout nella Tapaya Platform:

Aggiunga il Suo esercente e verifichi che mostri Ready. Si veda Impostazioni di Checkout.
Registri il Suo negozio come sito web consentito, con gli URL predefiniti di successo e di annullamento, per la chiave scelta. Gli esempi usano https://shop.example.

Gli URL di ritorno seguono la chiave

Le sessioni create con una chiave dell'esercente usano gli URL di ritorno dell'esercente. Le sessioni create con la Secret key dell'organizzazione usano invece le destinazioni di ritorno dell'organizzazione. Le due configurazioni non vengono mai combinate.

Accettare un pagamento

Tutte e tre le opzioni creano le stesse sessioni di Checkout con le stesse credenziali. Ne scelga una; ogni passaggio seguente si adatta alla Sua scelta.

Configurare il server

Imposti TAPAYA_CHECKOUT_API_URL su https://api.sandbox.tapaya.com e salvi la Sua chiave in TAPAYA_CHECKOUT_API_KEY. Chiami l'API con il fetch del Suo runtime server, mai dal browser del cliente. Gli esempi leggono questi valori tramite process.env; adatti questa lettura se il Suo runtime usa un'interfaccia diversa per i segreti.

Crei una funzione di supporto che controlli gli errori HTTP prima di restituire il corpo della risposta:

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

Creare una sessione

Calcoli il totale dell'ordine sul Suo server, imposte e spedizione comprese. Salvi l'ordine e un checkoutAttemptKey univoco prima di inviare la richiesta e carichi order da quello snapshot salvato. merchantOrderId è obbligatorio.

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

La risposta contiene l'id della sessione e l'url della pagina ospitata. Per riepiloghi degli articoli, ripartizioni delle imposte, dati del cliente e tutti i campi della risposta, si veda Creare una sessione di Checkout.

Se la richiesta non riesce o va in timeout, la ripeta con la stessa chiave e un corpo invariato. Non generi mai una nuova chiave per un esito incerto: un corpo modificato con la stessa chiave restituisce HTTP 409.

Opzione	Nuovi tentativi automatici
HTTP (fetch), cURL	No. Ripeta manualmente la richiesta. Si veda Idempotenza ed errori.
Node.js SDK	Fino a due volte dopo un errore di connessione, un timeout o un HTTP 429, 502, 503 o 504, con la stessa chiave e lo stesso corpo. Si veda Idempotenza e nuovi tentativi. Tra chiamate separate o dopo un riavvio, passi la chiave salvata: se la omette, ne viene generata una nuova a ogni chiamata.

Reindirizzare il cliente

Salvi session.id insieme all'ordine come suo checkoutSessionId, poi invii il browser a session.url con HTTP 303. Usi l'URL invariato invece di costruirlo.

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

Se il Suo framework usa un'API di risposta diversa, invii HTTP 303 con session.url nell'intestazione Location. Con cURL, apra l'url restituito nel browser per testare il pagamento manualmente.

Verificare il pagamento

Nel Suo handler di ritorno, individui l'ordine dal contesto di checkout autenticato della Sua applicazione e recuperi la sessione salvata dal Suo server. Lo faccia anche sull'URL di annullamento: una visita a uno qualsiasi dei due URL non prova nulla.

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

Evadere una sola volta, e solo se pagato

Registri il pagamento ed evada l'ordine solo quando la sessione corrisponde all'ordine salvato e paymentStatus è successful, e lo registri in modo atomico così che avvenga una sola volta. Se il recupero non riesce o il pagamento è in sospeso, conservi l'ID della sessione e ripeta il controllo. Si veda Stato del pagamento.

Gestire gli esiti dei pagamenti

Sicurezza di Checkout spiega cosa verificare e come ripetere una richiesta con esito sconosciuto senza creare una seconda sessione.

Esito	Cosa mostra la sessione	Cosa fare
Rifiutato	`open`, con `paymentStatus: failed`	Nulla. Il cliente può provare un'altra carta o un altro wallet nella stessa pagina.
Non ancora noto	`open` e `unpaid` mentre Tapaya conferma l'esito	Recuperi di nuovo la sessione più tardi.
Nuova sessione per lo stesso ordine	La sessione precedente non pagata riporta `expired`	Usi la nuova sessione. Un ordine pagato, o con un pagamento in corso, restituisce HTTP 409. Si veda Un pagamento per ordine.
Scaduta	Smette di accettare nuovi pagamenti 30 minuti dopo la creazione	Crei una nuova sessione se l'ordine non è ancora pagato. Un pagamento inviato prima della scadenza viene comunque completato.

Webhook non ancora disponibili

I webhook di Checkout non sono ancora disponibili. Esegua lato server un job di riconciliazione che recuperi le sessioni degli ordini i cui clienti non tornano mai.