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 de l'Overlay Checkout

Démo

Démo interactive

Voir l’overlay de paiement en action avec 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 à partir de l’API de création de session de paiement.

Guide d’intégration étape par étape

Installer le SDK

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

npm install dodopayments-checkout

Initialiser le 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 d’essayer d’ouvrir le paiement. L’initialisation doit se faire une fois lorsque votre application se charge.

Créer un composant de bouton de paiement

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

Ajouter le paiement à votre 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>
  );
}

Gérer les pages de succès et d'échec

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

Tester votre intégration

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 des événements de paiement enregistrés dans la console de votre navigateur.

Passer en production

Lorsque vous êtes prêt pour la production :

Changez le mode en '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 le paiement modal (par défaut), `'inline'` pour le paiement intégré
`onEvent`	`function`	Oui	Fonction de rappel pour gérer les événements de 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 de l’API de création de session de paiement
`options.showTimer`	`boolean`	Non	Afficher ou masquer le minuteur de paiement. Par défaut, c’est `true`. Lorsqu’il est désactivé, vous recevrez l’événement `checkout.link_expired` lorsque la session expire.
`options.showSecurityBadge`	`boolean`	Non	Afficher ou masquer le badge de sécurité. Par défaut, c’est `true`.
`options.manualRedirect`	`boolean`	Non	Lorsqu’il est activé, le paiement ne redirigera pas automatiquement après la finalisation. Au lieu de cela, vous recevrez les événements `checkout.status` et `checkout.redirect_requested` pour gérer la redirection vous-même.

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

Lors de l’utilisation de manualRedirect, gérez la finalisation du paiement dans votre fonction de 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 auxquels vous pouvez vous abonner via la fonction de 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.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`	L’overlay de paiement a été ouvert
`checkout.payment_page_opened`	La page de paiement a été affichée
`checkout.customer_details_submitted`	Les détails du client et de facturation ont été soumis
`checkout.closed`	L’overlay de paiement a été fermé
`checkout.redirect`	Le paiement effectuera une redirection
`checkout.error`	Une erreur s’est produite lors du paiement
`checkout.link_expired`	Déclenché lorsque la session de paiement expire. Reçu uniquement lorsque `showTimer` est défini 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, vous permettant de personnaliser les couleurs, les bordures, le texte, les boutons et le rayon de bordure.

Configuration de Thème de Base

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 Seulement

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 Seulement

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 remplacer uniquement des propriétés spécifiques. Le paiement utilisera des valeurs par défaut pour les propriétés que vous ne spécifiez pas :

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 de 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’erreur détaillées via le système d’événements. Implémentez toujours un traitement d’erreur approprié dans votre fonction de 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");
    }
  }
});

Veillez toujours à gérer l’événement checkout.error pour offrir une bonne expérience utilisateur en cas d’erreurs.

Meilleures Pratiques

Initialisez une fois : Initialisez le SDK une fois lorsque votre application se charge, pas à chaque tentative de paiement
Gestion des erreurs : Implémentez toujours un traitement d’erreur approprié dans votre fonction de rappel d’événements
Mode test : Utilisez le mode test pendant le développement et passez au mode live uniquement lorsque vous êtes prêt pour la production
Gestion des événements : Gérez tous les événements pertinents pour une expérience utilisateur complète
URLs valides : Utilisez toujours des URLs de paiement valides provenant de l’API de création de session de paiement
TypeScript : Utilisez TypeScript pour une meilleure sécurité de type et une expérience développeur améliorée
États de chargement : Affichez des états de chargement pendant que le paiement s’ouvre pour améliorer l’UX
Redirections manuelles : Utilisez manualRedirect lorsque vous avez besoin d’un contrôle personnalisé sur la navigation après le paiement
Gestion du minuteur : Désactivez le minuteur (showTimer: false) si vous souhaitez gérer l’expiration de la session manuellement

Dépannage

Le paiement ne s'ouvre pas

Causes possibles :

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

Solutions :

Vérifiez que l’initialisation du SDK se produit avant d’ouvrir le paiement
Vérifiez 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

Les événements ne se déclenchent pas

Causes possibles :

Gestionnaire d’événements mal configuré
Erreurs JavaScript empêchant la propagation des événements
SDK non initialisé correctement

Solutions :

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

Problèmes de style

Causes possibles :

Conflits CSS avec les styles de votre application
Paramètres de thème non appliqués correctement
Problèmes de design réactif

Solutions :

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

Activer les portefeuilles numériques

Pour des informations détaillées sur la configuration d’Apple Pay, Google Pay et d’autres portefeuilles numériques, consultez la page Portefeuilles numériques.

Configuration rapide pour Apple Pay

Télécharger le fichier d'association de domaine

Téléchargez le fichier d’association de domaine Apple Pay.

Demander l'activation

Envoyez un email à support@dodopayments.com avec l’URL de votre domaine de production et demandez l’activation d’Apple Pay.

Tester après confirmation

Une fois confirmé, vérifiez qu’Apple Pay apparaît au moment du paiement et testez le flux complet.

Apple Pay nécessite la vérification du domaine avant d’apparaître en production. Contactez le support avant de passer en ligne si vous prévoyez d’offrir Apple Pay.

Support 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+

Checkout en overlay vs en ligne

Choisissez le bon type de paiement selon votre cas d’utilisation :

Fonctionnalité	Checkout en overlay	Checkout en ligne
Profondeur d’intégration	Modal en haut de la page	Entièrement intégré dans la page
Contrôle de la mise en page	Limité	Contrôle total
Branding	Séparé de la page	Intégré
Effort de mise en œuvre	Inférieur	Supérieur
Meilleur pour	Intégration rapide, pages existantes	Pages de paiement personnalisées, flux à forte conversion

Utilisez le checkout en overlay pour une intégration plus rapide avec des modifications minimales de vos pages existantes. Utilisez le checkout en ligne lorsque vous souhaitez un contrôle maximal sur l’expérience de paiement et un branding intégré.

Ressources connexes

Checkout en ligne

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

API des sessions de paiement

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

Webhooks

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

Guide d'intégration

Guide complet pour intégrer Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Aperçu

​Démo

Démo interactive

​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 de Base

​Configuration Complète du Thème

​Mode Clair Seulement

​Mode Sombre Seulement

​Surcharge Partielle du Thème

​Configuration du Thème avec D’autres Options

​Types TypeScript

​Gestion des Erreurs

​Meilleures Pratiques

​Dépannage

​Activer les portefeuilles numériques

​Configuration rapide pour Apple Pay

​Support des navigateurs

​Checkout en overlay vs en ligne

​Ressources connexes

Checkout en ligne

API des sessions de paiement

Webhooks

Guide d'intégration

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 de Base

Configuration Complète du Thème

Mode Clair Seulement

Mode Sombre Seulement

Surcharge Partielle du Thème

Configuration du Thème avec D’autres Options

Types TypeScript

Gestion des Erreurs

Meilleures Pratiques

Dépannage

Activer les portefeuilles numériques

Configuration rapide pour Apple Pay

Support des navigateurs

Checkout en overlay vs en ligne

Ressources connexes