Configurer de futurs paiements par carte

Pour commencer, vous devez créer un compte Stripe.

Côté serveur

Pour cette intégration, votre serveur doit disposer de endpoints qui communiquent avec l’API Stripe. Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre serveur :

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Côté client

Le SDK Stripe Android est disponible en open source et fait l’objet d’une documentation complète.

Pour installer le SDK, ajoutez stripe-android au bloc dependencies de votre fichier app/build.gradle :

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

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:21.20.2")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:21.20.2")
}

Configurez le SDK avec votre clé publique Stripe de façon à ce qu’il puisse envoyer des requêtes à l’API Stripe, par exemple à la sous-classe Application :

import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        )
    }
}

Pour configurer une carte bancaire en vue de paiements futurs, vous devez l’associer à un client. Lorsque votre client ouvre un compte chez vous, créez un objet Customer, qui permet de réutiliser des moyens de paiement et d’assurer le suivi de plusieurs paiements.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jennyrosen@example.com"

Lorsque la création aboutit, l’objet Customer est renvoyé. Vous pouvez l’examiner pour identifier l’id du client et stocker cette valeur dans votre base de données pour la récupérer ultérieurement.

Vous pouvez trouver ces clients sur la page Clients du Dashboard.

Un SetupIntent est un objet qui représente votre intention de configurer un moyen de paiement pour encaisser de futurs paiements.

Cet objet contient la clé secrète du client, une clé unique que vous devez transmettre à votre application. Cette clé vous permet de réaliser diverses actions sur le client, comme confirmer la configuration et mettre à jour les informations du moyen de paiement, tout en masquant des données sensibles comme l’attribut customer. Vous pouvez également utiliser la clé secrète du client pour valider et authentifier les informations de carte par l’intermédiaire des réseaux de cartes de crédit. La clé secrète du client est une information sensible : ne la consignez pas, ne l’intégrez pas dans une URL et ne l’exposez à personne d’autre qu’au client.

Côté serveur

Sur votre serveur, créez un endpoint qui crée lui-même un SetupIntent et renvoie la clé secrète du client à votre application.

curl https://api.stripe.com/v1/setup_intents/ \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer"="{{CUSTOMER_ID}}"

Si vous prévoyez d’utiliser la carte pour des paiements futurs uniquement lorsque votre client est présent dans le tunnel de paiement, configurez le paramètre utilisation sur la valeur on_session afin d’optimiser votre taux d’autorisation.

Côté client

Côté client, demandez un SetupIntent auprès de votre serveur.

class CheckoutActivity : AppCompatActivity() {
   private lateinit var setupIntentClientSecret: String

   private fun loadPage() {
       // Request a SetupIntent from your server and store its client secret
       // Click View full sample to see a complete implementation
   }
}

Lorsque votre client soumet le formulaire de paiement, collectez ses informations de carte à l’aide du CardInputWidget, un composant d’interface utilisateur prêt à l’emploi fourni par le SDK, qui collecte le numéro de carte, la date d’expiration, le CVC et le code postal.

Appelez la méthode getPaymentMethodCard pour récupérer les informations de carte bancaire de votre client. Transmettez les informations collectées à de nouvelles instances de PaymentMethodCreateParams et PaymentMethod.BillingDetails pour créer une instance de ConfirmSetupIntentParams.

// Collect card details
val cardInputWidget =
    findViewById<CardInputWidget>(R.id.cardInputWidget)
val paymentMethodCard = cardInputWidget.paymentMethodCard

// Later, you will need to attach the PaymentMethod to the Customer it belongs to.
// This example collects the customer's email to know which customer the PaymentMethod belongs to, but your app might use an account id, session cookie, and so on.
val emailInput = findViewById<EditText>(R.id.emailInput)
val billingDetails = PaymentMethod.BillingDetails.Builder()
    .setEmail((emailInput.text ?: "").toString())
    .build()

// Create SetupIntent confirm parameters with the above
if (paymentMethodCard != null) {
    val paymentMethodParams = PaymentMethodCreateParams
        .create(paymentMethodCard, billingDetails, null)
    val confirmParams = ConfirmSetupIntentParams
        .create(paymentMethodParams, setupIntentClientSecret)
    lifecycleScope.launch {
        paymentLauncher.confirm(confirmParams)
    }
}

Pour terminer la configuration, transmettez l’objet SetupIntentParamsavec l’activité en cours à la méthode confirm de PaymentLauncher. Le SetupIntent vérifie que les informations de carte de votre client sont valides sur le réseau. Toutefois, cette vérification automatique n’est pas systématique. Pour plus d’informations à ce sujet, consultez la page Vérifier la validité d’une carte bancaire sans la débiter. Par ailleurs, ne conservez pas trop longtemps des SetupIntents non gérés, car ils risquent de ne plus être valides lors de l’appel de la méthode PaymentLauncher#confirm().

Certains moyens de paiement requièrent des étapes d’authentification supplémentaires pour finaliser un paiement. Le SDK gère le flux de confirmation de paiement et d’authentification, ce qui peut impliquer d’afficher des écrans supplémentaires, nécessaires pour l’authentification. Pour plus d’informations sur l’authentification 3D Secure et la personnalisation de l’expérience d’authentification, consultez la page Prise en charge de l’authentification 3D Secure sur Android.

Le résultat du flux est renvoyé à votre activité appelante par le rappel fourni, ici onPaymentResult. Le PaymentResult renvoyé par le PaymentLauncher présente les types suivants :

• Completed : confirmation ou authentification réussie
• Canceled : le client a annulé l’authentification requise
• Failed : la tentative d’authentification a échoué, au motif indiqué par la propriété throwable

