Encaissement des paiements par carte
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
- Recueillir un moyen de paiement
- Confirmer le paiement
- (Facultatif) Capturer le paiement
À l’étape 1, vous pouvez décider de capturer vos paiements automatiquement ou manuellement. L’autorisation sur la carte du client se produit à l’étape 3, quand le SDK confirme le paiement.
Créer un PaymentIntentCôté clientCôté serveur
La première étape dans l’encaissement des paiements 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.
Vous pouvez créer un PaymentIntent côté client ou côté serveur.
Utilisez des montants test pour essayer de produire des résultats différents. Un montant se terminant par 00
correspond à un paiement approuvé.
Côté client
Créez un PaymentIntent pour votre client :
Avertissement
Si votre application est connectée au Verifone P400, vous ne pouvez pas créer de PaymentIntent à partir du SDK iOS. Vous devez créer le PaymentIntent côté serveur, puis récupérer le PaymentIntent dans votre application à l’aide de la méthode Terminal.retrievePaymentIntent
du SDK.
Côté serveur
Vous pouvez créer le PaymentIntent
sur votre serveur si les informations requises pour lancer un paiement ne sont pas facilement accessibles dans votre application.
L’exemple suivant montre comment créer un PaymentIntent
sur votre serveur :
Pour les paiements Terminal, le paramètre payment_method_types
doit inclure l’option card_present
.
Vous pouvez contrôler le tunnel de paiement de la manière suivante :
- Pour contrôler totalement le tunnel de paiement des transactions
card_present
, définissez le paramètrecapture_method
surmanual
. Cela vous permet d’ajouter une étape de rapprochement avant la réalisation du paiement. - Pour effectuer en même temps la capture et l’autorisation des paiements, définissez le paramètre
capture_method
surautomatic
.
Note
En Australie, vous devez définir capture_method
sur automatic
ou manual_preferred
. Pour en savoir plus, consultez notre documentation concernant l’Australie.
Note
Pour accepter les paiements Interac au Canada, vous devrez également inclure l’option interac_present
dans payment_method_types
. Pour en savoir plus, consultez notre documentation concernant le Canada.
Le PaymentIntent contient une clé secrète du client, qui est une clé unique associée à un PaymentIntent donné. Pour utiliser la clé secrète du client, vous devez l’obtenir du PaymentIntent sur votre serveur et la transmettre côté client.
Utilisez d’abord la clé secrète du client pour appeler retrievePaymentIntent
, puis utilisez le PaymentIntent récupéré pour appeler collectPaymentMethod
.
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 être en mesure de recueillir un moyen de paiement, votre application doit être connectée à un lecteur. Le lecteur connecté attend qu’une carte soit présentée après l’appel de votre application collectPaymentMethod
.
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.
Mise en garde
La collecte d’un moyen de paiement s’effectue localement et ne nécessite aucune autorisation ou mise à jour de l’objet API Payment Intents jusqu’à la confirmation du paiement.
Vous pouvez également inspecter les informations du moyen de paiement Beta
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 initWithUpdatePaymentIntent
dans CollectConfiguration
pour associer un PaymentMethod au PaymentIntent côté serveur. Ces données sont renvoyées dans la réponse collectPaymentMethod
.
Note
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’à la confirmation du paiement.
Le Verifone P400 et les lecteurs Terminal de simulation ne sont pas compatibles avec ce cas d’usage avancé.
À ce stade, vous pouvez accéder à des attributs tels que la marque de la carte, le financement et d’autres données utiles.
Note
Stripe tente de détecter si un portefeuille mobile est utilisé dans une transaction, comme indiqué dans l’attribut wallet.type
. 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.type
de manière fiable.
Annuler la collecte
Annulation programmatique
Vous pouvez annuler la collecte d’un moyen de paiement à l’aide de l’objet Cancelable
renvoyé par le SDK iOS.
Annulation initiée par le client
Lorsque vous définissez setEnableCustomerCancellation
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.
Gérer les événements
En cas d’encaissement d’un moyen de paiement à l’aide d’un lecteur tel que le BBPOS Chipper 2X BT dépourvu d’un écran intégré, votre application doit pouvoir afficher aux utilisateurs les événements depuis le processus d’encaissement des moyens de paiement. Ces événements permettent aux utilisateurs d’encaisser les paiements avec succès (par exemple, relance d’une carte, relance d’une carte différente ou utilisation d’un moyen de lecture différent).
Au début d’une transaction, le SDK adresse une valeur ReaderInputOptions
au gestionnaire d’affichage du lecteur de votre application, précisant les types de saisie acceptables (par exemple, le glissement, l’insertion, la présentation). Dans l’interface de paiement de l’application, invitez l’utilisateur à effectuer son paiement par carte selon l’une de ces options.
Au cours de la transaction, le SDK peut recourir à l’application pour afficher d’autres messages à l’attention de l’utilisateur (« Réessayer la carte », par exemple) en transmettant une valeur ReaderDisplayMessage
au gestionnaire d’affichage du lecteur de votre application. Vérifiez que l’interface de paiement relaie bien ces messages à l’utilisateur.
Note
Votre application n’a pas besoin de présenter les événements du processus de collecte du moyen de paiement aux utilisateurs, car c’est le lecteur qui s’en charge. Pour effacer le moyen de paiement d’une transaction, vous pouvez annuler la requête.
Encaisser des paiements avec Tap to Pay sur iPhone
Lorsque votre application est prête à encaisser un paiement, le SDK iOS de Stripe prend le relais pour gérer le processus d’encaissement. Après l’appel de collecte du moyen de paiement, votre application continue de fonctionner, mais l’iPhone affiche une invite en plein écran demandant au titulaire de la carte de présenter une carte ou un portefeuille mobile compatible avec la technologie NFC. En cas d’erreur de lecture de la carte, une nouvelle tentative s’affiche. Si la présentation réussit, une indication de réussite s’affiche, puis votre application reprend le contrôle pour confirmer le paiement.
Encaissement des paiements
Confirmer le paiementCôté client
Après avoir obtenu un moyen de paiement auprès du client, l’étape suivante consiste à confirmer le paiement à l’aide du SDK. Au moment de procéder au paiement, appelez confirmPaymentIntent
avec le PaymentIntent
mis à jour lors de l’étape 2.
- Pour la capture manuelle des paiements, un appel réussi à
confirmPaymentIntent
génère unPaymentIntent
avec l’étatrequires_capture
. - En cas de capture automatique d’un paiement, le
PaymentIntent
passe à l’étatsucceeded
.
Avertissement
Vous devez capturer les PaymentIntents
manuellement sous deux jours, faute de quoi l’autorisation expire et les fonds sont restitués au client.
Gérer les échecs
Lorsque la confirmation 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_payment_method | Moyen de paiement refusé | Essayez de collecter un autre moyen de paiement en rappelant collectPaymentMethod avec le même PaymentIntent. |
requires_confirmation | Problème de connectivité temporaire | Appelez confirmPaymentIntent à 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 confirmer 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 confirmer un PaymentIntent, il doit être à l’état requires_payment_method
. Un PaymentIntent autorisé, capturé ou annulé ne peut pas être confirmé par un lecteur.
Capturer le paiementCôté serveur
Si vous avez défini capture_method
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
.
Note
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_capture
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. Un PaymentIntent annulé ne peut plus être utilisé 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 percevoir des pourboires lors de la capture des paiements.