Checkout Inline - Dodo Payments Documentation

Panoramica

Il checkout inline ti consente di creare esperienze di checkout completamente integrate che si fondono perfettamente con il tuo sito web o applicazione. A differenza del checkout overlay, che si apre come un modale sopra la tua pagina, il checkout inline incorpora il modulo di pagamento direttamente nel layout della tua pagina. Utilizzando il checkout inline, puoi:

Creare esperienze di checkout completamente integrate con la tua app o sito web
Consentire a Dodo Payments di catturare in modo sicuro le informazioni sui clienti e sui pagamenti in un frame di checkout ottimizzato
Visualizzare articoli, totali e altre informazioni da Dodo Payments sulla tua pagina
Utilizzare metodi e eventi SDK per costruire esperienze di checkout avanzate

Immagine di copertura del Checkout Inline

Come Funziona

Il checkout inline funziona incorporando un frame sicuro di Dodo Payments nel tuo sito web o app. Il frame di checkout gestisce la raccolta delle informazioni sui clienti e la cattura dei dettagli di pagamento. La tua pagina visualizza l’elenco degli articoli, i totali e le opzioni per modificare ciò che è presente nel checkout. L’SDK consente alla tua pagina e al frame di checkout di interagire tra loro. Dodo Payments crea automaticamente un abbonamento quando un checkout viene completato, pronto per essere attivato da te.

Il frame di checkout inline gestisce in modo sicuro tutte le informazioni sensibili sui pagamenti, garantendo la conformità PCI senza ulteriori certificazioni da parte tua.

Cosa Rende un Buon Checkout Inline?

È importante che i clienti sappiano da chi stanno acquistando, cosa stanno acquistando e quanto stanno pagando. Per costruire un checkout inline che sia conforme e ottimizzato per la conversione, la tua implementazione deve includere:

Esempio di checkout inline con elementi richiesti etichettati

Informazioni ricorrenti: Se ricorrente, con quale frequenza si ripete e il totale da pagare al rinnovo. Se è una prova, quanto dura la prova.
Descrizioni degli articoli: Una descrizione di ciò che viene acquistato.
Totali delle transazioni: Totali delle transazioni, inclusi subtotale, totale delle tasse e totale generale. Assicurati di includere anche la valuta.
Footer di Dodo Payments: L’intero frame di checkout inline, incluso il footer del checkout che contiene informazioni su Dodo Payments, i nostri termini di vendita e la nostra politica sulla privacy.
Politica di rimborso: Un link alla tua politica di rimborso, se differente dalla politica standard di rimborso di Dodo Payments.

Mostra sempre l’intero frame di checkout inline, incluso il footer. Rimuovere o nascondere informazioni legali viola i requisiti di conformità.

Percorso del Cliente

Il flusso di checkout è determinato dalla configurazione della tua sessione di checkout. A seconda di come configuri la sessione di checkout, i clienti vivranno un checkout che può presentare tutte le informazioni su una singola pagina o attraverso più passaggi.

Il cliente apre il checkout

Puoi aprire il checkout inline passando articoli o una transazione esistente. Usa l’SDK per mostrare e aggiornare le informazioni sulla pagina, e i metodi dell’SDK per aggiornare gli articoli in base all’interazione del cliente.

Pagina iniziale del checkout con elenco articoli e modulo di pagamento

Il cliente inserisce i propri dettagli

Il checkout inline chiede prima ai clienti di inserire il proprio indirizzo email, selezionare il proprio paese e (dove richiesto) inserire il proprio codice postale. Questo passaggio raccoglie tutte le informazioni necessarie per determinare le tasse e le opzioni di pagamento disponibili.Puoi precompilare i dettagli del cliente e presentare indirizzi salvati per semplificare l’esperienza.

Il cliente seleziona il metodo di pagamento

Dopo aver inserito i propri dettagli, ai clienti vengono presentati i metodi di pagamento disponibili e il modulo di pagamento. Le opzioni possono includere carta di credito o debito, PayPal, Apple Pay, Google Pay e altri metodi di pagamento locali in base alla loro posizione.Visualizza i metodi di pagamento salvati se disponibili per accelerare il checkout.

Metodi di pagamento disponibili e modulo dettagli carta

Checkout completato

Dodo Payments instrada ogni pagamento al miglior acquirente per quella vendita per ottenere la migliore possibilità di successo. I clienti entrano in un flusso di successo che puoi costruire.

Schermata di successo con segno di conferma

Dodo Payments crea l'abbonamento

Dodo Payments crea automaticamente un abbonamento per il cliente, pronto per essere attivato da te. Il metodo di pagamento utilizzato dal cliente viene mantenuto in archivio per i rinnovi o le modifiche all’abbonamento.

