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 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 provenant 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 l’état du paiement (`succeeded`, `failed`, ou `processing`).
`checkout.redirect_requested`	Déclenché lorsque `manualRedirect` est activé. Contient l’URL pour 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>

Support TypeScript

Le SDK est écrit en TypeScript et inclut des définitions de type complètes. Toutes les API publiques sont entièrement typées pour une meilleure expérience développeur et un support IntelliSense.

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

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

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

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

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 une gestion appropriée des erreurs dans votre fonction de rappel d’événements
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
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 expérience développeur
É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

Activation d’Apple Pay

Apple Pay permet aux clients de finaliser les paiements rapidement et en toute sécurité en utilisant leurs méthodes de paiement enregistrées. Lorsqu’il est activé, les clients peuvent lancer la modalité Apple Pay directement depuis l’overlay de paiement sur les appareils pris en charge.

Apple Pay est pris en charge sur iOS 17+, iPadOS 17+ et Safari 17+ sur macOS.

Pour activer Apple Pay pour votre domaine en production, suivez ces étapes :

Téléchargez et téléversez le fichier d'association de domaine Apple Pay

Téléchargez le fichier d’association de domaine Apple Pay.Téléversez le fichier sur votre serveur web à /.well-known/apple-developer-merchantid-domain-association. Par exemple, si votre site web est example.com, rendez le fichier disponible à https://example.com/well-known/apple-developer-merchantid-domain-association.

Demander l'activation d'Apple Pay

Envoyez un e-mail à [email protected] avec les informations suivantes :

L’URL de votre domaine de production (par exemple, https://example.com)
Demande d’activation d’Apple Pay pour votre domaine

Vous recevrez une confirmation dans un délai de 1 à 2 jours ouvrables une fois qu’Apple Pay a été activé pour votre domaine.

Vérifiez la disponibilité d'Apple Pay

Après avoir reçu la confirmation, testez Apple Pay dans votre paiement :

Ouvrez votre paiement sur un appareil pris en charge (iOS 17+, iPadOS 17+ ou Safari 17+ sur macOS)
Vérifiez que le bouton Apple Pay apparaît comme option de paiement
Testez le flux de paiement complet

Apple Pay doit être activé pour votre domaine avant qu’il n’apparaisse comme option de paiement en production. Contactez le support avant de passer en production si vous prévoyez d’offrir Apple Pay.

Support des navigateurs

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

Chrome (dernier)
Firefox (dernier)
Safari (dernier)
Edge (dernier)
IE11+

Paiement en overlay vs en ligne

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

Fonctionnalité	Paiement en overlay	Paiement en ligne
Profondeur d’intégration	Modal sur la page	Entièrement intégré dans la page
Contrôle de mise en page	Limité	Contrôle total
Branding	Séparé de la page	Transparent
Effort d’implémentation	Moins élevé	Plus élevé
Meilleur pour	Intégration rapide, pages existantes	Pages de paiement personnalisées, flux à haute conversion

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

Ressources connexes

Paiement en ligne

Intégrez directement le paiement dans votre page pour des expériences entièrement 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éveloppeur.

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

Support TypeScript

Gestion des erreurs

Meilleures pratiques

Dépannage

Activation d’Apple Pay

Support des navigateurs

Paiement en overlay vs en ligne

Ressources connexes

Paiement en ligne

API des sessions de paiement

Webhooks

Guide d'intégration

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

​Support TypeScript

​Gestion des erreurs

​Meilleures pratiques

​Dépannage

​Activation d’Apple Pay

​Support des navigateurs

​Paiement en overlay vs en ligne

​Ressources connexes

Paiement 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

Support TypeScript

Gestion des erreurs

Meilleures pratiques

Dépannage

Activation d’Apple Pay

Support des navigateurs

Paiement en overlay vs en ligne

Ressources connexes