Guida rapida

Onboarding dell'esercente

Completi l'onboarding dell'esercente 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. 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.

Salvare la chiave sul 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.

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 <key>. 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.

Creare una sessione di Checkout

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 install @tapayadot/checkout

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

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

Salvi session.id insieme all'ordine, poi invii il browser a session.url con HTTP 303. Usi l'URL esattamente come viene restituito.

// 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

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.

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

Con entrambe le integrazioni, confronti l'esito con l'ordine salvato prima di evaderlo:

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.