Overlay Checkout

Le checkout overlay ouvre une fenêtre modale au-dessus de votre page. Les clients saisissent leurs informations de paiement dans la fenêtre modale tandis que votre page reste visible en arrière-plan. Lorsqu’ils ferment la fenêtre modale, le contrôle revient à votre page. Lorsqu’ils terminent le paiement, ils sont redirigés vers return_url.

Fenêtre modale du checkout overlay affichée au-dessus d’une page produit

Interactive Demo

Découvrez le checkout overlay en action avec notre démonstration en direct.

Démarrage rapide

Installez le SDK, initialisez-le, puis ouvrez le checkout avec une URL de checkout provenant de l’API de création d’une session de checkout :

import { DodoPayments } from "dodopayments-checkout";

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

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

Intégration étape par étape

Install the SDK

Installez via npm, yarn ou pnpm :

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Appelez Initialize une fois au chargement de votre application, généralement dans votre composant principal ou votre point d’entrée :

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Initialisez toujours le SDK avant d’ouvrir le checkout. Initialisez-le une seule fois au chargement de votre application, et non avant chaque tentative de checkout.

Create a Checkout Button

Créez un composant qui ouvre la fenêtre modale de checkout :

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.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 the Button to Your Page

Utilisez le composant de bouton de checkout 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 Redirects

Créez des pages pour gérer les redirections du checkout après le 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 parcours de checkout :
- Cliquez sur le bouton de checkout
- Vérifiez que la fenêtre modale s’affiche
- Testez le parcours de paiement avec les identifiants de test
- Confirmez que les redirections fonctionnent correctement

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

Go Live

Lorsque vous êtes prêt pour la production :

Remplacez le mode par 'live' :

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

Mettez à jour vos URL de checkout afin d’utiliser les sessions de checkout live depuis votre backend
Testez l’intégralité du parcours en production
Surveillez les événements et les erreurs

Référence API

Initialiser

Appelez Initialize une fois pour configurer le SDK :

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

DodoPayments.Initialize(options);

Option	Type	Obligatoire	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 checkout modal (par défaut), `"inline"` pour le checkout intégré
`onEvent`	`function`	Oui	Fonction de callback pour gérer les événements du checkout

Ouvrir le checkout

Ouvrez la fenêtre modale de checkout :

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Option	Type	Obligatoire	Description
`checkoutUrl`	`string`	Oui	URL de la session de checkout provenant de l’API de création d’une session de checkout
`options.showTimer`	`boolean`	Non	Affiche ou masque le minuteur de session. La valeur par défaut est `true`. Lorsqu’il est désactivé, vous recevez l’événement `checkout.link_expired` lorsque la session expire.
`options.showSecurityBadge`	`boolean`	Non	Affiche ou masque le badge de sécurité. La valeur par défaut est `true`
`options.manualRedirect`	`boolean`	Non	Lorsque la valeur est `true`, empêche les redirections automatiques. Le checkout émet `checkout.status` avec le résultat du paiement et `checkout.redirect_requested` avec l’URL à ouvrir ; vous gérez alors la navigation
`options.themeConfig`	`ThemeConfig`	Non	Obsolète. Configurez plutôt le thème côté serveur lors de la création de la session de checkout
`options.payButtonText`	`string`	Non	Texte personnalisé du bouton de paiement
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	Non	Taille de police globale du checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	Non	Graisse de police globale du checkout

Fermer le checkout

Fermez la fenêtre modale par programmation :

DodoPayments.Checkout.close();

Vérifier l’état

Vérifiez si la fenêtre modale est actuellement ouverte :

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

Événements

Écoutez les événements du checkout via le callback onEvent transmis à Initialize :

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Événement	Description
`checkout.opened`	La fenêtre modale est ouverte
`checkout.form_ready`	Le formulaire est prêt à recevoir les saisies de l’utilisateur. Utilisez-le pour masquer les états de chargement
`checkout.payment_page_opened`	La page de paiement est affichée
`checkout.customer_details_submitted`	Les informations du client et de facturation ont été envoyées
`checkout.closed`	La fenêtre modale est fermée
`checkout.redirect`	Le checkout va effectuer une redirection, par exemple vers une page bancaire
`checkout.error`	Une erreur s’est produite pendant le checkout
`checkout.link_expired`	La session de checkout a expiré. Reçu uniquement lorsque `showTimer` est défini sur `false`.

Implémentation CDN

Pour une intégration rapide sans étape de build, chargez le SDK depuis le 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>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      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://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Personnalisation du thème

L’option themeConfig côté client est obsolète et sera supprimée dans la prochaine version majeure du Checkout SDK (v2.0.0). Son utilisation génère un avertissement d’obsolescence dans la console du navigateur. Configurez plutôt votre thème lors de la création de la session de checkout via l’API, à l’aide du paramètre customization.theme_config — consultez Personnalisation du thème du checkout — ou visuellement depuis la page Design du dashboard. Les thèmes configurés au niveau de la session s’appliquent aussi bien au checkout overlay qu’aux checkouts inline et hosted.

