Paiement en ligne - Dodo Payments Documentation

Aperçu

Le paiement intégré vous permet de créer des expériences de paiement entièrement intégrées qui se fondent parfaitement dans votre site Web ou votre application. Contrairement au paiement en superposition, qui s’ouvre en tant que modal au-dessus de votre page, le paiement intégré intègre le formulaire de paiement directement dans la mise en page de votre page. En utilisant le paiement intégré, vous pouvez :

Créer des expériences de paiement entièrement intégrées à votre application ou site Web
Permettre à Dodo Payments de capturer en toute sécurité les informations client et de paiement dans un cadre de paiement optimisé
Afficher des articles, des totaux et d’autres informations de Dodo Payments sur votre page
Utiliser des méthodes et des événements SDK pour construire des expériences de paiement avancées

Comment ça fonctionne

Le paiement intégré fonctionne en intégrant un cadre sécurisé de Dodo Payments dans votre site Web ou votre application. Le cadre de paiement gère la collecte des informations client et la capture des détails de paiement. Votre page affiche la liste des articles, les totaux et les options pour modifier ce qui se trouve dans le paiement. Le SDK permet à votre page et au cadre de paiement d’interagir l’un avec l’autre. Dodo Payments crée automatiquement un abonnement lorsque le paiement est terminé, prêt à être provisionné.

Le cadre de paiement intégré gère en toute sécurité toutes les informations de paiement sensibles, garantissant la conformité PCI sans certification supplémentaire de votre part.

Qu’est-ce qui fait un bon paiement intégré ?

Il est important que les clients sachent qui ils achètent, ce qu’ils achètent et combien ils paient. Pour construire un paiement intégré conforme et optimisé pour la conversion, votre mise en œuvre doit inclure :

Exemple de paiement intégré avec éléments requis étiquetés

Informations récurrentes : Si récurrent, à quelle fréquence cela se reproduit et le total à payer lors du renouvellement. Si un essai, combien de temps dure l’essai.
Descriptions des articles : Une description de ce qui est acheté.
Totaux de transaction : Totaux de transaction, y compris le sous-total, la taxe totale et le total général. Assurez-vous d’inclure la devise également.
Pied de page Dodo Payments : Le cadre de paiement intégré complet, y compris le pied de page de paiement qui contient des informations sur Dodo Payments, nos conditions de vente et notre politique de confidentialité.
Politique de remboursement : Un lien vers votre politique de remboursement, si elle diffère de la politique de remboursement standard de Dodo Payments.

Affichez toujours le cadre de paiement intégré complet, y compris le pied de page. Supprimer ou cacher des informations légales viole les exigences de conformité.

Parcours client

Le flux de paiement est déterminé par la configuration de votre session de paiement. Selon la façon dont vous configurez la session de paiement, les clients vivront un paiement qui peut présenter toutes les informations sur une seule page ou à travers plusieurs étapes.

Le client ouvre le paiement

Vous pouvez ouvrir le paiement en ligne en passant des articles ou une transaction existante. Utilisez le SDK pour afficher et mettre à jour les informations sur la page, et les méthodes du SDK pour mettre à jour les articles en fonction de l’interaction du client.

Page de paiement initiale avec liste d'articles et formulaire de paiement

Le client saisit ses informations

Le paiement intégré demande d’abord aux clients de saisir leur adresse e-mail, de sélectionner leur pays et (si nécessaire) de saisir leur code postal. Cette étape recueille toutes les informations nécessaires pour déterminer les taxes et les options de paiement disponibles.Vous pouvez préremplir les détails du client et présenter des adresses enregistrées pour simplifier l’expérience.

Le client sélectionne le mode de paiement

Après avoir saisi leurs informations, les clients se voient présenter les modes de paiement disponibles et le formulaire de paiement. Les options peuvent inclure carte de crédit ou de débit, PayPal, Apple Pay, Google Pay et d’autres méthodes de paiement locales en fonction de leur emplacement.Affichez les modes de paiement enregistrés si disponibles pour accélérer le paiement.

Méthodes de paiement disponibles et formulaire de détails de carte

Paiement terminé

Dodo Payments achemine chaque paiement vers le meilleur acquéreur pour cette vente afin d’obtenir la meilleure chance de succès possible. Les clients entrent dans un flux de succès que vous pouvez construire.

Écran de succès avec coche de confirmation

Dodo Payments crée un abonnement

Dodo Payments crée automatiquement un abonnement pour le client, prêt à être provisionné. Le mode de paiement utilisé par le client est conservé pour les renouvellements ou les modifications d’abonnement.

Abonnement créé avec notification webhook

