Encaissement des paiements par carte
Préparez votre application et votre back-end pour l'encaissement des paiements par carte à l'aide de Stripe Terminal.
Remarque
Pour les lecteurs intelligents, tels que le lecteur BBPOS WisePOS E ou Stripe Reader S700, nous vous recommandons d’utiliser l’intégration pilotée par serveur plutôt que le SDK JavaScript. L’intégration pilotée par serveur utilise l’API Stripe au lieu de s’appuyer sur les communications réseau locales pour collecter les paiements. Consultez notre comparatif des plateformes pour choisir la plateforme la mieux adaptée à vos besoins.
La définition d’un tunnel de paiement dans votre application est nécessaire pour encaisser des paiements avec Stripe Terminal. Utilisez le SDK Stripe Terminal pour créer et mettre à jour un PaymentIntent, un objet représentant une session de paiement individuelle.
Conçue pour résister aux défaillances, l’intégration Terminal divise le processus de paiement en plusieurs étapes, dont chacune peut être répétée en toute sécurité :
- Créer un PaymentIntent
- Collecter un moyen de paiement. Vous pouvez décider de capturer vos paiements automatiquement ou manuellement.
- Traiter le paiement L’autorisation sur la carte du client a lieu lorsque le SDK traite le paiement.
- (Facultatif) Capturer le paiement
Remarque
Cette forme d’intégration ne prend pas en charge les paiements par carte hors ligne.
Créer un PaymentIntentCôté serveur
La première étape dans l’encaissement d’un paiement consiste à démarrer le tunnel de paiement. Lorsque le client commence à payer, votre application doit créer un objet PaymentIntent
. Celui-ci représente une nouvelle session de paiement sur Stripe.
Utilisez des montants test pour essayer d’obtenir des résultats différents. Un montant se terminant par 00
correspond à un paiement approuvé.
L’exemple suivant montre comment créer un PaymentIntent
sur votre serveur :
Pour les paiements Terminal, le paramètre payment_
doit inclure l’option card_
.
Vous pouvez contrôler le tunnel de paiement de la manière suivante :
- Pour contrôler totalement le tunnel de paiement pour les paiements
card_
, définissez le paramètrepresent capture_
surmethod manual
. Cela vous permet d’ajouter une étape de rapprochement avant la réalisation du paiement. - Pour capturer et autoriser simultanément des paiements, définissez le paramètre
capture_
surmethod automatic
.
Pour accepter les paiements Interac au Canada, vous devez également inclure interac_
dans payment_
. Pour en savoir plus, consultez notre documentation sur le Canada.
Le PaymentIntent
contient une clé secrète du client, une clé unique propre à chaque PaymentIntent
. Pour utiliser la clé secrète du client, vous devez l’obtenir du PaymentIntent
sur votre serveur et la transmettre côté client.
Utilisez la clé secrète du client comme paramètre lorsque vous appelez collectPaymentMethod.
Le paramètre client_
est tout ce dont vous avez besoin dans votre application côté client pour procéder à l’encaissement du moyen de paiement.
Recueillir un moyen de paiementCôté client
Une fois que vous avez créé un PaymentIntent
, il vous faut ensuite recueillir un moyen de paiement avec le SDK.
Pour recueillir un moyen de paiement, votre application doit être connectée à un lecteur. Le lecteur connecté attend qu’une carte soit présentée une fois que votre application appelle collectPaymentMethod
.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret); if (result.error) { // Placeholder for handling result.error } else { // Placeholder for processing result.paymentIntent } }
Cette méthode recueille les données chiffrées du moyen de paiement à l’aide du lecteur de carte connecté, et les associe au PaymentIntent
local.
Examen facultatif des informations du moyen de paiement
Vous pouvez également examiner les informations de moyen de paiement de la carte présentée et effectuer votre propre logique métier avant l’autorisation, ce qui peut être utile pour les cas d’usage avancés.
Utilisez le paramètre update_
pour associer un PaymentMethod
au PaymentIntent
côté serveur. Ces données sont renvoyées dans la réponse collectPaymentMethod
.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret, { config_override: { update_payment_intent: true } }); if (result.error) { // Placeholder for handling result.error } else { const pm = result.paymentIntent.payment_method const card = pm?.card_present ?? pm?.interac_present // Placeholder for business logic on card before processing result.paymentIntent } }
Remarque
Cette méthode permet d’associer les données chiffrées collectées concernant le moyen de paiement grâce à une modification de l’objet PaymentIntent
. Aucune autorisation n’est requise jusqu’à le traitement du paiement.
Ce cas d’usage avancé n’est pas pris en charge sur le P400 de Verifone.
Une fois le moyen de paiement encaissé, vous devez autoriser le paiement ou annuler le recouvrement dans les 30 secondes.
Si le SDK fonctionne hors ligne, le champ paymentMethod
n’est pas présent dans l’objet PaymentIntent
.
À ce stade, vous pouvez accéder à des attributs tels que la marque de la carte, le financement et d’autres données utiles.
Remarque
Stripe tente de détecter si un portefeuille mobile est utilisé dans une transaction, comme indiqué dans l’attribut wallet.
. Cependant, l’attribut n’est pas renseigné si la banque émettrice de la carte ne prend pas en charge l’identification par lecteur d’un portefeuille mobile, une détection précise n’est donc pas garantie. Après l’autorisation à l’étape de confirmation, Stripe reçoit des réseaux des informations actualisées afin de mettre à jour wallet.
de manière fiable.
Annuler la collecte
Annulation programmatique
Vous pouvez annuler la collecte d’un moyen de paiement en appelant cancelCollectPaymentMethod dans le SDK JavaScript.
Annulation initiée par le client
Lorsque vous définissez enable_
sur la valeur « true » pour une transaction, les utilisateurs de lecteurs intelligents voient apparaître un bouton d’annulation.
Appuyer sur le bouton d’annulation annule la transaction active.
terminal.collectPaymentMethod( clientSecret, { config_override: { enable_customer_cancellation: true } } )
Gérer les événements
Remarque
Le SDK JavaScript ne prend en charge que le Verifone P400, le BBPOS WisePOS E et le Stripe Reader S700, qui ont un affichage intégré. Votre application n’a pas besoin de présenter aux utilisateurs les événements du processus d’encaissement du moyen de paiement, car le lecteur les affiche. Pour effacer le moyen de paiement d’une transaction, le caissier peut utiliser la touche rouge X.
Confirmer le paiementCôté client
Après avoir collecté un moyen de paiement auprès du client, vous devez traiter le paiement avec le SDK. Au moment de procéder au paiement, appelez processPayment
avec le PaymentIntent
mis à jour lors de l’étape 2.
- En cas de capture manuelle, si l’appel
processPayment
réussit, l’état dePaymentIntent
passe àrequires_
.capture - En cas de capture automatique d’un paiement, le
PaymentIntent
passe à l’étatsucceeded
.
Remarque
Always confirm PaymentIntents using the Terminal SDK on the client side. Server-side confirmation bypasses critical interactions, such as PIN prompts, and can result in transaction failures.
async () => { const result = await terminal.processPayment(paymentIntent); if (result.error) { // Placeholder for handling result.error } else if (result.paymentIntent) { // Placeholder for notifying your backend to capture result.paymentIntent.id } }
Avertissement
Vous devez capturer un PaymentIntent manuellement sous deux jours, faute de quoi l’autorisation expire et les fonds sont restitués au client.
Gérer les échecs
Lorsque le traitement d’un paiement échoue, le SDK renvoie une erreur qui inclut le PaymentIntent
mis à jour. Votre application doit inspecter le PaymentIntent
pour déterminer comment résoudre l’erreur.
État du PaymentIntent | Signification | Résolution |
---|---|---|
requires_ | Moyen de paiement refusé | Essayez de collecter un autre moyen de paiement en rappelant collectPaymentMethod avec le même PaymentIntent . |
requires_ | Problème de connectivité temporaire | Appelez processPayment à nouveau avec le même PaymentIntent pour relancer la requête. |
PaymentIntent est nil | La requête envoyée à Stripe a expiré, l’état de PaymentIntent est inconnu | Réessayez de traiter le PaymentIntent initial. N’en créez pas un nouveau, car cela pourrait entraîner des autorisations multiples pour le titulaire de la carte. |
Si vous rencontrez plusieurs expirations du délai paiement à la suite, il se peut qu’il y ait un problème de connectivité. Assurez-vous que votre application est connectée à Internet.
Éviter les doublons de paiement
L’objet PaymentIntent
active les mouvements de fonds sur Stripe : utilisez un seul PaymentIntent
pour représenter une transaction.
Réutilisez le même PaymentIntent
même après le refus d’une carte (par exemple, pour fonds insuffisants), afin que votre client puisse réessayer avec une autre carte.
Si vous modifiez le PaymentIntent
, vous devez appeler collectPaymentMethod
pour mettre à jour les informations de paiement sur le lecteur.
Pour que Stripe puisse traiter un PaymentIntent
, il doit être à l’état requires_
. Un PaymentIntent
autorisé, capturé ou annulé ne peut pas être traité par un lecteur.
Capturer le paiementCôté serveur
Si vous avez défini capture_
sur manual
lors de la création du PaymentIntent
à l’étape 1, le SDK renvoie à votre application un PaymentIntent
autorisé, mais non capturé. En savoir plus sur la différence entre autorisation et capture.
Assurez-vous que votre application demande à votre back-end de capturer le paiement lorsqu’elle reçoit du SDK un PaymentIntent
confirmé. Créez dans votre back-end un endpoint qui accepte un ID de PaymentIntent
et envoie à l’API Stripe une demande de capture correspondante :
Si l’appel de capture
réussit, l’état du PaymentIntent
passe à succeeded
.
Remarque
Pour débiter les comptes connectés des frais de plateforme appropriés, inspectez chaque PaymentIntent
et modifiez les frais de plateforme, si nécessaire, avant de capturer le paiement manuellement.
Rapprocher les paiements
Pour vérifier l’activité de paiement de votre entreprise, vous pouvez rapprocher les PaymentIntents avec votre système de commande interne sur votre serveur à la fin de chaque journée.
Un PaymentIntent
conservant l’état requires_
peut signifier deux choses :
Autorisation inutile sur le relevé de carte bancaire de votre client
- Cause : l’utilisateur abandonne le tunnel de paiement de votre application au milieu d’une transaction
- Solution : si le
PaymentIntent
non capturé n’est associé à aucune commande terminée sur votre serveur, vous pouvez l’annuler. Vous ne pouvez pas utiliser unPaymentIntent
annulé pour effectuer des paiements.
Encaissement de fonds incomplet auprès d’un client
- Cause : échec de la requête de votre application signalant à votre back-end de capturer le paiement
- Solution : si le
PaymentIntent
non capturé est associé à une commande terminée sur votre serveur, et aucun autre paiement n’a été encaissé pour la commande (par exemple, un paiement en espèces), vous pouvez le capturer.
Encaisser les pourboires États-Unis uniquement
Aux États-Unis, les utilisateurs admissibles peuvent encaisser des pourboires lors de la capture des paiements.