Overlay Checkout - Dodo Payments Documentation

Aperçu

Le SDK de paiement Dodo fournit un moyen fluide d’intégrer notre overlay de paiement dans votre application web. Construit avec TypeScript et des normes web modernes, il offre une solution robuste pour gérer les paiements avec un traitement d’événements en temps réel et des thèmes personnalisables.

Image de couverture du paiement en superposition

Démo

Interactive Demo

Découvrez le paiement en superposition en action grâce à notre démo en direct.

Démarrage rapide

Commencez avec le SDK de paiement Dodo en quelques lignes de code :

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

Obtenez votre URL de paiement via l’API de création de session de paiement.

Guide d’intégration étape par étape

Install the SDK

Installez le SDK de paiement Dodo en utilisant votre gestionnaire de paquets préféré :

npm install dodopayments-checkout

Initialize the SDK

Initialisez le SDK dans votre application, généralement dans votre composant principal ou point d’entrée de l’application :

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

Initialisez toujours le SDK avant de tenter d’ouvrir le paiement. L’initialisation doit être effectuée une seule fois lors du chargement de votre application.

Create a Checkout Button Component

Créez un composant qui ouvre l’overlay de paiement :

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

Add Checkout to Your Page

Utilisez le composant de bouton de paiement dans votre application :

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

Handle Success and Failure Pages

Créez des pages pour gérer les redirections de paiement :

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

Test Your Integration

Démarrez votre serveur de développement :

npm run dev

Testez le flux de paiement :
- Cliquez sur le bouton de paiement
- Vérifiez que l’overlay apparaît
- Testez le flux de paiement en utilisant des identifiants de test
- Confirmez que les redirections fonctionnent correctement

Vous devriez voir les événements du paiement consignés dans la console de votre navigateur.

Go Live

Lorsque vous êtes prêt pour la production :

Changez le mode pour 'live' :

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Mettez à jour vos URL de paiement pour utiliser des sessions de paiement en direct depuis votre backend
Testez le flux complet en production
Surveillez les événements et les erreurs

Référence API

Configuration

Options d’initialisation

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

Option	Type	Requis	Description
`mode`	`"test" \| "live"`	Oui	Mode d’environnement : `'test'` pour le développement, `'live'` pour la production
`displayType`	`"overlay" \| "inline"`	Non	Type d’affichage : `'overlay'` pour un paiement modal (par défaut), `'inline'` pour un paiement intégré
`onEvent`	`function`	Oui	Fonction de rappel pour gérer les événements du paiement

Options de paiement

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

Option	Type	Requis	Description
`checkoutUrl`	`string`	Oui	URL de session de paiement issue de l’API de création de session de paiement
`options.showTimer`	`boolean`	Non	Affiche ou masque le minuteur du paiement. Par défaut `true`. Lorsqu’il est désactivé, vous recevrez l’événement `checkout.link_expired` lorsque la session expire.
`options.showSecurityBadge`	`boolean`	Non	Affiche ou masque le badge de sécurité. Par défaut `true`.
`options.manualRedirect`	`boolean`	Non	Lorsque cette option est activée, le paiement ne redirige pas automatiquement après la finalisation. Vous recevrez plutôt les événements `checkout.status` et `checkout.redirect_requested` pour gérer vous-même la redirection.

Méthodes

Ouvrir le paiement

Ouvre l’overlay de paiement avec l’URL de session de paiement spécifiée.

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Vous pouvez également passer des options supplémentaires pour personnaliser le comportement du paiement :

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});

Quand vous utilisez manualRedirect, gérez la finalisation du paiement dans votre rappel 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
    }
  },
});

Fermer le paiement

Ferme programmatique l’overlay de paiement.

DodoPayments.Checkout.close();

Vérifier l’état

Renvoie si l’overlay de paiement est actuellement ouvert.

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

Événements

Le SDK fournit des événements en temps réel que vous pouvez écouter via le rappel onEvent :

Données de l’événement d’état de paiement

Lorsque manualRedirect est activé, vous recevez l’événement checkout.status avec les données suivantes :

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

Données de l’événement de redirection de paiement demandée

Lorsque manualRedirect est activé, vous recevez l’événement checkout.redirect_requested avec les données suivantes :

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.form_ready":
        // Checkout form is ready for user input
        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;
    }
  }
});

