API Payment Intents
Utilisez l’API Payment Intents pour développer une intégration capable de gérer des flux de paiement complexes dont le statut change au cours du cycle de vie du PaymentIntent. Cette API suit les paiements de leur création à leur finalisation et déclenche des étapes d’authentification supplémentaires si nécessaire.
L’API Payment Intents offre notamment les avantages suivants :
- Gestion de l’authentification automatique
- Aucun paiement en double
- Aucun problème de clé d’idempotence
- Prise en charge de l’authentification forte du client (SCA) et autres changements réglementaires
Un ensemble complet d’API
Utilisez l’API Payment Intents avec les API Setup Intents et Payment Methods. Ces API vous permettent de gérer des paiements dynamiques (notamment avec une authentification supplémentaire de type 3D Secure) et facilitent votre développement à l’international grâce à la prise en charge de nouvelles réglementations et de moyens de paiements locaux.
L’élaboration d’une intégration avec l’API Payment Intents implique deux actions : la création et la confirmation d’un PaymentIntent. Normalement, chaque PaymentIntent est associé au panier ou à une session du client dans votre application. Le PaymentIntent renferme des informations sur la transaction, comme les moyens de paiement pris en charge, le montant à encaisser et la devise souhaitée pour le paiement.
Créer un PaymentIntent
Pour démarrer, consultez le guide d’acceptation des paiements. Ce guide vous explique comment créer un PaymentIntent sur le serveur et transmettre la clé secrète au client au lieu de transmettre l’intégralité de l’objet PaymentIntent.
Lorsque vous créez le PaymentIntent, vous pouvez choisir certains éléments comme le montant et la devise :
Bonnes pratiques
Nous vous recommandons de créer un PaymentIntent dès que le montant est connu, par exemple lorsque le client commence le processus de paiement afin de faciliter le suivi de votre entonnoir des achats. Si nécessaire, vous pourrez mettre à jour le montant du PaymentIntent si celui-ci change. Par exemple, si le client revient en arrière pour ajouter de nouveaux articles au panier, le montant devra être mis à jour lorsque le client recommence le processus de paiement.
Si le processus de paiement est interrompu et reprend plus tard, essayez d’utiliser le même PaymentIntent au lieu d’en créer un nouveau. Chaque PaymentIntent dispose d’un ID unique que vous pouvez utiliser pour le récupérer si nécessaire. Le modèle de données de votre application vous permet de stocker l’ID du PaymentIntent dans le panier ou la session du client afin de pouvoir le récupérer plus facilement. La réutilisation du même PaymentIntent vous procure l’avantage d’effectuer le suivi des tentatives de paiement en échec pour une session ou un panier donné à l’aide de l’état de l’objet.
N’oubliez pas de fournir une clé d’idempotence pour éviter la création de PaymentIntents en double pour le même achat. Cette clé est généralement basée sur l’ID que vous associez au panier ou à la session client dans votre application.
Transmettre la clé secrète du client côté client
Le PaymentIntent contient la clé secrète du client, qui est une clé unique associée à un PaymentIntent donné. Sur le côté client de votre application, la clé secrète est utilisée par Stripe.js comme paramètre pour appeler des fonctions (comme stripe.confirmCardPayment ou stripe.handleCardAction) pour finaliser le paiement.
Récupérer la clé secrète du client
L’objet PaymentIntent comprend une clé secrète du client utilisée côté client pour effectuer le processus de paiement en toute sécurité. Vous pouvez utiliser différentes approches pour transmettre cette clé au côté client.
Avertissement
Vous pouvez utiliser la clé secrète du client pour finaliser le processus de paiement avec le montant spécifié dans le PaymentIntent. Vous ne devez pas l’enregistrer, l’intégrer à une URL ni la dévoiler à d’autres personnes que le client. Veillez à ce que le protocole TLS soit inclus sur toutes les pages qui contiennent la clé secrète du client.
Après le paiement
Une fois que le client a confirmé le paiement, il est recommandé à votre serveur de surveiller les webhooks afin de détecter la réussite ou l’échec du paiement.
Un PaymentIntent
peut avoir plus d’un objet Charge associé s’il y a eu plusieurs tentatives de paiement, par exemple en cas de nouvelles tentatives. Pour chaque paiement, vous pouvez consulter le résultat et les détails du moyen de paiement utilisé.
Optimisation des moyens de paiement pour les prochains achats
Le paramètre setup_future_usage enregistre les moyens de paiement en vue de leur réutilisation. Pour les cartes, il optimise également les taux d’autorisation conformément à la législation régionale et aux règles des réseaux, comme la SCA. Pour choisir la valeur à utiliser, prenez en compte l’utilisation que vous comptez faire du moyen de paiement.
Utilisation prévue du moyen de paiement | Valeur d’énumération setup_future_usage à utiliser |
---|---|
Paiements effectués pendant une session uniquement | on_session |
Paiements effectués hors session uniquement | off_session |
Paiements effectués pendant une session ou hors session | off_session |
Vous pouvez accepter des paiements hors session avec une carte configurée pour payer pendant une session, mais il est probable que l’institution financière refuse le paiement hors session et requiert l’authentification du titulaire de la carte.
L’exemple suivant montre la marche à suivre pour créer un PaymentIntent et indiquer setup_future_usage
:
Avertissement
Les configurations pour les paiements hors session sont plus susceptibles d’entraîner des frictions supplémentaires. Utilisez la configuration pendant une session si vous n’avez pas l’intention d’accepter les paiements hors session avec la carte enregistrée.
Libellé de relevé de compte dynamique
Le libellé de relevé de votre compte Stripe figure par défaut sur les relevés de vos clients chaque fois que vous débitez une carte. Pour afficher un libellé différent sur un paiement, incluez le paramètre statement_descriptor
.
Les libellés de relevé de compte sont limités à 22 caractères, ne peuvent pas contenir les caractères spéciaux <
, >
, '
,"
, ou *
, et ne doivent pas être constitués uniquement de chiffres. Lorsque vous utilisez des libellés dynamiques, le texte dynamique est ajouté au préfixe du libellé de relevé de compte défini dans le Dashboard Stripe. Un astérisque (*
) et une espace sont également ajoutés pour séparer la partie par défaut de la partie dynamique du libellé. Ces 2 caractères sont décomptés des 22 caractères disponibles.
Stockage d’informations sous forme de métadonnées
Stripe vous permet d’ajouter des métadonnées à vos requêtes les plus courantes, notamment au traitement des paiements. Les métadonnées ne sont pas visibles pour vos clients et n’influent aucunement sur un éventuel refus de paiement ou un blocage par notre système de prévention des fraudes.
Grâce aux métadonnées, vous pouvez associer des informations significatives pour vous à l’activité Stripe.
Toutes les métadonnées que vous incluez sont visibles dans le Dashboard (par exemple sur la page d’un paiement donné) ainsi que dans de nombreux rapports. Par exemple, vous pouvez associer l’ID attribué à la commande par votre boutique au PaymentIntent correspondant à celle-ci. Pour vos équipes, le rapprochement des paiements sur Stripe et des commandes enregistrées sur votre système interne s’en trouvera grandement facilité.
Si vous utilisez Radar for Fraud Teams, il peut être judicieux de transmettre toutes les informations supplémentaires concernant vos clients et leurs commandes en tant que métadonnées. Ensuite, vous pouvez définir des règles Radar basées sur des attributs de métadonnées et disposer de davantage d’informations sur les paiements dans le Dashboard, ce qui peut accélérer votre processus d’examen.
Lorsqu’un PaymentIntent crée un paiement, le PaymentIntent copie ses métadonnées dans le paiement. Les modifications ultérieures apportées aux métadonnées du PaymentIntent ne modifieront pas les métadonnées des paiements précédemment créés par le PaymentIntent.
Avertissement
Veillez à ne pas stocker d’informations confidentielles (informations permettant une identification personnelle, données de carte, etc.) sous forme de métadonnées ou dans le paramètre description
du PaymentIntent.