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 copertura del checkout overlay

Demo

Demo interattiva

Guarda il checkout overlay 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 il tuo URL di checkout dall’ API per creare sessioni di checkout.

Guida all’integrazione passo-passo

Installa l'SDK

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

npm install dodopayments-checkout

Inizializza l'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 tentare di aprire il checkout. L’inizializzazione dovrebbe avvenire una sola volta quando la tua applicazione si carica.

Crea un componente pulsante di checkout

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

Aggiungi il checkout alla tua pagina

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

Gestisci le pagine di successo e fallimento

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

Testa la tua integrazione

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 di checkout registrati nella console del tuo browser.

Vai in produzione

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	Richiesta	Descrizione
`mode`	`"test" \| "live"`	Sì	Modalità ambiente: `'test'` per sviluppo, `'live'` per produzione
`displayType`	`"overlay" \| "inline"`	No	Tipo di visualizzazione: `'overlay'` per checkout modale (predefinito), `'inline'` per checkout incorporato
`onEvent`	`function`	Sì	Funzione di callback per gestire gli eventi di checkout

Opzioni di checkout

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

Opzione	Tipo	Richiesta	Descrizione
`checkoutUrl`	`string`	Sì	URL della sessione di checkout dall’API di creazione della sessione di checkout
`options.showTimer`	`boolean`	No	Mostra o nascondi il timer di checkout. Predefinito a `true`. Quando disabilitato, riceverai l’evento `checkout.link_expired` quando la sessione scade.
`options.showSecurityBadge`	`boolean`	No	Mostra o nascondi il badge di sicurezza. Predefinito a `true`.
`options.manualRedirect`	`boolean`	No	Quando abilitato, il checkout non verrà reindirizzato automaticamente dopo il completamento. Invece, riceverai gli eventi `checkout.status` e `checkout.redirect_requested` per gestire il reindirizzamento da solo.

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 nel tuo 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 a cui puoi ascoltare tramite il 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.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 di checkout è stato aperto
`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 di checkout è stato chiuso
`checkout.redirect`	Il checkout eseguirà un reindirizzamento
`checkout.error`	Si è verificato un errore durante il checkout
`checkout.link_expired`	Attivato quando la sessione di checkout scade. Ricevuto solo quando `showTimer` è impostato su `false`.
`checkout.status`	Attivato quando `manualRedirect` è abilitato. Contiene lo stato del checkout (`succeeded`, `failed`, o `processing`).
`checkout.redirect_requested`	Attivato quando `manualRedirect` è abilitato. Contiene l’URL a cui reindirizzare il cliente.

Opzioni di Implementazione

Installazione tramite Package Manager

Installa tramite npm, yarn o pnpm come mostrato nella Guida all’Integrazione Passo-Passo.

Implementazione CDN

Per un’integrazione rapida senza passaggi di build, puoi utilizzare il nostro 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>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            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://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Personalizzazione del Tema

Puoi personalizzare l’aspetto del checkout passando un oggetto themeConfig nel parametro options quando apri il checkout. La configurazione del tema supporta sia modalità chiara che scura, consentendoti di personalizzare colori, bordi, testo, pulsanti e raggio di curvatura.

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 desideri 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 desideri 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",
    },
  },
});

Sovrascrittura Parziale del Tema

Puoi sovrascrivere solo proprietà specifiche. Il checkout utilizzerà 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,
    manualRedirect: false,
    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

L’SDK fornisce informazioni dettagliate sugli errori attraverso il sistema di eventi. Implementa sempre una corretta gestione degli errori nel tuo 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 fornire una buona esperienza utente quando si verificano errori.

Migliori Pratiche

Inizializza una sola volta: Inizializza l’SDK una sola volta quando la tua applicazione si carica, non ad ogni tentativo di checkout
Gestione degli errori: Implementa sempre una corretta gestione degli errori nel tuo 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 rilevanti per un’esperienza utente completa
URL validi: Usa sempre URL di checkout validi dall’API di creazione della sessione di checkout
TypeScript: Usa TypeScript per una migliore sicurezza dei tipi e esperienza dello sviluppatore
Stati di caricamento: Mostra stati di caricamento mentre il checkout si apre per migliorare l’UX
Reindirizzamenti manuali: Usa manualRedirect quando hai bisogno di un controllo personalizzato sulla navigazione post-checkout
Gestione del timer: Disabilita il timer (showTimer: false) se desideri gestire manualmente la scadenza della sessione

Risoluzione dei Problemi

Il checkout non si apre

Possibili cause:

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

Soluzioni:

Verifica che l’inizializzazione dell’SDK avvenga prima di aprire il checkout
Controlla gli errori nella console
Assicurati che l’URL di checkout sia valido e provenga dall’API di creazione della sessione di checkout
Verifica la connettività di rete

Eventi non attivati

Possibili cause:

Gestore dell’evento non configurato correttamente
Errori JavaScript che impediscono la propagazione dell’evento
SDK non inizializzato correttamente

Soluzioni:

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

Problemi di stile

Possibili cause:

Conflitti CSS con gli stili della tua applicazione
Impostazioni del tema non applicate correttamente
Problemi di design responsivo

Soluzioni:

Controlla i conflitti CSS negli strumenti per sviluppatori del browser
Verifica che le impostazioni del tema siano corrette
Testa su diverse dimensioni dello schermo
Assicurati che non ci siano conflitti di z-index con l’overlay

Abilitare Apple Pay

Apple Pay consente ai clienti di completare i pagamenti rapidamente e in modo sicuro utilizzando i loro metodi di pagamento salvati. Quando abilitato, i clienti possono avviare il modulo Apple Pay direttamente dall’overlay del checkout su dispositivi supportati.

Apple Pay è supportato su iOS 17+, iPadOS 17+ e Safari 17+ su macOS.

Per abilitare Apple Pay per il tuo dominio in produzione, segui questi passaggi:

Scarica e carica il file di associazione del dominio Apple Pay

Scarica il file di associazione del dominio Apple Pay.Carica il file sul tuo server web all’indirizzo /.well-known/apple-developer-merchantid-domain-association. Ad esempio, se il tuo sito web è example.com, rendi il file disponibile all’indirizzo https://example.com/well-known/apple-developer-merchantid-domain-association.

Richiedi l'attivazione di Apple Pay

Invia un’email a support@dodopayments.com con le seguenti informazioni:

L’URL del tuo dominio di produzione (ad es., https://example.com)
Richiesta per abilitare Apple Pay per il tuo dominio

Riceverai conferma entro 1-2 giorni lavorativi una volta che Apple Pay è stato abilitato per il tuo dominio.

Verifica la disponibilità di Apple Pay

Dopo aver ricevuto conferma, testa Apple Pay nel tuo checkout:

Apri il tuo checkout su un dispositivo supportato (iOS 17+, iPadOS 17+ o Safari 17+ su macOS)
Verifica che il pulsante Apple Pay appaia come opzione di pagamento
Testa l’intero flusso di pagamento

Apple Pay deve essere abilitato per il tuo dominio prima che appaia come opzione di pagamento in produzione. Contatta il supporto prima di andare live se intendi offrire Apple Pay.

Supporto del Browser

L’SDK di Dodo Payments Checkout supporta i seguenti browser:

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Panoramica

Demo

Demo interattiva

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

Opzioni di Implementazione

Installazione tramite Package Manager

Implementazione CDN

Personalizzazione del Tema

Configurazione di Base del Tema

Configurazione Completa del Tema

Solo Modalità Chiara

Solo Modalità Scura

Sovrascrittura Parziale del Tema

Configurazione del Tema con Altre Opzioni

Tipi TypeScript

Gestione degli Errori

Migliori Pratiche

Risoluzione dei Problemi

Abilitare Apple Pay

Supporto del Browser

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Panoramica

​Demo

Demo interattiva

​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

​Opzioni di Implementazione

​Installazione tramite Package Manager

​Implementazione CDN

​Personalizzazione del Tema

​Configurazione di Base del Tema

​Configurazione Completa del Tema

​Solo Modalità Chiara

​Solo Modalità Scura

​Sovrascrittura Parziale del Tema

​Configurazione del Tema con Altre Opzioni

​Tipi TypeScript

​Gestione degli Errori

​Migliori Pratiche

​Risoluzione dei Problemi

​Abilitare Apple Pay

​Supporto del Browser

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

Opzioni di Implementazione

Installazione tramite Package Manager

Implementazione CDN

Personalizzazione del Tema

Configurazione di Base del Tema

Configurazione Completa del Tema

Solo Modalità Chiara

Solo Modalità Scura

Sovrascrittura Parziale del Tema

Configurazione del Tema con Altre Opzioni

Tipi TypeScript

Gestione degli Errori

Migliori Pratiche

Risoluzione dei Problemi

Abilitare Apple Pay

Supporto del Browser