Inizio Veloce

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

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});

Assicurati di avere un elemento contenitore con il corrispondente id sulla tua pagina: <div id="dodo-inline-checkout"></div>.

Guida all’Integrazione Passo-Passo

Installa l'SDK

Installa l’SDK di Dodo Payments Checkout:

npm install dodopayments-checkout

Inizializza l'SDK per la Visualizzazione Inline

Inizializza l’SDK e specifica displayType: 'inline'. Dovresti anche ascoltare l’evento checkout.breakdown per aggiornare la tua interfaccia utente con calcoli in tempo reale di tasse e totali.

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});

Crea un Elemento Contenitore

Aggiungi un elemento al tuo HTML dove il frame del checkout sarà iniettato:

<div id="dodo-inline-checkout"></div>

Apri il Checkout

Chiama DodoPayments.Checkout.open() con il checkoutUrl e il elementId del tuo contenitore:

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

Testa la Tua Integrazione

Avvia il tuo server di sviluppo:

npm run dev

Testa il flusso di checkout:
- Inserisci i tuoi dettagli email e indirizzo nel frame inline.
- Verifica che il tuo riepilogo ordine personalizzato si aggiorni in tempo reale.
- Testa il flusso di pagamento utilizzando credenziali di test.
- Conferma che i reindirizzamenti funzionino correttamente.

Dovresti vedere eventi di checkout.breakdown registrati nella console del tuo browser se hai aggiunto un log nella callback onEvent.

Vai in Produzione

Quando sei pronto per la produzione:

Cambia la modalità in 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

Aggiorna i tuoi URL di checkout per utilizzare sessioni di checkout live dal tuo backend.
Testa il flusso completo in produzione.

Esempio Completo in React

Questo esempio dimostra come implementare un riepilogo dell’ordine personalizzato insieme al checkout inline, mantenendoli sincronizzati utilizzando l’evento checkout.breakdown.

"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

Riferimento API

Configurazione

Opzioni di Inizializzazione

interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}

Opzione	Tipo	Richiesto	Descrizione
`mode`	`"test" \| "live"`	Sì	Modalità ambiente.
`displayType`	`"inline" \| "overlay"`	Sì	Deve essere impostato su `"inline"` per incorporare il checkout.
`onEvent`	`function`	Sì	Funzione di callback per gestire gli eventi di checkout.

Opzioni di Checkout

export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

Opzione	Tipo	Richiesto	Descrizione
`checkoutUrl`	`string`	Sì	URL della sessione di checkout.
`elementId`	`string`	Sì	Il `id` dell’elemento DOM dove il checkout dovrebbe essere visualizzato.
`options.showTimer`	`boolean`	No	Mostra o nasconde il timer del checkout. 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. Predefinito è `true`.
`options.manualRedirect`	`boolean`	No	Quando abilitato, il checkout non verrà reindirizzato automaticamente dopo il completamento. Invece, riceverai eventi di `checkout.status` e `checkout.redirect_requested` per gestire il reindirizzamento tu stesso.
`options.themeConfig`	`ThemeConfig`	No	Configurazione del tema personalizzato.
`options.payButtonText`	`string`	No	Testo personalizzato da visualizzare sul pulsante di pagamento.
`options.fontSize`	`FontSize`	No	Dimensione del carattere globale per il checkout.
`options.fontWeight`	`FontWeight`	No	Peso del carattere globale per il checkout.

Metodi

Apri Checkout

Apre il frame di checkout nel contenitore specificato.

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

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
    payButtonText: "Pay Now",
  },
});

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

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  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

Rimuove programmaticamente il frame di checkout e pulisce i listener degli eventi.

DodoPayments.Checkout.close();

Controlla Stato

Restituisce se il frame di checkout è attualmente iniettato.

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

Eventi

L’SDK fornisce eventi in tempo reale attraverso la callback onEvent. Per il checkout inline, checkout.breakdown è particolarmente utile per sincronizzare la tua interfaccia utente.

