Overlay Checkout

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

yarn add dodopayments-checkout

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

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, en utilisant le paramètre customization.theme_config — consultez Personnalisation du thème du checkout — ou visuellement sur la page Design du dashboard. Les thèmes configurés pour une session s’appliquent également au checkout en overlay, inline et hosted.

Cette section présente la configuration de thème côté client 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, en utilisant le 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 temps réel.

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 uniquement

Si vous souhaitez personnaliser uniquement 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 personnaliser uniquement 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",
    },
  },
});

Remplacement partiel du thème

Vous pouvez remplacer uniquement certaines propriétés. Le checkout utilisera les 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 checkout :

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    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. Implémentez toujours une gestion appropriée 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);
      // 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 afin d’offrir une bonne expérience utilisateur lorsque des erreurs surviennent.

Bonnes pratiques

Initialiser une seule fois : initialisez le SDK une seule fois au chargement de votre application, et non à chaque tentative de checkout
Gestion des erreurs : implémentez toujours une gestion appropriée des erreurs dans votre callback d’événement
Mode 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 de session de checkout
TypeScript : utilisez TypeScript pour une meilleure sécurité des types et une meilleure expérience de développement
É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 de la session

Dépannage

Checkout not opening

Causes possibles :

Le SDK n’est pas initialisé avant l’appel à open()
URL de checkout invalide
Erreurs JavaScript dans la console
Problèmes de connectivité réseau

Solutions :

Vérifiez que l’initialisation du SDK a lieu avant l’ouverture du checkout
Recherchez les erreurs dans la console
Assurez-vous que l’URL de checkout est valide et provient de l’API de création de session de checkout
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()
Recherchez les erreurs JavaScript dans la console du navigateur
Vérifiez que l’initialisation du SDK s’est terminée correctement
Commencez par effectuer un test 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 DevTools du navigateur
Vérifiez que les paramètres du thème sont corrects
Effectuez des tests sur différentes tailles d’écran
Assurez-vous qu’il n’existe aucun conflit de z-index avec l’overlay

Activer les portefeuilles numériques

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

Apple Pay n’est pas encore pris en charge dans le checkout en overlay. La prise en charge d’Apple Pay sera bientôt disponible.

Navigateurs pris en charge

Le Checkout SDK de 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 ou inline

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

Fonctionnalité	Checkout en overlay	Checkout 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	Distinct de la page	Transparente
Effort d’implémentation	Moins important	Plus important
Idéal pour	Intégration rapide, pages existantes	Pages de checkout personnalisées, parcours à fort taux de conversion

Utilisez le checkout en 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 un branding homogène.

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 de l’aide, rendez-vous sur notre communauté Discord ou contactez notre équipe d’assistance aux développeurs.

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

Configuration de thème de base

Configuration complète du thème

Mode clair uniquement

Mode sombre uniquement

Remplacement partiel du thème

Configuration du thème avec d’autres options

Types TypeScript

Gestion des erreurs

Bonnes pratiques

Dépannage

Activer les portefeuilles numériques

Navigateurs pris en charge

Checkout en overlay ou inline

Ressources associées

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

​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

​Configuration de thème de base

​Configuration complète du thème

​Mode clair uniquement

​Mode sombre uniquement

​Remplacement partiel du thème

​Configuration du thème avec d’autres options

​Types TypeScript

​Gestion des erreurs

​Bonnes pratiques

​Dépannage

​Activer les portefeuilles numériques

​Navigateurs pris en charge

​Checkout en overlay ou inline

​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

Configuration de thème de base

Configuration complète du thème

Mode clair uniquement

Mode sombre uniquement

Remplacement partiel du thème

Configuration du thème avec d’autres options

Types TypeScript

Gestion des erreurs

Bonnes pratiques

Dépannage

Activer les portefeuilles numériques

Navigateurs pris en charge

Checkout en overlay ou inline

Ressources associées