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'
  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
  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",
      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",
  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";
  onEvent: (event: CheckoutEvent) => void;
}
OpzioneTipoRichiestaDescrizione
mode"test" | "live"SìModalità ambiente: 'test' per sviluppo, 'live' per produzione
onEventfunctionSìFunzione di callback per gestire gli eventi di checkout

​
Opzioni di checkout

interface CheckoutOptions {
  checkoutUrl: string;
}
OpzioneTipoRichiestaDescrizione
checkoutUrlstringSìURL della sessione di checkout dall’ API per creare sessioni di checkout

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

​
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 onEvent callback: 
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;
    }
  }
});
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

​
Opzioni di implementazione

​
Installazione tramite gestore di pacchetti

Installa tramite npm, yarn o pnpm come mostrato nella Guida all’integrazione passo-passo.

​
Implementazione CDN

Per un’integrazione rapida senza un passaggio 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
            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>

​
Supporto TypeScript

L’SDK è scritto in TypeScript e include definizioni di tipo complete. Tutte le API pubbliche sono completamente tipizzate per una migliore esperienza di sviluppo e supporto IntelliSense. 
import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

​
Gestione degli errori

L’SDK fornisce informazioni dettagliate sugli errori attraverso il sistema di eventi. Implementa sempre una corretta gestione degli errori nel tuo onEvent callback: 
DodoPayments.Initialize({
  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
    }
  }
});
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 per creare sessioni di checkout
  6. TypeScript: Usa TypeScript per una migliore sicurezza dei tipi e esperienza di sviluppo
  7. Stati di caricamento: Mostra stati di caricamento mentre il checkout si apre per migliorare l’UX

​
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 per creare sessioni di checkout
  • Verifica la connettività di rete
Possibili cause:
  • Gestore di eventi non configurato correttamente
  • Errori JavaScript che impediscono la propagazione degli eventi
  • SDK non inizializzato correttamente
Soluzioni:
  • Conferma che il gestore di 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 semplice gestore di eventi
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 di sviluppo 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

​
Supporto del browser

Il Dodo Payments Checkout SDK supporta i seguenti browser:
  • Chrome (ultime versioni)
  • Firefox (ultime versioni)
  • Safari (ultime versioni)
  • Edge (ultime versioni)
  • IE11+
Apple Pay non è attualmente supportato nell’esperienza di checkout overlay. Prevediamo di aggiungere supporto per Apple Pay in una futura versione.
Per ulteriore aiuto, visita la nostra comunità Discord o contatta il nostro team di supporto per sviluppatori.