Cette section présente la configuration de thème côté client, désormais obsolète, à l’aide du Checkout SDK. L’approche recommandée consiste à configurer les thèmes côté serveur lors de la création d’une session de checkout via l’API, à l’aide du paramètre theme_config. Consultez Personnalisation du thème du checkout pour la configuration au niveau de l’API, ou utilisez la page Design du dashboard pour configurer visuellement les thèmes avec un aperçu en direct.

Si vous devez utiliser la configuration de thème côté client, transmettez themeConfig dans le paramètre options :

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Propriétés du thème

Toutes les propriétés de thème disponibles pour les modes clair et sombre :

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Gestion des erreurs

Implémentez toujours la gestion des erreurs dans votre callback onEvent :

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

Gérez toujours l’événement checkout.error afin d’offrir une bonne expérience utilisateur lorsque des erreurs se produisent.

Bonnes pratiques

Initialiser une seule fois : appelez Initialize une fois au chargement de votre application, et non avant chaque checkout
Gestion des erreurs : implémentez une gestion appropriée des erreurs dans votre callback d’événements
Mode de test : utilisez le mode "test" pendant le développement et passez à "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
URL valides : utilisez toujours des URL de checkout valides provenant de l’API de création d’une session de checkout
TypeScript : utilisez TypeScript pour une meilleure sécurité des types et une meilleure expérience développeur
États de chargement : affichez les états de chargement pendant l’ouverture du checkout afin d’améliorer l’UX
Gestion du minuteur : désactivez le minuteur (showTimer: false) si vous souhaitez gérer manuellement l’expiration des sessions

Dépannage

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()
Consultez la console du navigateur pour détecter les erreurs JavaScript
Vérifiez que l’initialisation du SDK s’est terminée correctement
Commencez par tester avec un gestionnaire d’événements simple

Styling issues

Causes possibles :

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

Solutions :

Recherchez les conflits CSS dans les outils de développement du navigateur
Vérifiez que les paramètres du thème sont corrects
Testez différentes tailles d’écran
Assurez-vous qu’il n’existe aucun conflit de z-index avec la fenêtre modale

Portefeuilles numériques

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

Apple Pay n’est pas encore pris en charge dans le checkout overlay.

Navigateurs pris en charge

Le Checkout SDK de Dodo Payments prend en charge :

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

Checkout overlay et checkout inline

Choisissez le type de checkout adapté à votre cas d’utilisation :

Fonctionnalité	Overlay	Inline
Niveau d’intégration	Modal au-dessus de la page	Entièrement intégré à la page
Contrôle de la mise en page	Limité	Contrôle total
Branding	Séparé de la page	Correspond à votre page
Effort d’implémentation	Moins important	Plus important
Adapté à	Intégration rapide, pages existantes	Pages de checkout personnalisées, parcours à fort taux de conversion

Utilisez le checkout overlay pour une intégration plus rapide avec un minimum de modifications de vos pages existantes. Utilisez le checkout inline lorsque vous souhaitez un contrôle maximal de l’expérience de checkout et une identité visuelle cohérente.

Ressources associées

Inline Checkout

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

Checkout Sessions API

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

Webhooks

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

Integration Guide

Guide complet pour intégrer Dodo Payments.

Pour obtenir davantage d’aide, rejoignez notre communauté Discord ou contactez notre équipe d’assistance aux développeurs.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Démarrage rapide

Intégration étape par étape

Référence API

Initialiser

Ouvrir le checkout

Fermer le checkout

Vérifier l’état

Événements

Implémentation CDN

Personnalisation du thème

Propriétés du thème

Gestion des erreurs

Bonnes pratiques

Dépannage

Portefeuilles numériques

Navigateurs pris en charge

Checkout overlay et checkout inline

Ressources associées

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Démarrage rapide

​Intégration étape par étape

​Référence API

​Initialiser

​Ouvrir le checkout

​Fermer le checkout

​Vérifier l’état

​Événements

​Implémentation CDN

​Personnalisation du thème

​Propriétés du thème

​Gestion des erreurs

​Bonnes pratiques

​Dépannage

​Portefeuilles numériques

​Navigateurs pris en charge

​Checkout overlay et checkout inline

​Ressources associées

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Démarrage rapide

Intégration étape par étape

Référence API

Initialiser

Ouvrir le checkout

Fermer le checkout

Vérifier l’état

Événements

Implémentation CDN

Personnalisation du thème

Propriétés du thème

Gestion des erreurs

Bonnes pratiques

Dépannage

Portefeuilles numériques

Navigateurs pris en charge

Checkout overlay et checkout inline

Ressources associées