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 de manière sécurisée toutes les informations sensibles de paiement, 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 :
- 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.
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.Customer opens checkout
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.

Customer enters their details
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.
Customer selects payment method
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.

Checkout completed
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.

Démarrage rapide
Commencez avec le paiement en ligne Dodo en quelques lignes de code :Guide d’intégration étape par étape
Initialize the SDK for Inline Display
Initialisez le SDK et spécifiez
displayType: 'inline'. Vous devriez également écouter l’événement checkout.breakdown pour mettre à jour votre interface avec les calculs de taxes et totaux en temps réel.Open the Checkout
Appelez
DodoPayments.Checkout.open() avec le checkoutUrl et le elementId de votre conteneur :Test Your Integration
- Démarrez votre serveur de développement :
- 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 console log dans le rappel onEvent.Exemple complet en React
Cet exemple montre comment implémenter un résumé de commande personnalisé en parallèle avec le paiement intégré, en les synchronisant à l’aide de l’événementcheckout.breakdown.
Référence API
Configuration
Options d’initialisation
| Option | Type | Obligatoire | Description |
|---|---|---|---|
mode | "test" | "live" | Yes | Mode d’environnement. |
displayType | "inline" | "overlay" | Yes | Doit être réglé sur "inline" pour intégrer le paiement. |
onEvent | function | Yes | Fonction de rappel pour gérer les événements du paiement. |
Options de paiement
| 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 | Affiche ou masque le minuteur de paiement. Valeur 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é. Valeur par défaut : true. |
options.manualRedirect | boolean | Non | Lorsqu’activé, le paiement ne redirige plus automatiquement après la finalisation. Vous recevrez à la place les événements checkout.status et checkout.redirect_requested pour gérer vous-même la redirection. |
options.payButtonText | string | Non | Texte personnalisé à afficher sur le bouton payer. |
options.fontSize | FontSize | Non | Taille de police globale pour le paiement. |
options.fontWeight | FontWeight | Non | Épaisseur de police globale pour le paiement. |
Méthodes
Ouvrir le paiement
Ouvre le cadre de paiement dans le conteneur spécifié.manualRedirect, gérez l’achèvement du paiement dans votre rappel onEvent :
Fermer le paiement
Supprime le cadre de paiement par programme et nettoie les écouteurs d’événements.Vérifier le statut
Renvoie si le cadre de paiement est actuellement injecté.Événements
Le SDK fournit des événements en temps réel via le rappelonEvent. Pour le paiement intégré, checkout.breakdown est particulièrement utile pour synchroniser votre interface.
| Type d’événement | Description |
|---|---|
checkout.opened | Le cadre de paiement a été chargé. |
checkout.form_ready | Le formulaire de paiement est prêt à recevoir des saisies utilisateur. Utile pour masquer les états de chargement et afficher l’interface de paiement. |
checkout.breakdown | Déclenché lorsque les prix, taxes ou remises sont mis à jour. |
checkout.customer_details_submitted | Les informations client ont été soumises. |
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 pendant le paiement. |
checkout.link_expired | Déclenché lorsque la session de paiement expire. Reçu uniquement lorsque showTimer est défini sur false. |
checkout.status | Déclenché lorsque manualRedirect est activé. Contient le statut du paiement (succeeded, failed ou processing). |
checkout.redirect_requested | Déclenché lorsque manualRedirect est activé. Contient l’URL vers laquelle rediriger le client. |
Données de répartition du paiement
L’événementcheckout.breakdown fournit les données suivantes :
Données d’événement de statut de paiement
LorsquemanualRedirect est activé, vous recevez l’événement checkout.status avec les données suivantes :
Données d’événement de redirection de paiement demandée
LorsquemanualRedirect est activé, vous recevez l’événement checkout.redirect_requested avec les données suivantes :
Comprendre l’événement de répartition
L’événementcheckout.breakdown est le moyen principal de garder l’interface de votre application synchronisée avec l’état du paiement 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.
| Champ | Description |
|---|---|
subTotal | La somme de toutes les lignes de la session avant que les remises ou taxes ne soient appliquées. |
discount | La valeur totale de toutes les remises appliquées. |
tax | Le montant de taxe calculé. En mode inline, ce champ se met à jour dynamiquement à 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 standard, remise et taxe. |
finalTotal | Le montant réel facturé au client. Cela peut inclure des ajustements de change ou des frais de méthode de paiement locale qui ne font pas partie du détail 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. |
- Formatage des devises : Les prix sont toujours renvoyés sous forme d’entiers dans la plus petite unité de devise (par exemple, centimes pour USD, yens 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,
taxetdiscountpeuvent être0ounulljusqu’à ce que l’utilisateur fournisse ses informations de facturation ou applique un code. Votre interface doit gérer ces états avec élégance (par exemple, afficher un tiret—ou masquer la ligne). - « Total final » vs « Total » : Alors qu’
totalvous donne le calcul de prix standard,finalTotalest la source de vérité pour la transaction. SifinalTotalest présent, il reflète exactement ce qui sera débité sur la carte du client, y compris les ajustements dynamiques. - Retour en temps réel : Utilisez le champ
taxpour montrer aux utilisateurs que les taxes sont calculées en direct. Cela donne un ressenti « live » à votre page de paiement et réduit les frictions pendant la 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 :Mise à jour du moyen de paiement
Le paiement en ligne prend en charge les mises à jour de moyen de paiement pour les abonnements. Lorsqu’un client doit mettre à jour son moyen de paiement — que ce soit pour un abonnement actif ou pour réactiver un abonnement en attente — vous pouvez intégrer le flux de mise à jour directement dans la mise en page de votre page.Comment cela fonctionne
- Appelez l’API de mise à jour du moyen de paiement pour obtenir un
payment_link:
- Passez le
payment_linkretourné commecheckoutUrlpour ouvrir le paiement en ligne :
Pour les abonnements en attente
Lors de la mise à jour du moyen de paiement d’un abonnement en statuton_hold, Dodo Payments crée automatiquement une charge pour les sommes dues restantes. Surveillez les webhooks payment.succeeded et subscription.active pour confirmer la réactivation.
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 rappelonEvent :
Bonnes pratiques
- Design réactif : assurez-vous que votre élément conteneur dispose d’une largeur et d’une hauteur suffisantes. L’iframe s’étendra généralement pour remplir son conteneur.
- Synchronisation : utilisez l’événement
checkout.breakdownpour garder votre résumé de commande personnalisé ou vos tableaux de tarification synchronisés avec ce que l’utilisateur voit dans le cadre de paiement. - États squelettes : affichez un indicateur de chargement dans votre conteneur jusqu’à ce que l’événement
checkout.openedse déclenche. - Nettoyage : appelez
DodoPayments.Checkout.close()lorsque votre composant est démonté 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 d’arrière-plan pour une intégration visuelle optimale avec le cadre de paiement en ligne.Validation du statut de paiement
Pourquoi la validation côté serveur est essentielle
Bien que les événements du paiement en ligne commecheckout.status fournissent un retour en temps réel, ils ne doivent pas être votre seule source de vérité pour le statut du paiement. Des problèmes réseau, des plantages de navigateur ou la fermeture de la page par les utilisateurs peuvent faire manquer des événements. Pour garantir une validation fiable du paiement :
- Votre serveur doit écouter les événements de webhook – Dodo Payments envoie des webhooks pour les changements de statut de paiement
- Implémentez un mécanisme de sondage – Votre frontend doit interroger votre serveur pour les mises à jour de statut
- Combinez les deux approches – Utilisez les webhooks comme source principale et le sondage comme secours
Architecture recommandée
Étapes de mise en œuvre
1. Écoutez les événements de paiement – Lorsque l’utilisateur clique sur Payer, commencez à préparer la vérification du statut :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 demanualRedirect: true, certaines méthodes de paiement nécessitent de rediriger l’utilisateur hors de votre page pour l’authentification :
- 3D Secure (3DS) – Authentification de carte
- Google Pay – Authentification du portefeuille sur certains flux
- UPI – Redirections des méthodes de paiement indiennes
checkout.redirect_requested. Redirigez l’utilisateur vers l’URL fournie :
- Vérifiez si l’utilisateur revient d’une redirection (par exemple via
sessionStorage) - Commencez à interroger votre serveur pour obtenir le statut de paiement confirmé
- Affichez un état « Vérification du paiement… » pendant la mise en file d’attente
- Affichez l’interface de réussite/échec en fonction du statut confirmé par le serveur
Dépannage
Checkout frame is not appearing
Checkout frame is not appearing
- Vérifiez que
elementIdcorrespond auidd’undivqui existe réellement dans le DOM. - Assurez-vous que
displayType: 'inline'a été transmis àInitialize. - Vérifiez que le
checkoutUrlest valide.
Taxes are not updating in my UI
Taxes are not updating in my UI
- Assurez-vous d’écouter l’événement
checkout.breakdown. - Les taxes ne sont calculées qu’après que l’utilisateur ait 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 Portefeuilles numériques.Configuration rapide pour Apple Pay
Download domain association file
Téléchargez le fichier d’association de domaine Apple Pay.
Request activation
Envoyez un e-mail à support@dodopayments.com avec l’URL de votre domaine de production et demandez l’activation d’Apple Pay.
Prise en charge des navigateurs
Le SDK 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 type de paiement approprié à votre cas d’utilisation :| Fonctionnalité | Paiement en ligne | Paiement en superposition |
|---|---|---|
| Profondeur d’intégration | Entièrement intégré à la page | Modale au-dessus de la page |
| Contrôle de la mise en page | Contrôle total | Limité |
| Image de marque | Transparent | Séparé de la page |
| Effort d’implémentation | Plus élevé | Moins élevé |
| Idéal pour | Pages de paiement personnalisées, flux à haute conversion | Intégration rapide, pages existantes |
Ressources associées
Overlay Checkout
Utilisez le paiement en superposition pour une intégration rapide basée sur une modale.
Checkout Sessions API
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.
Integration Guide
Guide complet pour intégrer Dodo Payments.
