Encaissement de paiements par carte en mode hors ligneBêta
Le SDK Terminal permet à votre application de continuer à encaisser les paiements à l’aide d’un lecteur mobile sans connexion réseau.
Avertissement
Lorsque vous utilisez le mode hors-ligne, les informations de paiement sont collectées au moment de la vente, et la tentative d’autorisation s’effectue seulement une fois que la connectivité est restaurée et le paiement transféré. C’est vous, en tant qu’utilisateur, qui assumez tous les risques de refus de la transaction. Si la banque émettrice refuse la transaction hors-ligne, vous ne pourrez pas récupérer les fonds et il est possible que le client ne vous règle pas les biens ou services déjà fournis.
Pour limiter les risques de refus de la part de l’émetteur, nous vous conseillons de :
- Rétablir la connexion Internet le plus rapidement possible pour enregistrer les paiements sur Stripe.
- Bloquer les transactions supérieures à un certain montant.
- Faire échouer tous les paiements hors ligne quand le SDK a stocké un ensemble de transactions dont la somme dépasse un certain montant.
Encaisser des paiements en mode hors ligne
Les paiements hors ligne suivent les mêmes étapes que les paiements en ligne : création, collecte, traitement et capture du paiement. Votre appareil peut passer du mode en ligne au mode hors ligne à n’importe quelle étape du processus.
- Activer le mode hors ligne
- Se connecter à un lecteur en mode hors ligne
- Gérer les événements hors ligne
- Créer un Payment Intent en mode hors ligne
- Collecter un moyen de paiement
- Confirmer le paiement
- Attendre l’acheminement des paiements
- Capturer le paiement
- Examiner les paiements hors ligne
Activer le mode hors ligne
Pour utiliser le mode hors ligne, votre application doit utiliser la version 3.3.0 ou plus récente du SDK Terminal iOS .
Utilisez un objet Configuration afin d’activer le mode hors ligne pour les appareils BBPOS Chipper 2X BT, Lecteur Stripe M2 ou BBPOS WisePad 3 dans votre emplacement Location
.
Après avoir activé le mode hors ligne sur un objet Configuration
, vous pouvez l’affecter à un objet Location
. Vous pouvez également activer le mode hors ligne par défaut pour tous les emplacements (Locations
) en mettant à jour l’objet Configuration
par défaut pour votre compte. Les modifications de configuration de l’API peuvent mettre plusieurs minutes à se propager à votre SDK et à votre lecteur. Pour qu’elles soient prises en compte, vous devez vous déconnecter de votre lecteur, puis vous reconnecter.
Se connecter à un lecteur en mode hors ligne
Le SDK stocke localement les informations nécessaires sur Location
après la connexion en ligne. Lors des connexions hors ligne suivantes, il utilise les informations de configuration stockées à partir de cette Location
.
Pour vous connecter à un lecteur en mode hors ligne, vous devez avoir établi une connexion à un lecteur Bluetooth du même type à la mêmeLocation
en étant en ligne au cours des 30 derniers jours et avoir mis à jour le logiciel de votre lecteur dans ce laps de temps. Si vous tentez de vous connecter à un lecteur hors ligne sans remplir ces conditions, la demande échoue avec une erreur.
Erreur | Résolution |
---|---|
Le SDK n’est pas connecté à Internet | Assurez-vous que la Location que vous utilisez est configurée pour le mode hors ligne. Sinon, si votre Location est correctement configurée, votre PDV ne s’est pas encore connecté en ligne à des lecteurs. Vous devez d’abord vous connecter en ligne à un lecteur, puis vous connecter hors ligne à un lecteur du même type. |
Le lecteur sélectionné nécessite une mise à jour logicielle avant de pouvoir être utilisé hors ligne pour collecter des paiements. | Le logiciel du lecteur n’a pas été mis à jour depuis 30 jours ou plus. Connectez-vous au lecteur en ligne pour le mettre à jour. |
Le lecteur sélectionné doit être appairé en ligne à cet endroit avant de pouvoir être utilisé hors ligne pour collecter des paiements. | Vous essayez de vous connecter à un type de lecteur auquel votre PDV ne s’est pas encore connecté en ligne. Vous devez d’abord vous connecter en ligne à ce lecteur ou à tout autre lecteur du même type. Si vous voulez vous connecter hors ligne, vous pouvez également vous connecter à un type de lecteur auquel votre PDV s’est déjà connecté en ligne. |
Si vous réinstallez l’application ou effectuez une opération qui vide la mémoire du disque pour le SDK, vous perdez tous les paiements que le SDK a stockés et qui n’ont pas encore été transmis. Assurez-vous qu’aucun paiement n’est stocké avant d’effectuer une action de suppression.
Gérer les événements hors ligneCôté client
Implémentez le protocole OfflineDelegate
et transmettez-le à Terminal pour notifier les événements de type hors ligne à votre application. Vous devez configurer OfflineDelegate
avant d’encaisser des paiements hors ligne.
Vous pouvez également interroger Terminal.offlineStatus.sdk.networkStatus
pour connaître l’état actuel du réseau du SDK.
Le SDK tente de transmettre les paiements même si l’état du réseau est hors ligne. Cela signifie que votre fournisseur de tokens de connexion peut recevoir une demande de token de connexion, même si l’état du réseau du SDK est hors ligne. Pendant l’encaissement des paiements, l’état du réseau détermine si le SDK traite le paiement en ligne ou le stocke immédiatement.
Créer un PaymentIntent en mode en ligneCôté client
Afin prendre en charge le fonctionnement hors ligne, vous devez utiliser l’attribut createPaymentIntent
du SDK pour la création d’objets PaymentIntent.
Dans le cadre de transactions hors ligne, les objets PaymentIntent
ont une valeur stripeId
nulle. Nous vous recommandons d’ajouter un identifiant personnalisé aux métadonnées du PaymentIntent pour aider au rapprochement des objets PaymentIntent
créés hors ligne. Vous pouvez utiliser votre identifiant hors ligne dans votre attribut OfflineDelegate.didForwardPaymentIntent
pour corréler les paiements hors ligne aux transferts effectués vers Stripe.
Gérer les risques hors-ligne
L’attribut Terminal.createPaymentIntent
accepte un paramètre de type CreateConfiguration
. Par défaut, tous les paiements hors ligne sont stockés et transférés vers le back-end de Stripe lorsque la connection est rétablie. Vous pouvez passer un objet CreateConfiguration
avec l’attribut offlineBehavior
défini sur REQUIRE_ONLINE
pour faire échouer la transaction en cours si vous opérez hors ligne. Vous pouvez refuser les transactions supérieures à un certain montant ou toutes les transactions hors ligne si le SDK a stocké un ensemble de transactions dont la somme dépasse un certain montant (voir Terminal.offlineStatus.sdk.offlinePaymentAmountsByCurrency
).
Le SDK expose deux propriétés pour vous aider à gérer les risques :
Terminal.offlineStatus.sdk.offlinePaymentsCount
Terminal.offlineStatus.sdk.offlinePaymentAmountsByCurrency
Gérer la latence en mode hors ligne
Par défaut, le SDK Terminal détermine automatiquement si les paiements sont collectés en ligne ou hors ligne en fonction de la connectivité de votre réseau. Cependant, il peut vous arriver de vouloir opérer hors ligne malgré une connexion réseau active (par exemple, si vous devez encaisser des paiements rapidement et que votre connexion réseau est lente). Dans ce cas, vous pouvez transmettre un objet CreateConfiguration
avec l’attribut offlineBehavior
défini sur FORCE_OFFLINE
pour collecter un paiement hors ligne quelle que soit l’état de la connectivité. Notez que les paiements encaissés hors ligne alors que le SDK Terminal dispose d’une connexion réseau active sont transférés en arrière-plan.
Collecter un moyen de paiementCôté client
Il n’est pas possible de lire la bande magnétique d’une carte en mode hors ligne. La lecture sans contact n’est pas non plus prise en charge dans les régions où l’authentification forte du client est requise. Utilisez la méthode BluetoothReaderDelegate didRequestReaderInput pour afficher les options de présentation de carte valides au client. L’utilisation du paramètre initWithUpdatePaymentIntent
dans CollectConfiguration
est désactivée lorsque le mode hors ligne est activé sauf si offlineBehavior
est défini sur REQUIRE_ONLINE
.
Note
La responsabilité du paiement vous incombe lorsque vous utilisez votre lecteur hors-ligne. Les données de bande magnétique étant faciles à usurper, Stripe désactive cette option pour les paiements hors-ligne.
Confirmer le paiementCôté client
Cette étape est semblable à la confirmation de paiements en ligne. La principale différence est que votre intégration doit gérer des types d’erreurs spécifiques au mode hors ligne, par exemple lorsque la transaction dépasse la limite maximum de 10 000 USD appliquée par Stripe pour les paiements hors ligne (ou un montant équivalent dans votre devise).
Dans certains cas, le SDK peut créer en ligne un PaymentIntent
, mais le confirmer hors ligne. Dans ce cas, le PaymentIntent
peut avoir un stripeId
non nul. Vous pouvez vérifier offlineDetails.storedAt
pour déterminer s’il a été confirmé hors ligne.
Fourniture de reçus
Vous pouvez avoir besoin d’informations concernant la carte utilisée pour un paiement en mode hors ligne. Par exemple, vous pouvez avoir besoin de générer un reçu pour les clients qui le demandent au moment de l’achat.
Si le PaymentIntent est confirmé hors ligne, récupérez son attribut OfflineCardPresentDetails dans la propriété paymentIntent.offlineDetails.offlineCardPresentDetails
.
Ce hachage contient une propriété ReceiptDetails que vous pouvez utiliser pour générer un reçu, ainsi que d’autres informations sur la carte bancaire, notamment sa marque et le nom de son titulaire.
Les informations relatives aux reçus ne sont pas toutes disponibles en mode hors ligne. Les reçus par e-mail préconfigurés sont uniquement envoyés lorsque la connexion est rétablie et que le paiement est capturé.
Attendre l'acheminement des paiementsCôté client
Quand l’accès Internet est rétabli, le SDK commence automatiquement à transférer les paiements hors ligne stockés.
Si vous éteignez votre appareil de PDV trop tôt, vos paiements risquent de ne pas être transférés. Vous pouvez interroger Terminal.offlineStatus.sdk.networkStatus
pour vous assurer que votre PDV est en ligne et qu’il peut transférer les paiements, et Terminal.offlineStatus.sdk.offlinePaymentsCount
pour vérifier le nombre de paiements restant à transférer.
Capturer le paiement
Note
Quand vous êtes hors ligne, vous pouvez créer des PaymentIntents avec l’attribut captureMethod
défini sur automatic
. Une fois confirmés, ces PaymentIntents passent à l’état Succeeded
au lieu de RequiresCapture
, car ils sont capturés automatiquement lors du transfert.
Les paiements acheminés et autorisés doivent alors être capturés depuis votre back-end ou votre application :
- Pour capturer les paiements depuis votre back-end, utilisez des webhooks afin d’écouter les PaymentIntents à l’état
requires_capture
. - Pour capturer les paiements depuis votre application, attendez les appels à votre
OfflineDelegate.didForwardPayment
pour chaque PaymentIntent transmis. Un PaymentIntent peut être capturé si son état estRequiresCapture
.
Si votre application détermine quand capturer un PaymentIntent après confirmPaymentIntent
, ceux-ci peuvent être capturés s’ils sont à l’état RequiresCapture
et si le paramètre offlineDetails
est vide, ou si son attribut requiresUpload
a la valeur NO
.
Capturez un paiement après confirmPaymentIntent
, s’il est confirmé en ligne :
Capturez un paiement hors ligne après qu’il a été transféré dans le didForwardPaymentIntent
de votre OfflineDelegate :
Examiner les paiements collectés hors ligne
Après l’autorisation, vous pouvez utiliser l’API PaymentIntents pour examiner les détails hors ligne d’un paiement. Accédez aux informations du moyen de paiement du dernier objet Charge d’un PaymentIntent
pour déterminer s’il a été encaissé hors ligne.