Encaissement de paiements par carte en mode hors ligne

Pour utiliser le mode hors ligne, votre application doit utiliser la version 3.3.0 ou une version ultérieure du SDK Terminal iOS.

Utilisez un objet Configuration ou le Dashboard afin d’activer le mode hors ligne pour les appareils pris en charge dans votre Location.

curl https://api.stripe.com/v1/terminal/configurations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "offline[enabled]"=true

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 de votre compte. La propagation des modifications apportées à l’API Configuration vers votre SDK et votre lecteur peut prendre quelques minutes. Pour qu’elles soient prises en compte, vous devez vous déconnecter puis vous reconnecter à votre lecteur.

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 cet emplacementLocation.

Pour encaisser des paiements à l’aide d’un lecteur intelligent en mode hors ligne, vous devez avoir établi une connexion à un lecteur mobile du même type au même emplacement (Location) 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.

Si vous réinstallez l’application ou effectuez une opération qui vide la mémoire du disque pour le SDK (comme l’effacement du cache de votre application de point de vente dans les paramètres de l’appareil de point de vente), 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.

Pour permettre à votre application de recevoir des mises à jour sur l’état du réseau du SDK et des paiements transmis, implémentez le protocole OfflineDelegateet transmettez-le au SDK Terminal. Vous devez définir OfflineDelegate avant de collecter les paiements en mode hors ligne.

import StripeTerminal

class CustomOfflineDelegate: OfflineDelegate {

    func terminal(_ terminal: Terminal, didChangeOfflineStatus offlineStatus: OfflineStatus) {
        // Check the value of `offlineStatus` and update your UI accordingly. For instance,
        // you can check the SDK's network status at `offlineStatus.sdk.networkStatus`.
        //
        // You can also check the SDK's current offline status using
        // `Terminal.shared.offlineStatus.sdk.networkStatus`.
    }

    func terminal(_ terminal: Terminal, didForwardPaymentIntent intent: PaymentIntent, error: Error?) {
        // The PaymentIntent was successfully forwarded, or an error occurred.
        // Reconcile any local state using the backend-generated `PaymentIntent.stripeId`
        // and the metadata you supplied when creating the PaymentIntent.
        //
        // Note that the `PaymentIntent.stripeId` may still be nil if creating the
        // PaymentIntent in the backend failed.
    }

    func terminal(_ terminal: Terminal, didReportForwardingError error: Error) {
        // A non-specific error occurred while forwarding a PaymentIntent.
        // Check the error message and your integration implementation to
        // troubleshoot.
    }
}

import UIKit
import StripeTerminal

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Terminal.setTokenProvider(APIClient.shared)
        Terminal.shared.offlineDelegate = CustomOfflineDelegate()
        // ...
        return true
    }

    // ...

}

Afin prendre en charge le fonctionnement hors ligne, utilisez l’attribut createPaymentIntent du SDK pour créer des objets PaymentIntent. Cela permet au SDK de créer des PaymentIntents en mode hors ligne et de les transmettre à Stripe une fois que vous avez rétabli la connexion.

En mode hors ligne, les objets PaymentIntent ont un champ stripeId vide. Nous vous recommandons d’ajouter un identifiant personnalisé aux metadata pour faciliter le rapprochement des objets PaymentIntentcréés hors ligne dans votre base de données.

Une fois que le PaymentIntent a été transmis à Stripe lors de l’étape 7, utilisez votre identifiant personnalisé pour le rapprocher dans le rappel OfflineDelegate.didForwardPaymentIntent.

import UIKit
import StripeTerminal

class PaymentViewController: UIViewController {

    // Action for a "Checkout" button
    func checkoutAction() throws {
        // Populate the correct transaction amount from your application.
        let amount = UInt(10_00)

        // Build up parameters for creating a `PaymentIntent`
        let params = try PaymentIntentParametersBuilder(
            amount: amount,
            currency: "usd"
        )
        .setMetadata(["offlineId": UUID().uuidString])
        .build()

        Terminal.shared.createPaymentIntent(params) { createResult, createError in
            if let error = createError {
                // Handle errors in your application.
                print("createPaymentIntent failed: \(error)")
            } else if let paymentIntent = createResult {
                print("createPaymentIntent succeeded")
                // If the `PaymentIntent` was created offline, its `stripeId` field will be nil.
                if let onlineCreatedId = paymentIntent.stripeId {
                    print("created online");
                } else {
                    print("created offline")
                }
            }
        }
    }
}

Terminal.createPaymentIntent accepte un paramètre CreateConfiguration. Par défaut, si vous êtes en mode hors ligne, le SDK Terminal enregistre tous les paiements hors ligne, puis les transmet au backend de Stripe lorsque la connexion est rétablie.

Pour personnaliser ce comportement, vous pouvez transmettre un objet CreateConfiguration avec un attribut offlineBehavior défini sur REQUIRE_ONLINE, PREFER_ONLINE ou FORCE_OFFLINE.

Gestion du risque

La définition de offlineBehavior sur REQUIRE_ONLINE entraîne un échec de la transaction en cours si vous fonctionnez en mode hors ligne. Par exemple, 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.

Le SDK expose deux propriétés pour vous aider à gérer les risques :

1. Terminal.offlineStatus.sdk.offlinePaymentsCount
2. Terminal.offlineStatus.sdk.offlinePaymentAmountsByCurrency

Gérer la latence en mode hors ligne

En fonction de votre connectivité réseau, le SDK Terminal détermine automatiquement si les paiements sont collectés en ligne ou hors ligne. Cependant, il peut vous arriver de vouloir fonctionner 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). Vous pouvez transmettre un objet CreateConfiguration avec l’attribut offlineBehavior défini sur FORCE_OFFLINE pour collecter un paiement hors ligne quel que soit l’état de la connexion.

