### Configurare il server [#set-up-your-server] HTTP (fetch) Node.js SDK cURL 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: ```js title="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(); } ``` Usi Node.js 22.13.0 o versioni successive e installi il pacchetto ESM sul Suo server: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` Salvi la Sua chiave in `TAPAYA_SECRET_KEY` e selezioni l'ambiente sandbox. L'SDK non carica da solo i file `.env`, quindi carichi questi valori nell'ambiente del Suo server prima di creare il client. ```sh title=".env" TAPAYA_SECRET_KEY=tapaya_test_... TAPAYA_ENVIRONMENT=sandbox ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); // reads TAPAYA_SECRET_KEY ``` Senza `TAPAYA_ENVIRONMENT`, una chiave `tapaya_live_` seleziona la produzione e le altre chiavi usano la sandbox per impostazione predefinita. In modalità piattaforma, passi il token dell'esercente: `new Tapaya(key, { merchantToken })`, oppure `merchantToken` in ogni chiamata. Se la Sua chiave è salvata con un altro nome, la passi come primo argomento. Il [riferimento del Node.js SDK](/online/integration/node_sdk) tratta URL API personalizzati, timeout, nuovi tentativi ed errori. Esegua questi comandi dal Suo server o da un terminale attendibile. Carichi la Sua chiave in `TAPAYA_CHECKOUT_API_KEY`, la tenga fuori dal codice del browser e dal sistema di controllo versione e punti l'URL dell'API alla sandbox: ```bash export TAPAYA_CHECKOUT_API_URL='https://api.sandbox.tapaya.com' ``` ### Creare una sessione [#create-a-session] 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. HTTP (fetch) Node.js SDK cURL ```js 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', }), }); ``` ```ts const session = await tapaya.checkout.sessions.create( { merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }, { idempotencyKey: order.checkoutAttemptKey }, ); ``` L'esempio addebita 121,00 EUR per `order-1001`, di cui 21,00 EUR di IVA e 6,05 EUR di spedizione, con la idempotency key salvata `order-1001-checkout-1`. Sostituisca questi valori con i dati del Suo ordine salvato. ```bash curl --request POST \ "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "tax": 2100, "shipping": 605, "taxRate": 21, "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](/online/integration/api_integration#create-a-checkout-session). **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](/online/integration/api_integration#idempotency-and-errors). | | 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](/online/integration/node_sdk#idempotency-and-retries). 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 [#redirect-the-customer] 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. ```ts // 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 [#verify-the-payment] 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. HTTP (fetch) Node.js SDK cURL ```js 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'; ``` ```ts const current = await tapaya.checkout.sessions.get(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'; ``` Carichi in `CHECKOUT_SESSION_ID` l'ID della sessione salvato con il Suo ordine: ```bash curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/$CHECKOUT_SESSION_ID" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" ``` Per l'ordine di esempio, verifichi che `id` corrisponda all'ID della sessione salvato, che `merchantOrderId` sia `order-1001`, `amount` sia `12100`, `currency` sia `EUR` e `paymentStatus` sia `successful`. Una risposta HTTP 200 da sola non prova il pagamento. 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](/online/integration/api_integration#payment-status).