Type d’événement	Description
`checkout.opened`	La superposition de paiement a été ouverte
`checkout.form_ready`	Le formulaire de paiement est prêt à recevoir les saisies utilisateur. Utile pour masquer les états de chargement.
`checkout.payment_page_opened`	La page de paiement a été affichée
`checkout.customer_details_submitted`	Les coordonnées client et de facturation ont été soumises
`checkout.closed`	La superposition de paiement a été fermée
`checkout.redirect`	Le paiement effectuera une redirection
`checkout.error`	Une erreur est survenue pendant le paiement
`checkout.link_expired`	Déclenché lorsque la session de paiement expire. Reçu uniquement lorsque `showTimer` est réglé sur `false`.
`checkout.status`	Déclenché lorsque `manualRedirect` est activé. Contient le statut du paiement (`succeeded`, `failed` ou `processing`).
`checkout.redirect_requested`	Déclenché lorsque `manualRedirect` est activé. Contient l’URL vers laquelle rediriger le client.

Options d’implémentation

Installation via le gestionnaire de paquets

Installez via npm, yarn ou pnpm comme indiqué dans le Guide d’intégration étape par étape.

Implémentation CDN

Pour une intégration rapide sans étape de construction, vous pouvez utiliser notre 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>

Personnalisation du Thème

Vous pouvez personnaliser l’apparence du paiement en passant un objet themeConfig dans le paramètre options lors de l’ouverture du paiement. La configuration du thème prend en charge les modes clair et sombre, ce qui vous permet de personnaliser les couleurs, les bordures, le texte, les boutons et les rayons de bordure.

Cette section couvre la configuration côté client du thème à l’aide du SDK Checkout. Vous pouvez également configurer les thèmes côté serveur lors de la création d’une session de paiement via l’API en utilisant le paramètre theme_config. Consultez la personnalisation du thème de Checkout pour la configuration au niveau de l’API, ou utilisez la page Design du tableau de bord pour configurer les thèmes visuellement avec aperçu en direct.

Configuration de thème basique

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

Configuration complète du thème

Toutes les propriétés de thème disponibles :

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

Mode clair uniquement

Si vous souhaitez uniquement personnaliser le thème clair :

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Mode sombre uniquement

Si vous souhaitez uniquement personnaliser le thème sombre :

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Surcharge partielle du thème

Vous pouvez ne remplacer que certaines propriétés. Le paiement utilisera les valeurs par défaut pour les propriétés non spécifiées :

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

Configuration du thème avec d’autres options

Vous pouvez combiner la configuration du thème avec d’autres options de paiement :

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

Types TypeScript

Pour les utilisateurs de TypeScript, tous les types de configuration du thème sont exportés :

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Gestion des erreurs

Le SDK fournit des informations détaillées sur les erreurs via le système d’événements. Mettez toujours en place une gestion appropriée des erreurs dans votre rappel 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");
    }
  }
});

Gérez toujours l’événement checkout.error pour offrir une bonne expérience utilisateur lorsque des erreurs surviennent.

Bonnes pratiques

Initialisez une fois : initialisez le SDK une seule fois au chargement de votre application, et non à chaque tentative de paiement
Gestion des erreurs : implémentez toujours une gestion des erreurs appropriée dans votre rappel d’événements
Mode test : utilisez le mode test pendant le développement et basculez sur live uniquement lorsque vous êtes prêt pour la production
Gestion des événements : traitez tous les événements pertinents pour une expérience utilisateur complète
URLs valides : utilisez toujours des URLs de paiement valides issues de l’API de création de session de paiement
TypeScript : utilisez TypeScript pour une meilleure sécurité de typage et expérience développeur
États de chargement : affichez des états de chargement pendant l’ouverture du paiement pour améliorer l’UX
Redirections manuelles : utilisez manualRedirect lorsque vous avez besoin d’un contrôle personnalisé sur la navigation post-paiement
Gestion du minuteur : désactivez le minuteur (showTimer: false) si vous souhaitez gérer manuellement l’expiration de la session

Dépannage

Checkout not opening

Causes possibles :

SDK non initialisé avant l’appel à open()
URL de paiement invalide
Erreurs JavaScript dans la console
Problèmes de connectivité réseau

Solutions :

Vérifiez que le SDK est initialisé avant d’ouvrir le paiement
Recherchez les erreurs dans la console
Assurez-vous que l’URL de paiement est valide et provient de l’API de création de session de paiement
Vérifiez la connectivité réseau