private fun onPaymentResult(paymentResult: PaymentResult) {
    var title = ""
    var message = ""
    var restartDemo = false
    when (paymentResult) {
        is PaymentResult.Completed -> {
            title = "Setup Completed"
            restartDemo = true
        }
        is PaymentResult.Canceled -> {
            title = "Setup Canceled"
        }
        is PaymentResult.Failed -> {
            title = "Setup Failed"
            message = paymentResult.throwable.message!!
        }
    }
    displayAlert(title, message, restartDemo)
}

Vous disposez désormais d’un flux permettant de recueillir les informations de carte et de gérer les éventuelles demandes d’authentification. Utilisez la carte de test 4000 0025 0000 3155, ainsi qu’un CVC, un code postal et une date d’expiration postérieure à la date du jour pour tester le processus d’authentification.

Lorsque le SetupIntent aboutit, l’ID PaymentMethod généré (dans setupIntent.getPaymentMethodId()) est enregistré dans l’objet Customer fourni.

Au moment de débiter votre client hors session, utilisez les ID de client et de PaymentMethod afin de créer un PaymentIntent. Pour trouver une carte à débiter, listez les PaymentMethods associés à votre client.

curl -G https://api.stripe.com/v1/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d type=card

Lorsque vous avez les identifiants Client et PaymentMethod, créez un PaymentIntent avec le montant et la devise du paiement. Réglez quelques autres paramètres pour effectuer un paiement hors session :

• Assignez la valeur true à off_session afin d’indiquer que le client n’est pas dans votre tunnel de paiement lors de cette tentative de paiement. Si une authentification est requise, le PaymentIntent générera une erreur.
• Assignez la valeur true à la propriété confirm du PaymentIntent, ce qui aura pour effet de générer immédiatement une confirmation lors de la création du PaymentIntent.
• Renseignez l’ID du PaymentMethod dans payment_method et l’ID du client dans customer.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d amount=1099 \
  -d currency=usd \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d off_session=true \
  -d confirm=true

Inspectez la propriété d’état du PaymentIntent pour confirmer que le paiement a été effectué avec succès. Si la tentative de paiement a réussi, l’état du PaymentIntent est succeeded et que le est terminé.

Démarrer un flux de récupération

Si l’état de l’objet PaymentIntent est différent, le paiement n’a pas abouti et la requête échoue. Invitez votre client à revenir dans l’application (par e-mail, SMS ou notification Push, par exemple) afin de terminer le paiement. Nous vous recommandons de créer dans votre application un flux de récupération indiquant le motif de l’échec du paiement initial et permettant au client de réessayer.

Dans votre flux de récupération, récupérez l’objet PaymentIntent via sa clé secrète du client. Vérifiez la valeur lastPaymentError du PaymentIntent pour découvrir pourquoi la tentative de paiement a échoué. Pour les erreurs de carte, vous pouvez montrer à l’utilisateur le dernier message d’erreur du paiement. Sinon, vous pouvez afficher un message d’échec générique.

fun startRecoveryFlow(clientSecret: String) {
    val stripe = Stripe(
        applicationContext,
        PaymentConfiguration.getInstance(applicationContext).publishableKey
    )
    lifecycleScope.launch {
        runCatching {
            stripe.retrievePaymentIntent(clientSecret)
        }.fold(
            onSuccess = { paymentIntent ->
                var failureReason =
                    "Payment failed, try again" // Default to a generic error message
                paymentIntent.lastPaymentError?.let { lastPaymentError ->
                    if (lastPaymentError.type == PaymentIntent.Error.Type.CardError) {
                        lastPaymentError.message?.let { errorMessage ->
                            failureReason = errorMessage
                            // Display the failure reason to your customer
                        }
                    }
                }
            },
            onFailure = {
                // Handle error
            }
        )
    }
}

Permettre au client de réessayer

Votre flux de récupération doit permettre au client de mettre à jour ou supprimer sa carte enregistrée et de réessayer le paiement. Suivez les mêmes étapes que pour l’acceptation du paiement d’origine, à une différence près : confirmez l’objet PaymentIntent d’origine qui a échoué en réutilisant sa clé secrète de client plutôt que d’en créer une nouvelle.

Si le paiement échoue parce qu’il nécessite une authentification, réessayez avec l’objet PaymentMethod existant plutôt que d’en créer un nouveau.

fun startRecoveryFlow(clientSecret: String) {
    // ...continued from previous step
    val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext)
    val paymentLauncher = PaymentLauncher.Companion.create(
        this,
        paymentConfiguration.publishableKey,
        paymentConfiguration.stripeAccountId,
        ::onPaymentResult
    )

    val lastPaymentError = paymentIntent.lastPaymentError
    val lastPaymentMethodId = lastPaymentError.paymentMethod?.id
    if (lastPaymentError?.code == "authentication_required" && lastPaymentMethodId != null) {
        // Payment failed because authentication is required, reuse the PaymentMethod
        val paymentIntentParams =
            ConfirmPaymentIntentParams.createWithPaymentMethodId(
                lastPaymentMethodId,
                clientSecret // Reuse the existing PaymentIntent
            )
        // Submit the payment...
        paymentLauncher.confirm(paymentIntentParams)
    } else {
        // Collect a new PaymentMethod from the customer...
    }
}

À ce stade, vous devriez avoir une intégration qui :

1. Collecte les informations de carte bancaire sans débiter le client avec un SetupIntent
2. Débite la carte hors session et dispose d’un flux de récupération permettant de gérer les refus de paiement et les demandes d’authentification

Pour vérifier que votre intégration est prête, vous avez à votre disposition plusieurs cartes de test. Vous pouvez les utiliser en mode test avec n’importe quel CVC, code postal et date d’expiration non échue.

Voir la liste complète des cartes de test.