Overlay Checkout

Il checkout overlay apre una finestra modale sopra la tua pagina. I clienti inseriscono i dati di pagamento nella modale mentre la tua pagina rimane visibile sullo sfondo. Quando chiudono la modale, il controllo torna alla tua pagina. Quando completano il pagamento, vengono reindirizzati a return_url.

Modale del checkout overlay visualizzata sopra una pagina prodotto

Interactive Demo

Guarda il checkout overlay in azione con la nostra demo live.

Avvio rapido

Installa l’SDK, inizializzalo e apri il checkout con un URL di checkout dall’API per la creazione di una sessione di checkout:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

Integrazione passo dopo passo

Install the SDK

Installa tramite npm, yarn o pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Chiama Initialize una volta quando l’app viene caricata, in genere nel componente principale o nel punto di ingresso dell’app:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Inizializza sempre l’SDK prima di aprire il checkout. Inizializzalo una volta quando l’applicazione viene caricata, non prima di ogni tentativo di checkout.

Create a Checkout Button

Crea un componente che apra la modale del checkout:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add the Button to Your Page

Usa il componente del pulsante di checkout nella tua applicazione:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Redirects

Crea pagine per gestire i reindirizzamenti del checkout dopo il pagamento:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

Avvia il server di sviluppo:

npm run dev

Testa il flusso di checkout:
- Fai clic sul pulsante di checkout
- Verifica che la modale venga visualizzata
- Testa il flusso di pagamento utilizzando le credenziali di test
- Conferma che i reindirizzamenti funzionino correttamente

Dovresti vedere gli eventi del checkout registrati nella console del browser.

Go Live

Quando sei pronto per la produzione:

Modifica la modalità in 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Aggiorna gli URL di checkout per utilizzare sessioni di checkout live dal tuo backend
Testa l’intero flusso in produzione
Monitora eventi ed errori

Riferimento API

Inizializzazione

Chiama Initialize una volta per configurare l’SDK:

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

DodoPayments.Initialize(options);

Opzione	Tipo	Obbligatorio	Descrizione
`mode`	`"test" \| "live"`	Sì	Modalità dell’ambiente: `"test"` per lo sviluppo, `"live"` per la produzione
`displayType`	`"overlay" \| "inline"`	No	Tipo di visualizzazione: `"overlay"` per il checkout modale (predefinito), `"inline"` per il checkout incorporato
`onEvent`	`function`	Sì	Funzione callback per la gestione degli eventi del checkout

Apertura del checkout

Apri la modale del checkout:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Opzione	Tipo	Obbligatorio	Descrizione
`checkoutUrl`	`string`	Sì	URL della sessione di checkout dall’API per la creazione di una sessione di checkout
`options.showTimer`	`boolean`	No	Mostra o nasconde il timer della sessione. Il valore predefinito è `true`. Quando è disabilitato, ricevi l’evento `checkout.link_expired` alla scadenza della sessione.
`options.showSecurityBadge`	`boolean`	No	Mostra o nasconde il badge di sicurezza. Il valore predefinito è `true`
`options.manualRedirect`	`boolean`	No	Quando `true`, impedisce i reindirizzamenti automatici. Il checkout emette `checkout.status` con l’esito del pagamento e `checkout.redirect_requested` con l’URL da aprire; la navigazione viene gestita da te
`options.themeConfig`	`ThemeConfig`	No	Deprecato. Configura invece il tema lato server durante la creazione della sessione di checkout
`options.payButtonText`	`string`	No	Testo personalizzato per il pulsante di pagamento
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	No	Dimensione globale del carattere per il checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	No	Peso globale del carattere per il checkout

Chiusura del checkout

Chiudi la modale programmaticamente:

DodoPayments.Checkout.close();

Verifica dello stato

Verifica se la modale è attualmente aperta:

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Eventi

Ascolta gli eventi del checkout tramite il callback onEvent passato a Initialize:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Evento	Descrizione
`checkout.opened`	La modale è stata aperta
`checkout.form_ready`	Il modulo è pronto per l’input dell’utente. Usalo per nascondere gli stati di caricamento
`checkout.payment_page_opened`	La pagina di pagamento è visualizzata
`checkout.customer_details_submitted`	Dati del cliente e di fatturazione inviati
`checkout.closed`	La modale è stata chiusa
`checkout.redirect`	Il checkout verrà reindirizzato, ad esempio a una pagina bancaria
`checkout.error`	Si è verificato un errore durante il checkout
`checkout.link_expired`	La sessione di checkout è scaduta. Ricevuto solo quando `showTimer` è impostato su `false`.

Implementazione CDN

Per una rapida integrazione senza una fase di build, carica l’SDK dal CDN:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dodo Payments Checkout</title>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        console.log('Checkout event:', event);
      }
    });
  </script>
