### Onboarding dell'esercente [#onboard-your-merchant] Completi l'[onboarding dell'esercente](/merchants/onboarding) con la funzionalità di pagamenti online, oppure con i pagamenti online e in presenza. Un esercente che usa solo Checkout non ha bisogno di un terminale. Fornisca il sito web del negozio e i dati dell'attività online, poi attenda l'approvazione del processore di pagamento. La sola creazione di un record dell'esercente o di una chiave API non abilita i pagamenti. Apra **Checkout** nella [Tapaya Platform](https://platform.tapaya.com/checkout-settings). Gli esercenti che richiedono i pagamenti online compaiono automaticamente, compresi quelli in attesa di approvazione. Prosegua quando l'esercente è **Ready**. Apra **Settings** dell'esercente. In **Merchant API key redirects**, aggiunga il Suo negozio a **Allowed websites** e imposti gli URL predefiniti di successo e di annullamento. Una piattaforma che usa la Secret key dell'organizzazione li imposta invece in **Organization defaults**. Gli esempi usano `https://shop.example`. Per wallet e branding, consulti le [impostazioni di Checkout](/online/integration/checkout_settings). ### Salvare la chiave sul server [#store-your-key-on-the-server] In **Settings** dell'esercente, selezioni **Create merchant key** e copi la chiave `tapaya_test_…`. Viene mostrata una sola volta. La conservi solo nella configurazione lato server. Non deve mai finire nel codice del browser o nel sistema di controllo versione. ```bash title=".env" TAPAYA_ENVIRONMENT=sandbox TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com TAPAYA_SECRET_KEY=tapaya_test_... ``` L'SDK legge automaticamente `TAPAYA_SECRET_KEY` e `TAPAYA_ENVIRONMENT`. Gli esempi HTTP seguenti usano `TAPAYA_CHECKOUT_API_URL`. Carichi le variabili nel processo del Suo server; l'SDK non carica i file `.env`. Invii la chiave come `Authorization: Bearer `. Una chiave dell'esercente identifica il proprio esercente, quindi non serve nessun'altra intestazione. Una piattaforma che serve molti esercenti usa invece la Secret key dell'organizzazione e invia `X-Tapaya-Merchant-Token` in ogni richiesta. Si veda [Autenticazione di Checkout](/online/integration/api_integration#authentication). ### Creare una sessione di Checkout [#create-a-checkout-session] Quando il cliente fa clic su **Checkout** nel Suo negozio, calcoli il totale finale sul Suo server, salvi l'ordine con una chiave di tentativo univoca e crei una sessione. `merchantOrderId` è obbligatorio e un ordine può essere pagato una sola volta. Gli importi sono espressi nell'unità minima della valuta, quindi `12100` corrisponde a 121,00 EUR. Con Node.js 22.13.0 o versioni successive, installi l'SDK ESM prima di usare l'esempio **Node.js SDK**: npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` HTTP (fetch) Node.js SDK cURL ```js title="server/checkout.js" const response = await fetch( new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL), { method: 'POST', headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`, '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', }), }, ); if (!response.ok) throw new Error(`Checkout failed (${response.status})`); const session = await response.json(); ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); 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 }, ); ``` ```bash title="Terminal" curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Se la richiesta va in timeout, la ripeta con la **stessa** chiave e lo stesso corpo. L'API restituisce di nuovo la sessione originale invece di crearne una seconda. ### Reindirizzare il cliente [#redirect-the-customer] Salvi `session.id` insieme all'ordine, poi invii il browser a `session.url` con HTTP 303. Usi l'URL esattamente come viene restituito. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Tapaya mostra il riepilogo dell'ordine e il modulo di pagamento sicuro e gestisce la tokenizzazione, 3-D Secure e l'addebito. Dopo un rifiuto, il cliente può provare un'altra carta nella stessa pagina. Le sessioni accettano nuovi pagamenti per 30 minuti. ### Verificare il pagamento sul server [#verify-the-payment-on-your-server] Quando il cliente arriva sul Suo URL di successo o di annullamento, recuperi la sessione con la Sua Secret key e la confronti con l'ordine salvato. Un reindirizzamento da solo non prova mai il pagamento. HTTP (fetch) Node.js SDK ```js title="server/return.js" const response = await fetch( new URL( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, process.env.TAPAYA_CHECKOUT_API_URL, ), { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } }, ); if (!response.ok) throw new Error(`Status check failed (${response.status})`); const current = await response.json(); ``` ```ts title="server/return.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); ``` Con entrambe le integrazioni, confronti l'esito con l'ordine salvato prima di evaderlo: ```ts const matches = current.id === order.checkoutSessionId && current.merchantOrderId === order.id && current.amount === order.totalInMinorUnits && current.currency === order.currency; if (matches && current.paymentStatus === 'successful') { await fulfillOnce(order); // idempotent, safe on repeated visits } ``` Se lo stato è ancora `unpaid` o il recupero non riesce, conservi l'ID della sessione e ripeta il controllo. I webhook non sono ancora disponibili, quindi esegua un job di riconciliazione per i clienti che chiudono la scheda prima di tornare.