Démarrage rapide

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

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});

Assurez-vous d’avoir un élément conteneur avec le id correspondant sur votre page : <div id="dodo-inline-checkout"></div>.

Guide d’intégration étape par étape

Installer le SDK

Installez le SDK de paiement Dodo :

npm install dodopayments-checkout

Initialiser le SDK pour l'affichage en ligne

Initialisez le SDK et spécifiez displayType: 'inline'. Vous devez également écouter l’événement checkout.breakdown pour mettre à jour votre interface utilisateur avec des calculs de taxes et de totaux en temps réel.

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});

Créer un élément conteneur

Ajoutez un élément à votre HTML où le cadre de paiement sera injecté :

<div id="dodo-inline-checkout"></div>

Ouvrir le paiement

Appelez DodoPayments.Checkout.open() avec le checkoutUrl et le elementId de votre conteneur :

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

Tester votre intégration

Démarrez votre serveur de développement :

npm run dev

Testez le flux de paiement :
- Entrez votre email et vos coordonnées dans le cadre en ligne.
- Vérifiez que votre résumé de commande personnalisé se met à jour en temps réel.
- Testez le flux de paiement en utilisant des identifiants de test.
- Confirmez que les redirections fonctionnent correctement.

Vous devriez voir des événements checkout.breakdown enregistrés dans la console de votre navigateur si vous avez ajouté un log dans le callback onEvent.

Passer en production

Lorsque vous êtes prêt pour la production :

Changez le mode en 'live' :

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

Mettez à jour vos URL de paiement pour utiliser des sessions de paiement en direct depuis votre backend.
Testez le flux complet en production.

Exemple complet en React

Cet exemple démontre comment implémenter un résumé de commande personnalisé aux côtés du paiement en ligne, en les maintenant synchronisés à l’aide de l’événement checkout.breakdown.

"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

Référence API

Configuration

Options d’initialisation

interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}

Option	Type	Requis	Description
`mode`	`"test" \| "live"`	Oui	Mode d’environnement.
`displayType`	`"inline" \| "overlay"`	Oui	Doit être défini sur `"inline"` pour intégrer le paiement.
`onEvent`	`function`	Oui	Fonction de rappel pour gérer les événements de paiement.

Options de paiement

export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

Option	Type	Requis	Description
`checkoutUrl`	`string`	Oui	URL de session de paiement.
`elementId`	`string`	Oui	Le `id` de l’élément DOM où le paiement doit être rendu.
`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.
`options.themeConfig`	`ThemeConfig`	Non	Configuration de thème personnalisée.
`options.payButtonText`	`string`	Non	Texte personnalisé à afficher sur le bouton de paiement.
`options.fontSize`	`FontSize`	Non	Taille de police globale pour le paiement.
`options.fontWeight`	`FontWeight`	Non	Poids de police global pour le paiement.

Méthodes

Ouvrir le paiement

Ouvre le cadre de paiement dans le conteneur spécifié.

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

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
    payButtonText: "Pay Now",
  },
});

Lors de l’utilisation de manualRedirect, gérez l’achèvement du paiement dans votre callback onEvent :

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  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

Supprime le cadre de paiement par programme et nettoie les écouteurs d’événements.

DodoPayments.Checkout.close();

Vérifier le statut

Renvoie si le cadre de paiement est actuellement injecté.

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

Événements

Le SDK fournit des événements en temps réel via le callback onEvent. Pour le paiement en ligne, checkout.breakdown est particulièrement utile pour synchroniser votre interface utilisateur.

Type d’événement	Description
`checkout.opened`	Le cadre de paiement a été chargé.
`checkout.breakdown`	Déclenché lorsque les prix, les taxes ou les remises sont mis à jour.
`checkout.customer_details_submitted`	Les détails du client ont été soumis.
`checkout.pay_button_clicked`	Déclenché lorsque le client clique sur le bouton de paiement. Utile pour l’analyse et le suivi des entonnoirs de conversion.
`checkout.redirect`	Le paiement effectuera une redirection (par exemple, vers une page bancaire).
`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.

Données de répartition du paiement

L’événement checkout.breakdown fournit les données suivantes :

interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

Données d’événement de statut 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 d’é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;
  };
}

Comprendre l’événement de répartition

L’événement checkout.breakdown est le principal moyen de garder l’interface utilisateur de votre application synchronisée avec l’état de paiement de Dodo Payments. Quand il se déclenche :

À l’initialisation : Immédiatement après que le cadre de paiement est chargé et prêt.
Lors du changement d’adresse : Chaque fois que le client sélectionne un pays ou entre un code postal qui entraîne un recalcul de la taxe.

