Ecco Tapaya Checkout

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.

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.

• 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

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.
2. Salvi l'ID della sessione sull'ordine.
3. Reindirizzi il browser a session.url con HTTP 303. Usi l'URL esattamente come viene restituito.
4. Il cliente paga sulla pagina ospitata. Una carta rifiutata può essere riprovata sulla stessa pagina. Le sessioni accettano pagamenti per 30 minuti.
5. 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:

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:

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.

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.

Dalla sandbox alla produzione

1. Registri l'esercente con la funzionalità di pagamenti online, e attenda che risulti Ready in Checkout sulla Tapaya Platform.
2. Aggiunga il Suo negozio agli Allowed websites e imposti gli URL predefiniti di successo e di annullamento.
3. Sviluppi nella sandbox con una chiave tapaya_test_, conservata solo sul Suo server.
4. Passi alla produzione: una chiave di produzione, TAPAYA_ENVIRONMENT=production e URL di ritorno di produzione.
5. 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, crei una chiave sandbox e accetti oggi stesso il Suo primo pagamento di test. Domande sulla Sua integrazione? Scriva a developers@tapaya.com.