Tipo di Evento	Descrizione
`checkout.opened`	Il frame di checkout è stato caricato.
`checkout.breakdown`	Attivato quando i prezzi, le tasse o gli sconti vengono aggiornati.
`checkout.customer_details_submitted`	I dettagli del cliente sono stati inviati.
`checkout.pay_button_clicked`	Attivato quando il cliente fa clic sul pulsante di pagamento. Utile per analisi e monitoraggio dei funnel di conversione.
`checkout.redirect`	Il checkout eseguirà un reindirizzamento (ad esempio, a una pagina bancaria).
`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 per reindirizzare il cliente.

Dati di Breakdown del Checkout

L’evento checkout.breakdown fornisce i seguenti dati:

interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

Dati dell’Evento di Stato del Checkout

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

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

Dati dell’Evento di Reindirizzamento del Checkout Richiesto

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

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

Comprendere l’Evento di Breakdown

L’evento checkout.breakdown è il modo principale per mantenere l’interfaccia utente della tua applicazione sincronizzata con lo stato del checkout di Dodo Payments. Quando si attiva:

All’inizializzazione: Immediatamente dopo che il frame di checkout è stato caricato e pronto.
Al cambio di indirizzo: Ogni volta che il cliente seleziona un paese o inserisce un codice postale che comporta un ricalcolo delle tasse.

Dettagli dei Campi:

Campo	Descrizione
`subTotal`	La somma di tutti gli articoli nella sessione prima che vengano applicati sconti o tasse.
`discount`	Il valore totale di tutti gli sconti applicati.
`tax`	L’importo della tassa calcolata. In `inline` mode, questo si aggiorna dinamicamente mentre l’utente interagisce con i campi dell’indirizzo.
`total`	Il risultato matematico di `subTotal - discount + tax` nella valuta base della sessione.
`currency`	Il codice valuta ISO (ad es., `"USD"`) per i valori standard di subtotale, sconto e tassa.
`finalTotal`	L’importo effettivo addebitato al cliente. Questo può includere ulteriori aggiustamenti di cambio estero o commissioni di metodo di pagamento locale che non fanno parte della ripartizione del prezzo di base.
`finalTotalCurrency`	La valuta in cui il cliente sta effettivamente pagando. Questo può differire da `currency` se è attiva la parità di potere d’acquisto o la conversione della valuta locale.

Consigli chiave per l’integrazione:

Formattazione della valuta: I prezzi vengono sempre restituiti come interi nella più piccola unità di valuta (ad es., centesimi per USD, yen per JPY). Per visualizzarli, dividere per 100 (o la potenza di 10 appropriata) o utilizzare una libreria di formattazione come Intl.NumberFormat.
Gestione degli stati iniziali: Quando il checkout viene caricato per la prima volta, tax e discount possono essere 0 o null fino a quando l’utente non fornisce le proprie informazioni di fatturazione o applica un codice. La tua interfaccia utente dovrebbe gestire questi stati in modo elegante (ad es., mostrando un trattino — o nascondendo la riga).
Il “Totale Finale” vs “Totale”: Mentre total ti fornisce il calcolo del prezzo standard, finalTotal è la fonte di verità per la transazione. Se finalTotal è presente, riflette esattamente ciò che verrà addebitato sulla carta del cliente, inclusi eventuali aggiustamenti dinamici.
Feedback in tempo reale: Usa il campo tax per mostrare agli utenti che le tasse vengono calcolate in tempo reale. Questo fornisce una sensazione di “live” alla tua pagina di checkout e riduce l’attrito durante la fase di inserimento dell’indirizzo.

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 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 Inline 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",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </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 di bordo.

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
        inputFocusBorder: "#D0D5DD", // Input focus 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",
        inputFocusBorder: "#323232",
        
        // 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 nella tua callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});

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

Migliori Pratiche

Design reattivo: Assicurati che il tuo elemento contenitore abbia abbastanza larghezza e altezza. L’iframe si espanderà tipicamente per riempire il suo contenitore.
Sincronizzazione: Usa l’evento checkout.breakdown per mantenere il tuo riepilogo dell’ordine personalizzato o le tabelle dei prezzi sincronizzate con ciò che l’utente vede nel frame di checkout.
Stati di caricamento: Mostra un indicatore di caricamento nel tuo contenitore fino a quando non si attiva l’evento checkout.opened.
Pulizia: Chiama DodoPayments.Checkout.close() quando il tuo componente viene smontato per pulire l’iframe e i listener degli eventi.

Per implementazioni in modalità scura, è consigliato utilizzare #0d0d0d come colore di sfondo per un’integrazione visiva ottimale con il frame di checkout inline.

Validazione dello stato del pagamento

Non fare affidamento esclusivamente sugli eventi di checkout inline per determinare il successo o il fallimento del pagamento. Implementa sempre una validazione lato server utilizzando webhook e/o polling.

Perché la validazione lato server è essenziale

Sebbene gli eventi di checkout inline come checkout.status forniscano feedback in tempo reale, non dovrebbero essere la tua unica fonte di verità per lo stato del pagamento. Problemi di rete, crash del browser o utenti che chiudono la pagina possono causare la perdita di eventi. Per garantire una validazione affidabile dei pagamenti:

Il tuo server dovrebbe ascoltare gli eventi webhook - Dodo Payments invia webhook per le modifiche allo stato del pagamento
Implementa un meccanismo di polling - Il tuo frontend dovrebbe interrogare il tuo server per aggiornamenti di stato
Combina entrambi gli approcci - Usa i webhook come fonte primaria e il polling come fallback

Architettura raccomandata

Passaggi di implementazione

1. Ascolta gli eventi di checkout - Quando l’utente fa clic su paga, inizia a prepararti per verificare lo stato:

onEvent: (event) => {
  if (event.event_type === 'checkout.status') {
    // Start polling your server for confirmed status
    startPolling();
  }
}

2. Interroga il tuo server - Crea un endpoint che controlla il tuo database per lo stato del pagamento (aggiornato dai webhook):

// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);

3. Gestisci i webhook lato server - Aggiorna il tuo database quando Dodo invia i webhook di payment.succeeded o payment.failed. Vedi la nostra documentazione sui webhook per dettagli.

Gestione dei reindirizzamenti (3DS, Google Pay, UPI)

Quando utilizzi manualRedirect: true, alcuni metodi di pagamento richiedono di reindirizzare l’utente lontano dalla tua pagina per l’autenticazione:

3D Secure (3DS) - Autenticazione della carta
Google Pay - Autenticazione del portafoglio in alcuni flussi
UPI - Reindirizzamenti del metodo di pagamento indiano

Quando è necessario un reindirizzamento, riceverai l’evento checkout.redirect_requested. Reindirizza l’utente all’URL fornito:

if (event.event_type === 'checkout.redirect_requested') {
  const redirectUrl = event.data?.message?.redirect_to;
  // Save payment ID before redirect, then redirect
  sessionStorage.setItem('pendingPaymentId', paymentId);
  window.location.href = redirectUrl;
}

Dopo che l’autenticazione è completata (successo o fallimento), l’utente torna alla tua pagina. Non presumere il successo solo perché l’utente è tornato. Invece:

Controlla se l’utente sta tornando da un reindirizzamento (ad es., tramite sessionStorage)
Inizia a interrogare il tuo server per lo stato di pagamento confermato
Mostra uno stato di “Verifica pagamento…” mentre interroghi
Visualizza l’interfaccia utente di successo/fallimento in base allo stato confermato dal server

Verifica sempre lo stato del pagamento lato server dopo i reindirizzamenti. Il ritorno dell’utente alla tua pagina significa solo che l’autenticazione è completata—non indica se il pagamento è riuscito o fallito.

Risoluzione dei problemi

Il frame di checkout non appare

Verifica che elementId corrisponda al id di un div che esiste effettivamente nel DOM.
Assicurati che displayType: 'inline' sia stato passato a Initialize.
Controlla che il checkoutUrl sia valido.

Le tasse non si aggiornano nella mia interfaccia utente

Assicurati di ascoltare l’evento checkout.breakdown.
Le tasse vengono calcolate solo dopo che l’utente inserisce un paese e un codice postale validi nel frame di checkout.

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 dal sovrapposto di 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 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.

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

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 supporta i seguenti browser:

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Panoramica

​Come Funziona

​Cosa Rende un Buon Checkout Inline?

​Percorso del Cliente

​Inizio Veloce

​Guida all’Integrazione Passo-Passo

​Esempio Completo in React

​Riferimento API

​Configurazione

​Opzioni di Inizializzazione

​Opzioni di Checkout

​Metodi

​Apri Checkout

​Chiudi Checkout

​Controlla Stato

​Eventi

​Dati di Breakdown del Checkout

​Dati dell’Evento di Stato del Checkout

​Dati dell’Evento di Reindirizzamento del Checkout Richiesto

​Comprendere l’Evento di Breakdown

​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

​Validazione dello stato del pagamento

​Perché la validazione lato server è essenziale

​Architettura raccomandata

​Passaggi di implementazione

​Gestione dei reindirizzamenti (3DS, Google Pay, UPI)

​Risoluzione dei problemi

​Abilitare Apple Pay

​Supporto del browser

Panoramica

Come Funziona

Cosa Rende un Buon Checkout Inline?

Percorso del Cliente

Inizio Veloce

Guida all’Integrazione Passo-Passo

Esempio Completo in React

Riferimento API

Configurazione

Opzioni di Inizializzazione

Opzioni di Checkout

Metodi

Apri Checkout

Chiudi Checkout

Controlla Stato

Eventi

Dati di Breakdown del Checkout

Dati dell’Evento di Stato del Checkout

Dati dell’Evento di Reindirizzamento del Checkout Richiesto

Comprendere l’Evento di Breakdown

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

Validazione dello stato del pagamento

Perché la validazione lato server è essenziale

Architettura raccomandata

Passaggi di implementazione

Gestione dei reindirizzamenti (3DS, Google Pay, UPI)

Risoluzione dei problemi

Abilitare Apple Pay

Supporto del browser