--- title: "Ecco Tapaya Checkout" description: "Carte, Apple Pay e Google Pay con un'unica API. Reindirizzi i clienti a una pagina di pagamento ospitata, oppure integri campi carta sicuri nel Suo checkout. Ecco come funziona ciascuna opzione e come scegliere." url: "https://tapaya.com/it/blog/introducing-tapaya-checkout-it" lang: "it" last_updated: "2026-11-13" --- # Ecco Tapaya Checkout > Carte, Apple Pay e Google Pay con un'unica API. Reindirizzi i clienti a una pagina di pagamento ospitata, oppure integri campi carta sicuri nel Suo checkout. Ecco come funziona ciascuna opzione e come scegliere. Con Tapaya Checkout arrivano su Tapaya i pagamenti online. I Suoi esercenti possono accettare carte, Apple Pay e Google Pay su qualsiasi sito web, e Lei sceglie quanta parte del checkout gestire in prima persona. - **Hosted Checkout.** Il Suo server crea una sessione e reindirizza il cliente a una pagina di pagamento sicura ospitata da Tapaya. Richiede pochissimo lavoro sul front-end. - **Embedded Checkout.** Campi carta sicuri e pulsanti dei wallet si trovano direttamente nella Sua pagina di checkout, accanto al Suo pulsante Paga. Entrambi usano lo stesso modello lato server: creare, reindirizzare o integrare, e poi verificare sul Suo server prima di evadere l'ordine. Può iniziare già oggi nella sandbox su [docs.tapaya.com](https://docs.tapaya.com). {% youtube #PejafWaMx24 title="Introducing Tapaya Checkout: New way to payments online" poster="/images/posts/introducing-tapaya-checkout-video-poster.jpg" /%} ## Che cos'è Tapaya Checkout Tapaya Checkout è la parte online di Tapaya. Accetta per i Suoi esercenti pagamenti con carta, Apple Pay e Google Pay, tramite un'unica API e un unico SDK Node.js. L'idea è la stessa dei pagamenti in negozio: Lei integra una volta, l'esperienza dell'esercente resta nel Suo prodotto e Tapaya gestisce dietro le quinte tutta la complessità dei pagamenti. ![Tapaya Checkout in sintesi: carte, Apple Pay e Google Pay, 3-D Secure integrato, nessun pagamento duplicato, nuovi tentativi automatici, dati della carta che non toccano mai la Sua pagina, un'unica API e un unico SDK per Hosted ed Embedded Checkout](/images/posts/introducing-tapaya-checkout-at-a-glance.jpg) - **Hosted Checkout** Le offre una pagina di pagamento pronta all'uso sul dominio di Tapaya, su desktop e su mobile. - **Embedded Checkout** Le offre campi sicuri da integrare nella Sua pagina. I dati della carta restano nel frame (iframe) di Tapaya e non raggiungono mai la Sua pagina. Entrambi si basano sugli stessi elementi: una chiave lato server, importi nell'unità minima della valuta (quindi `1880` significa 18,80 EUR), richieste idempotenti e verifica lato server. Una volta costruito uno, conosce già gran parte dell'altro. ## Hosted o Embedded: quale scegliere ![Embedded Checkout mantiene i clienti sulla Sua pagina di checkout. Hosted Checkout li porta su una pagina sicura ospitata da Tapaya.](/images/posts/introducing-tapaya-checkout-embedded-vs-hosted.jpg) {% table %} -   - Hosted Checkout - Embedded Checkout --- - **Dove paga il cliente** - Su una pagina ospitata da Tapaya, poi torna al Suo negozio - Direttamente nella Sua pagina di checkout --- - **Lavoro sul front-end** - Un reindirizzamento - Integrare i campi, gestire `submit()` e lo stato --- - **Pulsante Paga** - Sulla pagina di Tapaya - Il Suo pulsante --- - **Apple Pay e Google Pay** - Sulla pagina ospitata - Visualizzati nel frame di Tapaya accanto ai campi carta --- - **3-D Secure** - Gestito sulla pagina ospitata - Gestito dentro `submit()`, nel frame di Tapaya --- - **Ideale per** - Andare live in fretta, negozi semplici, piattaforme con molti esercenti - Team che vogliono il pieno controllo dell'esperienza di checkout {% /table %} Se non è sicuro, inizi con Hosted Checkout. Passare in seguito a Embedded riutilizza le stesse chiavi, lo stesso modello di ordine e la stessa logica di verifica. ## Hosted Checkout in cinque passaggi 1. **Crei una sessione sul Suo server.** Chiami `POST /merchant/checkout-sessions` con `merchantOrderId`, `amount` (nell'unità minima), `currency`, `customer`, `successUrl` e `cancelUrl`. Invii un header `Idempotency-Key`. 1. **Salvi l'ID della sessione** sull'ordine. 1. **Reindirizzi il browser** a `session.url` con HTTP 303. Usi l'URL esattamente come viene restituito. 1. **Il cliente paga sulla pagina ospitata.** Una carta rifiutata può essere riprovata sulla stessa pagina. Le sessioni accettano pagamenti per 30 minuti. 1. **Verifichi sul Suo server.** Quando il cliente torna su uno dei due URL di ritorno, chiami `GET /merchant/checkout-sessions/{id}`. Controlli che ID, ID dell'ordine, importo e valuta corrispondano al Suo ordine, ed evada l'ordine solo quando `paymentStatus` è `successful`. Con l'SDK Node.js (`npm install @tapayadot/checkout`, Node.js 22.13.0 o successivo), il nucleo è questo: ```typescript import { Tapaya } from '@tapayadot/checkout' // Reads TAPAYA_SECRET_KEY from the server environment. const tapaya = new Tapaya() // 1–3. Create the session and redirect the customer const session = await tapaya.checkout.sessions.create(params, { idempotencyKey }) return Response.redirect(session.url, 303) // 5. Later, on the return URL: verify before you fulfil const current = await tapaya.checkout.sessions.get(sessionId) ``` Tutti i parametri si trovano nel tipo `CreateHostedCheckoutSessionParams` e nella guida a Hosted Checkout. ## Embedded Checkout: campi sicuri nella Sua pagina Embedded Checkout divide il lavoro tra la Sua pagina e un piccolo endpoint `prepare` sul Suo server. Nel browser carica Tapaya da `@tapayadot/checkout/client` e integra i campi: ```typescript import { loadTapaya } from '@tapayadot/checkout/client' const tapaya = await loadTapaya(publishableKey, { apiOrigin }) const payment = tapaya.createPayment({ prepare: '/api/payments', // your server endpoint wallets: { amount: 1880, currency: 'EUR' }, onChange: (snapshot) => { /* enable Pay when snapshot.canSubmit */ }, }) payment.mount('#card-fields') // In your form handler: await payment.submit() // validates, runs 3-D Secure, confirms ``` Sul Suo server, l'endpoint `prepare` carica l'ordine e riutilizza un pagamento esistente, se c'è. Altrimenti ne crea uno con `POST /merchant/payments` e una chiave di idempotenza. Poi restituisce `{ clientSecret, status }`. Le app React possono usare `usePayment()` da `@tapayadot/checkout/react`. Alcune cose da sapere: - Aggiunga `https://js.tapaya.com` a `script-src` e `frame-src` nella Sua Content Security Policy. - Importi `@tapayadot/checkout` solo sul server. Il browser usa il punto di ingresso `/client`. - `snapshot.outcome` Le dice cosa mostrare: `open`, `pending`, `completed` o `ended`. - I pulsanti dei wallet compaiono solo dove sono supportati e attivati. Apple Pay richiede un dominio del negozio attivo, e Google Pay in produzione richiede un merchant ID. Il flusso completo è nella guida a Embedded Checkout. ## Pensato per integrazioni affidabili I pagamenti falliscono in modi disordinati: un timeout, un cliente che chiude la scheda, un nuovo tentativo che arriva due volte. Tapaya Checkout è costruito perché Lei possa gestire ciascuno di questi casi. - **Chiavi di idempotenza su ogni creazione.** Riprovi con la stessa chiave e lo stesso body e riceve la sessione o il pagamento originale. Un body modificato restituisce HTTP 409. - **Nuovi tentativi integrati nell'SDK Node.js.** Per impostazione predefinita ritenta due volte in caso di errori di connessione, timeout e HTTP 429, 502, 503 e 504, con un backoff a intervalli casuali (jitter). - **Un pagamento per ordine.** Una nuova sessione per lo stesso ordine fa scadere la precedente. Un ordine pagato, o con un pagamento in corso, viene rifiutato. - **Webhook più polling.** Si iscriva agli eventi delle sessioni di checkout e continui a controllare le sessioni non risolte come soluzione di riserva. - **Prima verificare, poi evadere, una sola volta.** Una visita al Suo URL di successo non prova nulla da sola. Confermi sempre lo stato sul Suo server e registri l'evasione dell'ordine in modo atomico. Prima di andare live, provi ogni esito con le carte di test della sandbox e completi la checklist di QA. ## Sviluppi più in fretta con il server MCP della documentazione Tapaya La documentazione di Tapaya ha un proprio server MCP. I Suoi strumenti di sviluppo con AI possono cercare nelle guide e consultare gli endpoint dell'API mentre sviluppa, senza lasciare l'editor. Funziona con Claude Code, Claude Desktop, Cursor, VS Code, Codex e qualsiasi altro client MCP. È pubblico e non richiede una chiave API. ```bash claude mcp add --transport http tapaya-docs https://docs.tapaya.com/mcp ``` Non chiama mai l'API Tapaya di produzione e non chiede mai chiavi. La configurazione per ogni client è in [MCP Setup](https://docs.tapaya.com/mcp-server). ## Dalla sandbox alla produzione 1. **Registri l'esercente** con la funzionalità di pagamenti online, e attenda che risulti Ready in Checkout sulla Tapaya Platform. 1. **Aggiunga il Suo negozio** agli Allowed websites e imposti gli URL predefiniti di successo e di annullamento. 1. **Sviluppi nella sandbox** con una chiave `tapaya_test_`, conservata solo sul Suo server. 1. **Passi alla produzione:** una chiave di produzione, `TAPAYA_ENVIRONMENT=production` e URL di ritorno di produzione. 1. **Configuri i wallet per la produzione:** il dominio del negozio per Apple Pay e il merchant ID per Google Pay. La guida Quick Start La porta da zero a un primo pagamento in sandbox con poche chiamate al server. ## Domande frequenti ### Quali metodi di pagamento supporta Tapaya Checkout? Carte, Apple Pay e Google Pay, sia con Hosted sia con Embedded Checkout. ### I dati della carta passano dal mio server o dalla mia pagina? No. Con Hosted Checkout il cliente paga sulla pagina di Tapaya. Con Embedded Checkout i campi carta e 3-D Secure funzionano dentro il frame di Tapaya, e i dati della carta non raggiungono mai la Sua pagina. ### Per quanto tempo è valida una sessione di Hosted Checkout? 30 minuti dalla creazione. Un pagamento inviato prima di quel termine viene comunque completato. Se l'ordine risulta ancora non pagato dopo, crei una nuova sessione. ### Esiste un SDK? Sì, `@tapayadot/checkout` per Node.js 22.13.0 o successivo. Copre Hosted Checkout sul server, più i punti di ingresso per browser e React per Embedded Checkout. Altri stack possono chiamare direttamente la REST API. ### Le piattaforme possono accettare pagamenti per molti esercenti? Sì. Usi la Secret key dell'organizzazione e invii un token dell'esercente con ogni richiesta. ## Per iniziare Legga la panoramica Online Payments su [docs.tapaya.com](https://docs.tapaya.com), crei una chiave sandbox e accetti oggi stesso il Suo primo pagamento di test. Domande sulla Sua integrazione? Scriva a [developers@tapaya.com](mailto:developers@tapaya.com). ## Sitemap - [Sitemap](https://tapaya.com/sitemap.md): every page on tapaya.com, as markdown links