Events not firing

Causes possibles :

Le gestionnaire d’événements n’est pas correctement configuré
Des erreurs JavaScript empêchent la propagation des événements
Le SDK n’est pas correctement initialisé

Solutions :

Confirmez que le gestionnaire d’événements est correctement configuré dans Initialize()
Vérifiez la console du navigateur pour détecter les erreurs JavaScript
Vérifiez que l’initialisation du SDK s’est déroulée avec succès
Testez d’abord avec un gestionnaire d’événements simple

Styling issues

Causes possibles :

Conflits CSS avec les styles de votre application
Paramètres de thème mal appliqués
Problèmes de responsive design

Solutions :

Recherchez les conflits CSS dans les outils de développement du navigateur
Assurez-vous que les paramètres du thème sont corrects
Testez sur différentes tailles d’écran
Vérifiez qu’il n’y a pas de conflits de z-index avec la superposition

Activation des portefeuilles numériques

Pour plus d’informations sur la configuration de Google Pay et d’autres portefeuilles numériques, consultez la page Digital Wallets.

Apple Pay n’est pas encore pris en charge dans le paiement en superposition. Le support arrivera bientôt.

Compatibilité des navigateurs

Le SDK de paiement Dodo Payments prend en charge les navigateurs suivants :

Chrome (dernière version)
Firefox (dernière version)
Safari (dernière version)
Edge (dernière version)
IE11+

Paiement en superposition vs paiement intégré

Choisissez le type de paiement adapté à votre cas d’usage :

Fonctionnalité	Paiement en superposition	Paiement intégré
Profondeur d’intégration	Fenêtre modale au-dessus de la page	Entièrement intégré à la page
Contrôle de la mise en page	Limité	Contrôle total
Image de marque	Séparé de la page	Transparent
Effort de mise en œuvre	Moins important	Plus important
Idéal pour	Intégration rapide, pages existantes	Pages de paiement personnalisées, parcours à forte conversion

Utilisez le paiement en superposition pour une intégration rapide avec un minimum de modifications de vos pages existantes. Utilisez le paiement intégré lorsque vous souhaitez un contrôle maximal sur l’expérience de paiement et une image de marque transparente.

Ressources associées

Inline Checkout

Intégrez le paiement directement dans votre page pour des expériences entièrement intégrées.

Checkout Sessions API

Créez des sessions de paiement pour alimenter vos expériences de paiement.

Webhooks

Traitez les événements de paiement côté serveur avec des webhooks.

Integration Guide

Guide complet pour intégrer Dodo Payments.

Pour plus d’aide, visitez notre communauté Discord ou contactez notre équipe de support développeur.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Aperçu

​Démo

Interactive Demo

​Démarrage rapide

​Guide d’intégration étape par étape

​Référence API

​Configuration

​Options d’initialisation

​Options de paiement

​Méthodes

​Ouvrir le paiement

​Fermer le paiement

​Vérifier l’état

​Événements

​Données de l’événement d’état de paiement

​Données de l’événement de redirection de paiement demandée

​Options d’implémentation

​Installation via le gestionnaire de paquets

​Implémentation CDN

​Personnalisation du Thème

​Configuration de thème basique

​Configuration complète du thème

​Mode clair uniquement

​Mode sombre uniquement

​Surcharge partielle du thème

​Configuration du thème avec d’autres options

​Types TypeScript

​Gestion des erreurs

​Bonnes pratiques

​Dépannage

​Activation des portefeuilles numériques

​Compatibilité des navigateurs

​Paiement en superposition vs paiement intégré

​Ressources associées

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Aperçu

Démo

Démarrage rapide

Guide d’intégration étape par étape

Référence API

Configuration

Options d’initialisation

Options de paiement

Méthodes

Ouvrir le paiement

Fermer le paiement

Vérifier l’état

Événements

Données de l’événement d’état de paiement

Données de l’événement de redirection de paiement demandée

Options d’implémentation

Installation via le gestionnaire de paquets

Implémentation CDN

Personnalisation du Thème

Configuration de thème basique

Configuration complète du thème

Mode clair uniquement

Mode sombre uniquement

Surcharge partielle du thème

Configuration du thème avec d’autres options

Types TypeScript

Gestion des erreurs

Bonnes pratiques

Dépannage

Activation des portefeuilles numériques

Compatibilité des navigateurs

Paiement en superposition vs paiement intégré

Ressources associées