Détails des champs :

Champ	Description
`subTotal`	La somme de tous les articles de la session avant que des remises ou des taxes ne soient appliquées.
`discount`	La valeur totale de toutes les remises appliquées.
`tax`	Le montant de la taxe calculée. En mode `inline`, cela se met à jour dynamiquement au fur et à mesure que l’utilisateur interagit avec les champs d’adresse.
`total`	Le résultat mathématique de `subTotal - discount + tax` dans la devise de base de la session.
`currency`	Le code de devise ISO (par exemple, `"USD"`) pour les valeurs de sous-total, de remise et de taxe standard.
`finalTotal`	Le montant réel facturé au client. Cela peut inclure des ajustements de change supplémentaires ou des frais de méthode de paiement locale qui ne font pas partie de la répartition de prix de base.
`finalTotalCurrency`	La devise dans laquelle le client paie réellement. Cela peut différer de `currency` si la parité de pouvoir d’achat ou la conversion de devise locale est active.

Conseils d’intégration clés :

Formatage des devises : Les prix sont toujours renvoyés sous forme d’entiers dans la plus petite unité monétaire (par exemple, cents pour USD, yen pour JPY). Pour les afficher, divisez par 100 (ou la puissance de 10 appropriée) ou utilisez une bibliothèque de formatage comme Intl.NumberFormat.
Gestion des états initiaux : Lorsque le paiement se charge pour la première fois, tax et discount peuvent être 0 ou null jusqu’à ce que l’utilisateur fournisse ses informations de facturation ou applique un code. Votre interface utilisateur doit gérer ces états de manière fluide (par exemple, en affichant un tiret — ou en masquant la ligne).
Le “Total final” vs “Total” : Bien que total vous donne le calcul de prix standard, finalTotal est la source de vérité pour la transaction. Si finalTotal est présent, il reflète exactement ce qui sera facturé à la carte du client, y compris tout ajustement dynamique.
Retour d’information en temps réel : Utilisez le champ tax pour montrer aux utilisateurs que les taxes sont calculées en temps réel. Cela donne une sensation “live” à votre page de paiement et réduit les frictions lors de l’étape de saisie de l’adresse.

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 Inline 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",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </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
        inputFocusBorder: "#D0D5DD", // Input focus 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",
        inputFocusBorder: "#323232",
        
        // 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 une gestion des erreurs appropriée dans votre callback onEvent :

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});

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

Meilleures Pratiques

Conception réactive : Assurez-vous que votre élément conteneur a suffisamment de largeur et de hauteur. L’iframe s’étendra généralement pour remplir son conteneur.
Synchronisation : Utilisez l’événement checkout.breakdown pour garder votre résumé de commande personnalisé ou vos tableaux de prix synchronisés avec ce que l’utilisateur voit dans le cadre de paiement.
États de squelette : Affichez un indicateur de chargement dans votre conteneur jusqu’à ce que l’événement checkout.opened se déclenche.
Nettoyage : Appelez DodoPayments.Checkout.close() lorsque votre composant se démonte pour nettoyer l’iframe et les écouteurs d’événements.

Pour les implémentations en mode sombre, il est recommandé d’utiliser #0d0d0d comme couleur de fond pour une intégration visuelle optimale avec le cadre de paiement en ligne.

Validation de l’état de paiement

Ne vous fiez pas uniquement aux événements de paiement en ligne pour déterminer le succès ou l’échec du paiement. Implémentez toujours une validation côté serveur à l’aide de webhooks et/ou de polling.

Pourquoi la validation côté serveur est essentielle

Bien que les événements de paiement en ligne comme checkout.status fournissent un retour d’information en temps réel, ils ne doivent pas être votre seule source de vérité pour l’état du paiement. Des problèmes de réseau, des plantages de navigateur ou des utilisateurs fermant la page peuvent entraîner des événements manqués. Pour garantir une validation de paiement fiable :

Votre serveur doit écouter les événements de webhook - Dodo Payments envoie des webhooks pour les changements d’état de paiement
Implémentez un mécanisme de polling - Votre frontend doit interroger votre serveur pour des mises à jour d’état
Combinez les deux approches - Utilisez les webhooks comme source principale et le polling comme solution de secours

Architecture recommandée

Étapes d’implémentation

1. Écoutez les événements de paiement - Lorsque l’utilisateur clique sur payer, commencez à vous préparer à vérifier l’état :

onEvent: (event) => {
  if (event.event_type === 'checkout.status') {
    // Start polling your server for confirmed status
    startPolling();
  }
}

