Checkout Inline

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

Esempio di layout del checkout inline che mostra gli elementi richiesti

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 UI 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 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 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	Richiesta	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

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
}

Opzione	Tipo	Richiesta	Descrizione
`checkoutUrl`	`string`	Sì	URL della sessione di checkout.
`elementId`	`string`	Sì	Il `id` dell’elemento DOM dove il checkout dovrebbe essere visualizzato.

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

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

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.redirect`	Il checkout eseguirà un reindirizzamento (ad esempio, a una pagina bancaria).
`checkout.error`	Si è verificato un errore durante il checkout.

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
}

Comprendere l’Evento di Breakdown

L’evento checkout.breakdown è il modo principale per mantenere la UI 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 delle tasse calcolato. In modalità `inline`, 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 esempio, `"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 del breakdown di 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 esempio, centesimi per USD, yen per JPY). Per visualizzarli, dividi per 100 (o la potenza di 10 appropriata) o usa una libreria di formattazione come Intl.NumberFormat.
Gestione degli Stati Iniziali: Quando il checkout si carica 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 UI dovrebbe gestire questi stati in modo elegante (ad esempio, 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 sarà 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>

Supporto TypeScript

L’SDK è scritto in TypeScript e include definizioni di tipo complete.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  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 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 Responsivo: 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 ordine personalizzato o le tabelle dei prezzi sincronizzate con ciò che l’utente vede nel frame di checkout.
Stati di Skeleton: 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.

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 l’checkoutUrl sia valido.

Le tasse non si aggiornano nella mia UI

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.

Supporto Browser

L’SDK di Dodo Payments Checkout 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 inline. Prevediamo di aggiungere supporto per Apple Pay in una futura versione.

Checkout Inline vs Overlay

Scegli il tipo di checkout giusto per il tuo caso d’uso:

Caratteristica	Checkout Inline	Checkout Overlay
Profondità di integrazione	Completamente incorporato nella pagina	Modale sopra la pagina
Controllo del layout	Controllo completo	Limitato
Branding	Senza soluzione di continuità	Separato dalla pagina
Sforzo di implementazione	Maggiore	Minore
Migliore per	Pagine di checkout personalizzate, flussi ad alta conversione	Integrazione rapida, pagine esistenti

Usa checkout inline quando desideri il massimo controllo sull’esperienza di checkout e branding senza soluzione di continuità. Usa checkout overlay per un’integrazione più rapida con modifiche minime alle tue pagine esistenti.

Risorse Correlate

Checkout Overlay

Usa il checkout overlay per un’integrazione modale rapida.

API delle Sessioni di Checkout

Crea sessioni di checkout per alimentare le tue esperienze di checkout.

Webhook

Gestisci eventi di pagamento lato server con webhook.

Guida all'Integrazione

Guida completa per integrare Dodo Payments.

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

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

Comprendere l’Evento di Breakdown

Opzioni di Implementazione

Installazione tramite Package Manager

Implementazione CDN

Supporto TypeScript

Gestione degli Errori

Migliori Pratiche

Risoluzione dei Problemi

Supporto Browser

Checkout Inline vs Overlay

Risorse Correlate

Checkout Overlay

API delle Sessioni di Checkout

Webhook

Guida all'Integrazione

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

​Comprendere l’Evento di Breakdown

​Opzioni di Implementazione

​Installazione tramite Package Manager

​Implementazione CDN

​Supporto TypeScript

​Gestione degli Errori

​Migliori Pratiche

​Risoluzione dei Problemi

​Supporto Browser

​Checkout Inline vs Overlay

​Risorse Correlate

Checkout Overlay

API delle Sessioni di Checkout

Webhook

Guida all'Integrazione

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

Comprendere l’Evento di Breakdown

Opzioni di Implementazione

Installazione tramite Package Manager

Implementazione CDN

Supporto TypeScript

Gestione degli Errori

Migliori Pratiche

Risoluzione dei Problemi

Supporto Browser

Checkout Inline vs Overlay

Risorse Correlate