Overlay Checkout

Panoramica

Il Dodo Payments Checkout SDK fornisce un modo fluido per integrare il nostro overlay di pagamento nella tua applicazione web. Costruito con TypeScript e standard web moderni, offre una soluzione robusta per gestire i pagamenti con gestione degli eventi in tempo reale e temi personalizzabili.

Immagine di copertina del checkout sovrapposto

Demo

Interactive Demo

Guarda il checkout sovrapposto in azione con la nostra demo dal vivo.

Inizio rapido

Inizia con il Dodo Payments Checkout SDK in poche righe di codice:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

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

Ottieni l’URL del tuo checkout dall’API di creazione della sessione di checkout.

Guida all’integrazione passo-passo

Install the SDK

Installa il Dodo Payments Checkout SDK utilizzando il tuo gestore di pacchetti preferito:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Inizializza l’SDK nella tua applicazione, tipicamente nel tuo 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", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Inizializza sempre l’SDK prima di cercare di aprire il checkout. L’inizializzazione dovrebbe avvenire una sola volta quando la tua applicazione viene caricata.

Create a Checkout Button Component

Crea un componente che apre l’overlay di 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(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://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 Checkout to Your Page

Usa il componente 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 Success and Failure Pages

Crea pagine per gestire i reindirizzamenti del checkout:

// 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 tuo server di sviluppo:

npm run dev

Testa il flusso di checkout:
- Clicca sul pulsante di checkout
- Verifica che l’overlay appaia
- Testa il flusso di pagamento utilizzando 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:

Cambia la modalità in 'live':

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

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

Riferimento API

Configurazione

Opzioni di inizializzazione

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

Opzione	Tipo	Richiesto	Descrizione
`mode`	`"test" \| "live"`	Sì	Modalità 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 di callback per gestire gli eventi del checkout

Opzioni di checkout

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}

Opzione	Tipo	Richiesto	Descrizione
`checkoutUrl`	`string`	Sì	URL della sessione di checkout dall’API di creazione della sessione di checkout
`options.showTimer`	`boolean`	No	Mostra o nasconde il timer del checkout. Il valore predefinito è `true`. Quando disabilitato, riceverai l’evento `checkout.link_expired` quando la sessione scade.
`options.showSecurityBadge`	`boolean`	No	Mostra o nasconde il badge di sicurezza. Il valore predefinito è `true`.
`options.manualRedirect`	`boolean`	No	Quando abilitato, il checkout non reindirizzerà automaticamente dopo il completamento. Riceverai invece gli eventi `checkout.status` e `checkout.redirect_requested` per gestire tu stesso il reindirizzamento.

Metodi

Apri Checkout

Apre l’overlay di checkout con l’URL della sessione di checkout specificato.

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

Puoi anche passare opzioni aggiuntive per personalizzare il comportamento del checkout:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});

Quando utilizzi manualRedirect, gestisci il completamento del checkout nella tua callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Chiudi Checkout

Chiude programmaticamente l’overlay di checkout.

DodoPayments.Checkout.close();

Controlla Stato

Restituisce se l’overlay di checkout è attualmente aperto.

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

Eventi

L’SDK fornisce eventi in tempo reale ai quali puoi ascoltare tramite la callback onEvent:

Dati Evento Stato Checkout

Quando manualRedirect è abilitato, ricevi l’evento checkout.status con i seguenti dati:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Dati Evento Reindirizzamento Checkout Richiesto

Quando manualRedirect è abilitato, ricevi l’evento checkout.redirect_requested con i seguenti dati:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Tipo di evento	Descrizione
`checkout.opened`	L’overlay del checkout è stato aperto
`checkout.form_ready`	Il modulo di checkout è pronto per ricevere l’input dell’utente. Utile per nascondere gli stati di caricamento.
`checkout.payment_page_opened`	La pagina di pagamento è stata visualizzata
`checkout.customer_details_submitted`	I dettagli del cliente e di fatturazione sono stati inviati
`checkout.closed`	L’overlay del checkout è stato chiuso
`checkout.redirect`	Il checkout eseguirà un reindirizzamento
`checkout.error`	Si è verificato un errore durante il checkout
`checkout.link_expired`	Viene attivato quando la sessione di checkout scade. Viene ricevuto solo quando `showTimer` è impostato su `false`.
`checkout.status`	Viene attivato quando `manualRedirect` è abilitato. Contiene lo stato del checkout (`succeeded`, `failed` o `processing`).
`checkout.redirect_requested`	Viene attivato quando `manualRedirect` è abilitato. Contiene l’URL al quale reindirizzare il cliente.

L’opzione themeConfig lato client è deprecata e verrà rimossa nella prossima versione principale di Checkout SDK (v2.0.0). Il suo utilizzo registra un avviso di deprecazione nella console del browser. Configura invece il tema quando crei la sessione di checkout tramite 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 allo stesso modo al checkout overlay, inline e hosted.

Questa sezione descrive la configurazione del tema lato client deprecata utilizzando Checkout SDK. L’approccio consigliato consiste nel configurare i temi lato server quando crei una sessione di checkout tramite API, utilizzando il parametro theme_config. Consulta Personalizzazione del tema del checkout per la configurazione a livello di API, oppure utilizza la pagina Design nella dashboard per configurare visivamente i temi con un’anteprima in tempo reale.

Configurazione di base del tema

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