2. Interrogez votre serveur - Créez un point de terminaison qui vérifie votre base de données pour l’état de paiement (mis à jour par les webhooks) :

// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);

3. Gérez les webhooks côté serveur - Mettez à jour votre base de données lorsque Dodo envoie des webhooks payment.succeeded ou payment.failed. Consultez notre documentation sur les webhooks pour plus de détails.

Gestion des redirections (3DS, Google Pay, UPI)

Lors de l’utilisation de manualRedirect: true, certaines méthodes de paiement nécessitent de rediriger l’utilisateur loin de votre page pour l’authentification :

3D Secure (3DS) - Authentification de carte
Google Pay - Authentification de portefeuille sur certains flux
UPI - Redirections de méthode de paiement indienne

Lorsqu’une redirection est nécessaire, vous recevrez l’événement checkout.redirect_requested. Redirigez l’utilisateur vers l’URL fournie :

if (event.event_type === 'checkout.redirect_requested') {
  const redirectUrl = event.data?.message?.redirect_to;
  // Save payment ID before redirect, then redirect
  sessionStorage.setItem('pendingPaymentId', paymentId);
  window.location.href = redirectUrl;
}

Après que l’authentification soit terminée (succès ou échec), l’utilisateur revient sur votre page. Ne supposez pas le succès simplement parce que l’utilisateur est revenu. Au lieu de cela :

Vérifiez si l’utilisateur revient d’une redirection (par exemple, via sessionStorage)
Commencez à interroger votre serveur pour l’état de paiement confirmé
Affichez un état “Vérification du paiement…” pendant le polling
Affichez l’interface utilisateur de succès/échec en fonction de l’état confirmé par le serveur

Vérifiez toujours l’état du paiement côté serveur après les redirections. Le retour de l’utilisateur sur votre page signifie seulement que l’authentification est terminée—cela n’indique pas si le paiement a réussi ou échoué.

Dépannage

Le cadre de paiement n'apparaît pas

Vérifiez que elementId correspond au id d’un div qui existe réellement dans le DOM.
Assurez-vous que displayType: 'inline' a été passé à Initialize.
Vérifiez que le checkoutUrl est valide.

Les taxes ne se mettent pas à jour dans mon interface utilisateur

Assurez-vous d’écouter l’événement checkout.breakdown.
Les taxes ne sont calculées qu’après que l’utilisateur a saisi un pays et un code postal valides dans le cadre de paiement.

Activation des 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 des 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 à la caisse et testez l’ensemble du processus.

Apple Pay nécessite une vérification de domaine avant d’apparaître en production. Contactez le support avant de mettre en ligne 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 ligne vs Paiement en superposition

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

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

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

Ressources connexes

Paiement en superposition

Utilisez le paiement en superposition pour une intégration rapide basée sur des modaux.

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 l’intégration de 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

​Comment ça fonctionne

​Qu’est-ce qui fait un bon paiement intégré ?

​Parcours client

​Démarrage rapide

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

​Exemple complet en React

​Référence API

​Configuration

​Options d’initialisation

​Options de paiement

​Méthodes

​Ouvrir le paiement

​Fermer le paiement

​Vérifier le statut

​Événements

​Données de répartition du paiement

​Données d’événement de statut de paiement

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

​Comprendre l’événement de répartition

​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

​Validation de l’état de paiement

​Pourquoi la validation côté serveur est essentielle

​Architecture recommandée

​Étapes d’implémentation

​Gestion des redirections (3DS, Google Pay, UPI)

​Dépannage

​Activation des portefeuilles numériques

​Configuration rapide pour Apple Pay

​Support des navigateurs

​Paiement en ligne vs Paiement en superposition

​Ressources connexes

Paiement en superposition

API des sessions de paiement

Webhooks

Guide d'intégration

Aperçu

Comment ça fonctionne

Qu’est-ce qui fait un bon paiement intégré ?

Parcours client

Démarrage rapide

Guide d’intégration étape par étape

Exemple complet en React

Référence API

Configuration

Options d’initialisation

Options de paiement

Méthodes

Ouvrir le paiement

Fermer le paiement

Vérifier le statut

Événements

Données de répartition du paiement

Données d’événement de statut de paiement

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

Comprendre l’événement de répartition

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

Validation de l’état de paiement

Pourquoi la validation côté serveur est essentielle

Architecture recommandée

Étapes d’implémentation

Gestion des redirections (3DS, Google Pay, UPI)

Dépannage

Activation des portefeuilles numériques

Configuration rapide pour Apple Pay

Support des navigateurs

Paiement en ligne vs Paiement en superposition

Ressources connexes