Configurer votre intégration

Pour installer le SDK, ajoutez stripeterminal au bloc dependencies du fichier build de votre application :

plugins {
  id("com.android.application")
}

android { ... }

dependencies {
  implementation("com.stripe:stripeterminal:5.1.0")
  // ...
}

(Facultatif) Prise en charge des coroutines Kotlin

SDK version 5.0.0 includes an optional module, stripeterminal-ktx. This module provides suspend function wrappers for asynchronous Terminal APIs, allowing you to write simple, sequential code instead of nesting callbacks.

Pour l’utiliser, ajoutez sa dépendance :

dependencies {
  implementation("com.stripe:stripeterminal:5.1.0")
  // Add the coroutines module
  implementation("com.stripe:stripeterminal-ktx:5.1.0")
  // ...
}

Voir un exemple de ce modèle d’intégration dans notre application Kotlin exemple sur GitHub.

Définir la version Java cible

Ensuite, étant donné que le SDK repose sur Java 8, le fichier de build de votre application doit l’indiquer en précisant la version Java cible :

android {
  // ...
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Vous devez activer l’autorisation ACCESS_FINE_LOCATION. Pour connecter un lecteur Bluetooth, vous devez également activer les autorisations Bluetooth. Ajoutez les autorisations appropriées à votre manifeste, comme indiqué ici :

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

Avant d’initialiser l’objet Terminal, ajoutez la vérification suivante afin de vérifier que l’autorisation ACCESS_FINE_LOCATION est activée dans votre application :

if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
    val permissions = arrayOf(android.Manifest.permission.ACCESS_FINE_LOCATION)
    ActivityCompat.requestPermissions(this, permissions, REQUEST_CODE_LOCATION)
}

Vérifiez également que l’utilisateur de l’application accorde l’autorisation d’accéder aux emplacements ; le SDK ne peut fonctionner sans elle. À cet effet, remplacez la méthode onRequestPermissionsResult dans votre application et vérifiez le résultat de l’autorisation.

override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)

    if (requestCode == REQUEST_CODE_LOCATION && grantResults.isNotEmpty()
        && grantResults[0] != PackageManager.PERMISSION_GRANTED
    ) {
        throw RuntimeException("Location services are required to connect to a reader.")
    }
}

Vous devez également vous assurer que les services de localisation et de Bluetooth sont activés sur l’appareil, et pas seulement pour l’application. Voici un exemple de ce à quoi cela peut ressembler dans les paramètres de l’appareil :

Paramètres d’emplacement

Paramètres Bluetooth

Côté serveur

Pour se connecter à un lecteur, votre back-end doit donner au SDK la permission d’utiliser le lecteur avec votre compte Stripe en lui fournissant la clé secrète d’un ConnectionToken. Votre back-end doit créer des tokens de connexion uniquement pour les clients qu’il reconnaît comme fiables.

curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

Obtenez la clé secrète à partir du ConnectionToken sur votre serveur et transmettez-la côté client.

post '/connection_token' do
  token = # ... Create or retrieve the ConnectionToken
  {secret: token.secret}.to_json
end

Côté client

Afin de permettre au SDK d’accéder à cet endpoint, déployez l’interface ConnectionTokenProvider dans votre application. Celle-ci définit une fonction unique qui demande un ConnectionToken à votre back-end.

class CustomConnectionTokenProvider : ConnectionTokenProvider {
    override fun fetchConnectionToken(callback: ConnectionTokenCallback) {
        try {
            // Your backend should call /v1/terminal/connection_tokens and return the
            // JSON response from Stripe. When the request to your backend succeeds,
            // return the `secret` from the response to the SDK.
            callback.onSuccess(secret)
        } catch (e: Exception) {
            callback.onFailure(
                ConnectionTokenException("Failed to fetch connection token", e)
            )
        }
    }
}

Cette fonction est appelée dès lors que le SDK doit s’authentifier auprès de Stripe ou du lecteur. Elle est également appelée lorsqu’un nouveau token est nécessaire pour se connecter à un lecteur (par exemple, lorsque votre application s’est déconnectée du lecteur). Si le SDK n’est pas en mesure de récupérer un nouveau jeton de connexion depuis votre backend, la connexion au lecteur échoue associée à une erreur de votre serveur.

Le SDK Android est sensible au cycle de vie. Pour éviter les fuites de mémoire et garantir un nettoyage approprié des processus de longue durée du SDK Terminal, votre application doit implémenter une sous-classe Application qui utilise TerminalApplicationDelegate.onCreate() pour informer le SDK des événements de cycle de vie.

// Substitute with your application name, and remember to keep it the same as your AndroidManifest.xml
class StripeTerminalApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        TerminalApplicationDelegate.onCreate(this)
    }
}

La classe Terminal mise à disposition par le SDK Stripe Terminal dispose d’une interface générique permettant de détecter les lecteurs, de se connecter à un lecteur et d’effectuer des opérations sur le lecteur, telles que l’affichage des informations du panier, l’encaissement de paiements et l’enregistrement de cartes bancaires pour une utilisation ultérieure.

Pour commencer, fournissez le contexte actuel de l’application, le ConnectionTokenProvider implémenté à l’Étape 3 et un objet TerminalListener. Vous pouvez utiliser cet écouteur pour gérer des événements tels que des paiements et des mises à jour de l’état de la connexion à partir du SDK.

// Create your listener object. Override any methods that you want to be notified about
val listener = object : TerminalListener {
    override fun onConnectionStatusChange(status: ConnectionStatus) {
        println("onConnectionStatusChange: $status");
    }

    override fun onPaymentStatusChange(status: PaymentStatus) {
        println("onPaymentStatusChange: $status");
    }
}

// Choose the level of messages that should be logged to your console
val logLevel = LogLevel.VERBOSE

// Create your token provider.
val tokenProvider = CustomConnectionTokenProvider()

// Pass in the current application context, your desired logging level, your token provider, and the listener you created
if (!Terminal.isInitialized()) {
    Terminal.init(applicationContext, logLevel, tokenProvider, listener, offlineListener)
}

// Since the Terminal is a singleton, you can call getInstance whenever you need it
Terminal.getInstance()