Vai al contenuto principale

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

1

Installa l'SDK

Installa il Dodo Payments Checkout SDK utilizzando il tuo gestore di pacchetti preferito:
npm install dodopayments-checkout
2

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

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

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

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

Testa la tua integrazione

  1. Avvia il tuo server di sviluppo:
npm run dev
  1. 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.
7

Vai in produzione

Quando sei pronto per la produzione:
  1. Cambia la modalità in 'live':
DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. Aggiorna i tuoi URL di checkout per utilizzare sessioni di checkout dal vivo dal tuo backend
  2. Testa l’intero flusso in produzione
  3. Monitora eventi ed errori

Riferimento API

Configurazione

Opzioni di inizializzazione

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
OpzioneTipoRichiestoDescrizione
mode"test" | "live"Modalità ambiente: 'test' per lo sviluppo, 'live' per la produzione
displayType"overlay" | "inline"NoTipo di visualizzazione: 'overlay' per il checkout modale (predefinito), 'inline' per il checkout incorporato
onEventfunctionFunzione di callback per gestire gli eventi di checkout

Opzioni di checkout

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}
OpzioneTipoRichiestoDescrizione
checkoutUrlstringURL della sessione di checkout dall’API di creazione della sessione di checkout
options.showTimerbooleanNoMostra o nascondi il timer di checkout. Predefinito a true. Quando disabilitato, riceverai l’evento checkout.link_expired quando la sessione scade.
options.showSecurityBadgebooleanNoMostra o nascondi il badge di sicurezza. Predefinito a true.
options.manualRedirectbooleanNoQuando abilitato, il checkout non verrà reindirizzato automaticamente dopo il completamento. Invece, riceverai gli eventi checkout.status e checkout.redirect_requested per gestire il reindirizzamento tu stesso.

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 funzione di 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 la funzione di 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 EventoDescrizione
checkout.openedL’overlay di checkout è stato aperto
checkout.payment_page_openedLa pagina di pagamento è stata visualizzata
checkout.customer_details_submittedI dettagli del cliente e di fatturazione sono stati inviati
checkout.closedL’overlay di checkout è stato chiuso
checkout.redirectIl checkout eseguirà un reindirizzamento
checkout.errorSi è verificato un errore durante il checkout
checkout.link_expiredAttivato quando la sessione di checkout scade. Ricevuto solo quando showTimer è impostato su false.
checkout.statusAttivato quando manualRedirect è abilitato. Contiene lo stato del checkout (succeeded, failed, o processing).
checkout.redirect_requestedAttivato 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à chiare che scure, consentendoti di personalizzare colori, bordi, testo, pulsanti e raggio dei bordi.

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

  1. Inizializza una sola volta: Inizializza l’SDK una sola volta quando la tua applicazione si carica, non ad ogni tentativo di checkout
  2. Gestione degli errori: Implementa sempre una corretta gestione degli errori nel tuo callback degli eventi
  3. Modalità di test: Usa la modalità test durante lo sviluppo e passa a live solo quando sei pronto per la produzione
  4. Gestione degli eventi: Gestisci tutti gli eventi rilevanti per un’esperienza utente completa
  5. URL validi: Usa sempre URL di checkout validi dall’API di creazione della sessione di checkout
  6. TypeScript: Usa TypeScript per una migliore sicurezza dei tipi e un’esperienza di sviluppo migliore
  7. Stati di caricamento: Mostra stati di caricamento mentre il checkout si apre per migliorare l’UX
  8. Redirect manuali: Usa manualRedirect quando hai bisogno di un controllo personalizzato sulla navigazione post-checkout
  9. Gestione del timer: Disabilita il timer (showTimer: false) se desideri gestire manualmente la scadenza della sessione

Risoluzione dei Problemi

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
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 dell’evento 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
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:
1

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 in /.well-known/apple-developer-merchantid-domain-association. Ad esempio, se il tuo sito web è example.com, rendi il file disponibile in https://example.com/well-known/apple-developer-merchantid-domain-association.
2

Richiedi l'attivazione di Apple Pay

Invia un’email a [email protected] con le seguenti informazioni:
  • L’URL del tuo dominio di produzione (ad es., https://example.com)
  • Richiesta di 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.
3

Verifica la disponibilità di Apple Pay

Dopo aver ricevuto conferma, testa Apple Pay nel tuo checkout:
  1. Apri il tuo checkout su un dispositivo supportato (iOS 17+, iPadOS 17+ o Safari 17+ su macOS)
  2. Verifica che il pulsante Apple Pay appaia come opzione di pagamento
  3. 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:
  • Chrome (ultimissima versione)
  • Firefox (ultimissima versione)
  • Safari (ultimissima versione)
  • Edge (ultimissima versione)
  • IE11+

Checkout Overlay vs Inline

Scegli il tipo di checkout giusto per il tuo caso d’uso:
CaratteristicaCheckout OverlayCheckout Inline
Profondità di integrazioneModale sopra la paginaCompletamente integrato nella pagina
Controllo del layoutLimitatoControllo completo
BrandingSeparato dalla paginaSenza soluzione di continuità
Sforzo di implementazioneInferioreSuperiore
Migliore perIntegrazione rapida, pagine esistentiPagine di checkout personalizzate, flussi ad alta conversione
Usa checkout overlay per un’integrazione più rapida con modifiche minime alle tue pagine esistenti. Usa checkout inline quando desideri il massimo controllo sull’esperienza di checkout e un branding senza soluzione di continuità.

Risorse Correlate

Per ulteriore aiuto, visita la nostra comunità Discord o contatta il nostro team di supporto per sviluppatori.