Les paiements collectés hors ligne alors que le SDK Terminal dispose d’une connexion réseau active sont transmis en arrière-plan.

import UIKit
import StripeTerminal

class PaymentViewController: UIViewController {

    // Action for a "Checkout" button
    func checkoutAction() throws {
        // ...build up parameters and callback for creating a `PaymentIntent`

        // Your app might want to prevent offline payments for too large an amount.
        // Here, we block the payment if the amount is over 1000 usd.
        // Otherwise, we allow collecting offline if the network connection is unavailable.
        let offlineBehavior: SCPOfflineBehavior = {
            if amount > UInt(1_000_00) {
                return .requireOnline
            } else {
                return .preferOnline
            }
        }()

        let createConfiguration = try CreateConfigurationBuilder().setOfflineBehavior(offlineBehavior).build()
        Terminal.shared.createPaymentIntent(params, createConfig: createConfiguration) { createResult, createError in
            // handle success or failure
        }
    }
}

La collecte des paiements en mode hors ligne est similaire à la collecte des paiements en ligne. Utilisez la méthode didRequestReaderInput pour afficher les options de présentation de carte valides au client.

import UIKit
import StripeTerminal

class PaymentViewController: UIViewController {

    // Action for a "Checkout" button
    func checkoutAction() {
        Terminal.shared.collectPaymentMethod(paymentIntent) { collectResult, collectError in
            if let error = collectError {
                print("collectPaymentMethod failed: \(error)")
            }
            else if let paymentIntent = collectResult {
                print("collectPaymentMethod succeeded")
                // ... Confirm the payment
            }
        }
    }
}

La confirmation des paiements en mode hors ligne est similaire à la confirmation des 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. S’il a été confirmé hors ligne, offlineDetails sera défini et renseigné.

import UIKit
import StripeTerminal

class PaymentViewController: UIViewController {

    // Action for a "Checkout" button
    func checkoutAction() {

        Terminal.shared.confirmPaymentIntent(paymentIntent) { confirmResult, confirmError in
            if let error = confirmError {
                // Handle offline-specific errors in your application (for example,
                // unsupported payment method).
                print("confirmPaymentIntent failed: \(error)")
            } else if let confirmedPaymentIntent= confirmResult {
                print("confirmPaymentIntent succeeded")
                if let offlineDetails = paymentIntent.offlineDetails {
                    print("confirmed offline");
                } else {
                    print("confirmed online")
                }
            }
        }
    }
}

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 sa propriété OfflineCardPresentDetails from the 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 champs des reçus account_type et authorization_response_code ne sont pas disponibles sur les PaymentIntents traités 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é.

Quand l’accès Internet est rétabli, le SDK commence automatiquement à transférer les paiements hors ligne stockés.

Le SDK tente de transmettre les paiements même si l’état de son réseau est hors ligne. Cela signifie que votre fournisseur de tokens de connexion peut recevoir une demande de token de connexion, même lorsque l’appareil est hors ligne.

Si vous éteignez votre appareil de POS 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 POS est en ligne et peut transférer des paiements, et Terminal.offlineStatus.sdk.offlinePaymentsCount pour connaître le nombre de paiements que le SDK Terminal doit transférer.

Lorsque vous êtes hors ligne, vous pouvez créer des PaymentIntents avec l’attribut captureMethod défini sur automatic.

Une fois que vous avez confirmé ces PaymentIntents, ils passent à l’état Succeeded au lieu de RequiresCapture. Stripe capture automatiquement les paiements une fois que vous les avez transmis.

Si vous choisissez la capture manuelle, les paiements acheminés et autorisés doivent alors être capturés depuis votre back-end ou votre application.

• Afin de capturer les paiements depuis votre back-end, utilisez des webhooks pour écouter les PaymentIntents à l’état requires_capture.
• Pour capturer les paiements depuis votre application, attendez que celle-ci reçoive les appels à OfflineDelegate.didForwardPayment pour chaque PaymentIntent à mesure que le SDK les transmet. Un PaymentIntent est prêt à capturer si son état est RequiresCapture et si le paramètre offlineDetails est vide ou présente une valeur requiresUpload de NO .

Terminal.shared.confirmPaymentIntent(paymentIntent) { confirmResult, confirmError in
    if let error = confirmError {
        // Handle offline-specific errors in your application (for example,
        // unsupported payment method).
        print("confirmPaymentIntent failed: \(error)")
    } else if let confirmedPaymentIntent = confirmResult {
        if intent.status == .requiresCapture {
            if let offlineDetails = confirmedPaymentIntent.offlineDetails(),
               offlineDetails.requiresUpload {
                // Offline payment, wait for `didForwardPaymentIntent` (see snippet below)
            } else {
                // Online payment, can be captured now
            }
        }
        // else, handle other intent.status results here
    }
}

Capturez un paiement hors ligne après qu’il ait été transmis par le SDK dans le didForwardPaymentIntent de votre OfflineDelegate :

import StripeTerminal

class CustomOfflineDelegate: OfflineDelegate {
    // ...
    func terminal(_ terminal: Terminal, didForwardPaymentIntent intent: PaymentIntent, error: Error?) {
        if let error = error {
            // Handle the error appropriate for your application
            return
        }

        if intent.status == .requiresCapture {
            // The intent is ready to be captured.
        } else {
            // Handle the intent.status as appropriate.
        }
    }
    // ...
}

Après autorisation, vous pouvez utiliser l’API PaymentIntents pour examiner les informations hors ligne d’un paiement. Accédez aux informations relatives au moyen de paiement sur le dernier objet Charge d’un PaymentIntent pour déterminer s’il a été encaissé hors ligne.