# 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. # JavaScript > #### Recommandation pour les lecteurs intelligents > > Pour les lecteurs intelligents, tels que le [lecteur BBPOS WisePOS E](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md), le [lecteur Stripe S700/S710](https://docs.stripe.com/terminal/readers/stripe-reader-s700-s710.md) et [les lecteurs Verifone](https://docs.stripe.com/terminal/payments/setup-reader/verifone.md), nous recommandons d’utiliser l’[intégration pilotée par serveur](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=server-driven) au lieu du SDK JavaScript. > > Le SDK JavaScript requiert que votre POS et votre lecteur soient connectés au même réseau local avec un DNS local opérationnel. Cependant, l’intégration pilotée par le serveur s’appuie sur l’API Stripe, offrant une approche plus simple dans des environnements réseau complexes. Consultez notre [comparaison de plateformes](https://docs.stripe.com/terminal/payments/setup-reader.md#sdk) pour sélectionner la solution la plus adaptée à vos besoins. Vous découvrez l’API Payment Intents ? Voici quelques ressources utiles : - [L’API Payment Intents](https://docs.stripe.com/payments/payment-intents.md) - [L’objet PaymentIntent](https://docs.stripe.com/api/payment_intents.md) - [Autres scénarios de paiement](https://docs.stripe.com/payments/more-payment-scenarios.md) 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](https://docs.stripe.com/api.md#payment_intents), 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é : 1. [Créer un PaymentIntent](https://docs.stripe.com/terminal/payments/collect-card-payment.md#create-payment) 2. [Collecter un moyen de paiement](https://docs.stripe.com/terminal/payments/collect-card-payment.md#collect-payment). Vous pouvez décider de capturer vos paiements [automatiquement](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-capture_method) ou [manuellement](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md). 3. [Traitement du paiement](https://docs.stripe.com/terminal/payments/collect-card-payment.md#confirm-payment). L’autorisation sur la carte du client a lieu lorsque le SDK traite le paiement. 4. (Facultatif) [Capturer le paiement](https://docs.stripe.com/terminal/payments/collect-card-payment.md#capture-payment) > Ce type d’intégration ne prend pas en charge les [paiements par carte hors ligne](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md). ## Créer un PaymentIntent [Cô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](https://docs.stripe.com/terminal/references/testing.md#physical-test-cards) pour essayer d’obtenir des résultats différents. Un montant se terminant par `00` correspond à un paiement approuvé. > #### Ne recréez pas de PaymentIntents pour les cartes refusées > > Ne recréez pas un PaymentIntent si une carte est refusée. Réutilisez plutôt le même PaymentIntent pour [éviter les doubles paiements](https://docs.stripe.com/terminal/payments/collect-card-payment.md#avoiding-double-charges). L’exemple suivant montre comment créer un `PaymentIntent` sur votre serveur : #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "amount"=1000 \ -d "currency"="usd" \ -d "payment_method_types[]"="card_present" \ -d "capture_method"="manual" ``` 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 pour les paiements `card_present`, définissez le paramètre `capture_method` sur `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_method` sur `automatic`. Pour accepter les paiements Interac au Canada, vous devez également inclure un paramètre `interac_present` dans `payment_method_types`. Pour en savoir plus, consultez notre [documentation sur le Canada](https://docs.stripe.com/terminal/payments/regional.md?integration-country=CA). Le `PaymentIntent` contient une [clé secrète du client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), 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](https://docs.stripe.com/payments/payment-intents.md#passing-to-client). #### Ruby ```ruby post '/create_payment_intent' do intent = # ... Create or retrieve the PaymentIntent {client_secret: intent.client_secret}.to_json end ``` Utilisez la clé secrète du client comme paramètre lorsque vous appelez [collectPaymentMethod](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-payment-method). Le paramètre `client_secret` 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 paiement [Côté client] - [collectPaymentMethod (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-payment-method) Une fois que vous avez créé un `PaymentIntent`, il vous faut ensuite recueillir un moyen de paiement avec le SDK. Pour collecter 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`. ```javascript 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 - [collectPaymentMethod config_override (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-payment-method) 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_payment_intent` pour associer un `PaymentMethod` au `PaymentIntent` côté serveur. Ces données sont renvoyées dans la réponse `collectPaymentMethod`. ```javascript 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 } } ``` Cette méthode associe les données chiffrées collectées du moyen de paiement avec une mise à jour de l’objet `PaymentIntent`. Elle ne nécessite pas d’autorisation tant que vous n’avez pas [traité le paiement](https://docs.stripe.com/terminal/payments/collect-card-payment.md#confirm-payment). 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](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md), 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. 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](https://docs.stripe.com/terminal/payments/collect-card-payment.md#confirm-payment), 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 en appelant [cancelCollectPaymentMethod](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-collect-payment-method) dans le SDK JavaScript. #### Annulation initiée par le client - [enable_customer_cancellation (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-payment-method) Lorsque vous définissez `enable_customer_cancellation` 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. ```javascript terminal.collectPaymentMethod( clientSecret, { config_override: { enable_customer_cancellation: true, } } ) ``` ### Gérer les événements > Le SDK JavaScript ne prend en charge que les lecteurs Stripe S710/710 et BBPOS WisePOS E, qui ont un affichage intégré. Votre application n’a pas besoin d’afficher aux utilisateurs les événements du moyen de paiement traité, car le lecteur les affiche. Pour effacer le moyen de paiement d’une transaction, le caissier peut appuyer sur la touche annuler (❌). ## Confirmer le paiement [Côté client] - [processPayment (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#process-payment) 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](https://docs.stripe.com/terminal/payments/collect-card-payment.md#collect-payment). - En cas de capture manuelle, si l’appel `processPayment` réussit, l’état de `PaymentIntent` passe à `requires_capture`. - En cas de capture automatique d’un paiement, le `PaymentIntent` passe à l’état `succeeded`. Confirmez toujours les PaymentIntents à l’aide du SDK Terminal côté client. La confirmation côté serveur contourne les interactions critiques, telles que les invites de code PIN, et peut entraîner l’échec des transactions. ```javascript 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 } } ``` 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 - [Codes d’erreur (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#error-codes) Lorsque le traitement d’un paiement échoue, le SDK renvoie une erreur qui inclut la `PaymentIntent` mise à jour. Votre application doit inspecter la `PaymentIntent` pour décider comment traiter l’erreur. | État du PaymentIntent | Signification | Résolution | | ------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requires_payment_method` | Moyen de paiement refusé | Essayez de collecter un autre moyen de paiement en appelant à nouveau `collectPaymentMethod` avec la même `PaymentIntent`. | | `requires_confirmation` | Problème de connectivité temporaire | Réexécutez le `processPayment`avec la 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 la `PaymentIntent` initiale. N’en créez pas une nouvelle, car cela pourrait entraîner plusieurs autorisations 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 la `PaymentIntent`, vous devez appeler `collectPaymentMethod` pour mettre à jour les informations de paiement sur le lecteur. Une `PaymentIntent` doit être à l’état `requires_payment_method` pour que Stripe puisse la traiter. Une `PaymentIntent` autorisée, capturée ou annulée ne peut pas être traitée par un lecteur. ## Capturer le paiement [Côté serveur] Si vous avez défini `capture_method` sur `manual` lors de la création du `PaymentIntent` à l’[étape 1](https://docs.stripe.com/terminal/payments/collect-card-payment.md#create-payment), le SDK renvoie à votre application un `PaymentIntent` autorisé, mais non capturé. En savoir plus sur la différence entre [autorisation et capture](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md). When your app receives a confirmed `PaymentIntent` from the SDK, make sure it notifies your back end to capture the payment. Create an endpoint on your back end that accepts a `PaymentIntent` ID and sends a request to the Stripe API to capture it: ```curl curl -X POST https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \ -u "<>:" ``` Si l’appel de `capture` réussit, l’état du `PaymentIntent` passe à `succeeded`. 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](https://docs.stripe.com/api/payment_intents/cancel.md). Vous ne pouvez pas utiliser un `PaymentIntent` annulé pour effectuer des paiements. **Encaissement de fonds incomplet auprès d’un client** - Cause: Failure of the request from your app notifying your back end to capture the payment - 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](https://docs.stripe.com/api/payment_intents/capture.md). ### Encaisser les pourboires (États-Unis uniquement) Aux États-Unis, les utilisateurs admissibles peuvent [collecter un pourboire sur le reçu lors de la capture des paiements](https://docs.stripe.com/terminal/features/collecting-tips/on-receipt.md).