</head>
<body>
  <button onclick="openCheckout()">Checkout Now</button>

  <script>
    function openCheckout() {
      DodoPaymentsCheckout.DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Personalizzazione del tema

L’opzione themeConfig lato client è deprecata e verrà rimossa nella prossima versione principale dell’Checkout SDK (v2.0.0). Passandola, viene registrato un avviso di deprecazione nella console del browser. Configura invece il tema quando crei la sessione di checkout tramite l’API, utilizzando il parametro customization.theme_config — consulta Personalizzazione del tema del checkout — oppure visivamente nella pagina Design della dashboard. I temi configurati nella sessione si applicano al checkout overlay, inline e hosted.

Questa sezione descrive la configurazione del tema lato client deprecata tramite Checkout SDK. L’approccio consigliato consiste nel configurare i temi lato server durante la creazione di una sessione di checkout tramite l’API, utilizzando il parametro theme_config. Consulta Personalizzazione del tema del checkout per la configurazione a livello API oppure usa la pagina Design della dashboard per configurare visivamente i temi con un’anteprima live.

Se devi utilizzare la configurazione del tema lato client, passa themeConfig nel parametro options:

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Proprietà del tema

Tutte le proprietà del tema disponibili per le modalità chiara e scura:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Gestione degli errori

Implementa sempre la gestione degli errori nel callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

Gestisci sempre l’evento checkout.error per offrire una buona esperienza utente quando si verificano errori.

Best practice

Inizializza una volta: chiama Initialize una volta quando l’app viene caricata, non prima di ogni checkout
Gestione degli errori: implementa una corretta gestione degli errori nel callback degli eventi
Modalità di test: usa la modalità "test" durante lo sviluppo e passa a "live" solo quando sei pronto per la produzione
Gestione degli eventi: gestisci tutti gli eventi pertinenti per un’esperienza utente completa
URL validi: usa sempre URL di checkout validi dall’API per la creazione di una sessione di checkout
TypeScript: usa TypeScript per una migliore sicurezza dei tipi e un’esperienza di sviluppo migliore
Stati di caricamento: mostra gli stati di caricamento durante l’apertura del checkout per migliorare l’UX
Gestione del timer: disabilita il timer (showTimer: false) se vuoi gestire manualmente la scadenza della sessione

Risoluzione dei problemi

Events not firing

Possibili cause:

Gestore degli eventi non configurato correttamente
Errori JavaScript che impediscono la propagazione degli eventi
SDK non inizializzato correttamente

Soluzioni:

Conferma che il gestore degli eventi sia configurato correttamente in Initialize()
Controlla la console del browser per individuare errori JavaScript
Verifica che l’inizializzazione dell’SDK sia stata completata correttamente
Esegui prima un test con un semplice gestore degli eventi

Styling issues

Possibili cause:

Conflitti CSS con gli stili dell’applicazione
Impostazioni del tema non applicate correttamente
Problemi di responsive design

Soluzioni:

Controlla la presenza di conflitti CSS nei DevTools del browser
Verifica che le impostazioni del tema siano corrette
Esegui test su diverse dimensioni dello schermo
Assicurati che non vi siano conflitti di z-index con la modale

Portafogli digitali

Per informazioni dettagliate sulla configurazione di Google Pay e di altri portafogli digitali, consulta la pagina Portafogli digitali.

Apple Pay non è ancora supportato nel checkout overlay.

Supporto dei browser

Il Checkout SDK di Dodo Payments supporta:

Chrome (ultima versione)
Firefox (ultima versione)
Safari (ultima versione)
Edge (ultima versione)
IE11+

Checkout overlay vs inline

Scegli il tipo di checkout più adatto al tuo caso d’uso:

Funzionalità	Overlay	Inline
Profondità dell’integrazione	Modale sopra la pagina	Completamente incorporato nella pagina
Controllo del layout	Limitato	Completo
Branding	Separato dalla pagina	Corrisponde alla tua pagina
Impegno di implementazione	Minore	Maggiore
Ideale per	Integrazione rapida, pagine esistenti	Pagine di checkout personalizzate, flussi ad alta conversione

Usa il checkout overlay per un’integrazione più rapida con modifiche minime alle pagine esistenti. Usa il checkout inline quando vuoi il massimo controllo sull’esperienza di checkout e un branding coerente.

Risorse correlate

Inline Checkout

Incorpora il checkout direttamente nella tua pagina per esperienze completamente integrate.

Checkout Sessions API

Crea sessioni di checkout per alimentare le tue esperienze di checkout.

Webhooks

Gestisci gli eventi di pagamento lato server con i webhook.

Integration Guide

Guida completa all’integrazione di Dodo Payments.

Per ulteriore assistenza, visita la nostra community Discord o contatta il nostro team di supporto per sviluppatori.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Avvio rapido

Integrazione passo dopo passo

Riferimento API

Inizializzazione

Apertura del checkout

Chiusura del checkout

Verifica dello stato

Eventi

Implementazione CDN

Personalizzazione del tema

Proprietà del tema

Gestione degli errori

Best practice

Risoluzione dei problemi

Portafogli digitali

Supporto dei browser

Checkout overlay vs inline

Risorse correlate

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Avvio rapido

​Integrazione passo dopo passo

​Riferimento API

​Inizializzazione

​Apertura del checkout

​Chiusura del checkout

​Verifica dello stato

​Eventi

​Implementazione CDN

​Personalizzazione del tema

​Proprietà del tema

​Gestione degli errori

​Best practice

​Risoluzione dei problemi

​Portafogli digitali

​Supporto dei browser

​Checkout overlay vs inline

​Risorse correlate

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Avvio rapido

Integrazione passo dopo passo

Riferimento API

Inizializzazione

Apertura del checkout

Chiusura del checkout

Verifica dello stato

Eventi

Implementazione CDN

Personalizzazione del tema

Proprietà del tema

Gestione degli errori

Best practice

Risoluzione dei problemi

Portafogli digitali

Supporto dei browser

Checkout overlay vs inline

Risorse correlate