Configurazione completa del tema

Tutte le proprietà del tema disponibili:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Solo modalità chiara

Se vuoi personalizzare solo il tema chiaro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Solo modalità scura

Se vuoi personalizzare solo il tema scuro:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Override parziale del tema

Puoi eseguire l’override solo di proprietà specifiche. Il checkout utilizzerà i valori predefiniti per le proprietà che non specifichi:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Configurazione del tema con altre opzioni

Puoi combinare la configurazione del tema con altre opzioni di checkout:

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

Tipi TypeScript

Per gli utenti TypeScript, tutti i tipi di configurazione del tema sono esportati:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Gestione degli errori

SDK fornisce informazioni dettagliate sugli errori tramite il sistema di eventi. Implementa sempre una corretta 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);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

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

Best practice

Inizializza una sola volta: inizializza SDK una sola volta al caricamento dell’applicazione, non a ogni tentativo di checkout
Gestione degli errori: implementa sempre una corretta gestione degli errori nel callback degli eventi
Modalità di test: utilizza 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 offrire un’esperienza utente completa
URL validi: utilizza sempre URL di checkout validi provenienti dall’API create checkout session
TypeScript: utilizza TypeScript per una migliore sicurezza dei tipi e una migliore esperienza di sviluppo
Stati di caricamento: mostra gli stati di caricamento mentre il checkout si apre per migliorare la UX
Gestione del timer: disabilita il timer (showTimer: false) se vuoi gestire manualmente la scadenza della sessione

Risoluzione dei problemi

Checkout not opening

Possibili cause:

SDK non inizializzato prima della chiamata a open()
URL di checkout non valido
Errori JavaScript nella console
Problemi di connettività di rete

Soluzioni:

Verifica che l’inizializzazione di SDK avvenga prima dell’apertura del checkout
Controlla la presenza di errori nella console
Assicurati che l’URL di checkout sia valido e provenga dall’API create checkout session
Verifica la connettività di rete

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 di SDK sia stata completata correttamente
Esegui prima un test con un gestore degli eventi semplice

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 negli strumenti per sviluppatori del browser
Verifica che le impostazioni del tema siano corrette
Esegui test con diverse dimensioni dello schermo
Assicurati che non vi siano conflitti di z-index con l’overlay

Abilitazione dei wallet digitali

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

Apple Pay non è ancora supportato nel checkout overlay. Il supporto per Apple Pay sarà disponibile prossimamente.

Browser supportati

Dodo Payments Checkout SDK supporta i seguenti browser:

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

Checkout overlay e inline

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

Funzionalità	Checkout overlay	Checkout inline
Profondità dell’integrazione	Modale sopra la pagina	Completamente incorporato nella pagina
Controllo del layout	Limitato	Completo
Branding	Separato dalla pagina	Integrato
Impegno di implementazione	Inferiore	Superiore
Ideale per	Integrazione rapida, pagine esistenti	Pagine di checkout personalizzate, flussi ad alta conversione

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

Risorse correlate

Inline Checkout

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

Checkout Sessions API

Crea sessioni di checkout per supportare 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

Panoramica

Demo

Interactive Demo

Inizio rapido

Guida all’integrazione passo-passo

Riferimento API

Configurazione

Opzioni di inizializzazione

Opzioni di checkout

Metodi

Apri Checkout

Chiudi Checkout

Controlla Stato

Eventi

Dati Evento Stato Checkout

Dati Evento Reindirizzamento Checkout Richiesto

Configurazione di base del tema

Configurazione completa del tema

Solo modalità chiara

Solo modalità scura

Override parziale del tema

Configurazione del tema con altre opzioni

Tipi TypeScript

Gestione degli errori

Best practice

Risoluzione dei problemi

Abilitazione dei wallet digitali

Browser supportati

Checkout overlay e inline

Risorse correlate

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

​Panoramica

​Demo

Interactive Demo

​Inizio rapido

​Guida all’integrazione passo-passo

​Riferimento API

​Configurazione

​Opzioni di inizializzazione

​Opzioni di checkout

​Metodi

​Apri Checkout

​Chiudi Checkout

​Controlla Stato

​Eventi

​Dati Evento Stato Checkout

​Dati Evento Reindirizzamento Checkout Richiesto

​Configurazione di base del tema

​Configurazione completa del tema

​Solo modalità chiara

​Solo modalità scura

​Override parziale del tema

​Configurazione del tema con altre opzioni

​Tipi TypeScript

​Gestione degli errori

​Best practice

​Risoluzione dei problemi

​Abilitazione dei wallet digitali

​Browser supportati

​Checkout overlay e inline

​Risorse correlate

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Panoramica

Demo

Inizio rapido

Guida all’integrazione passo-passo

Riferimento API

Configurazione

Opzioni di inizializzazione

Opzioni di checkout

Metodi

Apri Checkout

Chiudi Checkout

Controlla Stato

Eventi

Dati Evento Stato Checkout

Dati Evento Reindirizzamento Checkout Richiesto

Configurazione di base del tema

Configurazione completa del tema

Solo modalità chiara

Solo modalità scura

Override parziale del tema

Configurazione del tema con altre opzioni

Tipi TypeScript

Gestione degli errori

Best practice

Risoluzione dei problemi

Abilitazione dei wallet digitali

Browser supportati

Checkout overlay e inline

Risorse correlate