Créer une intégration pour les abonnements

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.26.1")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:21.26.1")
}

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"
        )
    }
}

Installez ensuite l’interface de ligne de commande Stripe. Cette dernière vous permet d’exécuter les tests webhook dont vous avez besoin, et d’exécuter des appels à l’API vers Stripe. Ce guide vous explique dans une section ultérieure comment utiliser l’interface de ligne de commande pour définir un modèle tarifaire.

# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

Pour davantage d’options d’installation, consultez la page consacrée à l’interface de ligne de commande Stripe.

Créez vos produits et leurs tarifs dans le Dashboard ou via l’interface de ligne de commande Stripe.

Cet exemple utilise un service à tarif fixe avec deux options de niveau de service différentes : Basic et Premium. Pour chaque option de niveau de service, vous devez créer un produit et un tarif récurrent. (Si vous souhaitez ajouter un paiement ponctuel, par exemple des frais d’installation, créez un troisième produit avec un tarif unique. Par souci de simplicité, cet exemple n’inclut pas de paiement ponctuels.)

Dans cet exemple, chaque produit est facturé mensuellement. Le tarif du produit de base est de 5 USD. Celui du produit premium est de 15 USD.

Stripe a besoin d’un objet Customer pour chaque abonnement. Sur le front-end de votre application, collectez toutes les informations nécessaires sur vos utilisateurs et transmettez-les à votre back-end.

Utilisez une bibliothèque réseau pour envoyer des requêtes réseau à votre back-end. Ce document utilise okhttp, mais vous pouvez utiliser n’importe quelle bibliothèque adaptée à votre projet.

dependencies {
  ...
  implementation "com.squareup.okhttp3:okhttp:4.12.0"
}

Si vous avez besoin de recueillir une adresse, le composant Address Element vous permet de recueillir l’adresse de livraison ou de facturation de vos clients. Pour plus d’informations sur ce composant, consultez la page consacrée à Address Element.

import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

@Composable
fun RegisterView() {
    var email by remember { mutableStateOf("") }
    Column {
        OutlinedTextField(value = email,
            label = { Text(text = "Email") },
            onValueChange = { email = it })
        Button(onClick = {
            val body = JSONObject().put("email", email).toString()
                .toRequestBody("application/json".toMediaType())
            val request =
                Request.Builder().url("http://10.0.2.2:4567/create-customer").post(body).build()
            CoroutineScope(Dispatchers.IO).launch {
                OkHttpClient().newCall(request).execute().use { response ->
                    if (response.isSuccessful) {
                        println(JSONObject(response.body!!.string()).get("customer"))
                    }
                }
            }
        }) {
            Text(text = "Submit")
        }
    }
}

Sur le serveur, créez l’objet Customer Stripe.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

Laissez votre nouveau client choisir une offre, puis créez l’abonnement. Dans ce guide, le client a le choix entre l’option de base et l’option Premium.

Dans votre application, transmettez l’ID du tarif sélectionné et l’ID du dossier client à votre back-end.

import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

fun createSubscription(priceId: String, customerId: String): SubscriptionResponse? {
    val body = JSONObject()
        .put("priceId", priceId)
        .put("customerId", customerId).toString()
        .toRequestBody("application/json".toMediaType())
    val request =
        Request.Builder().url("http://10.0.2.2:4567/create-subscription").post(body).build()
    OkHttpClient().newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            // SubscriptionsResponse is data class conforming to the expected response from your backend.
            // It should include the client_secret, as discussed below.
            return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java)
        }
    }
    return null
}

Sur votre back-end, créez l’abonnement à l’état incomplete à l’aide de payment_behavior=default_incomplete. Renvoyez ensuite le client_secret du premier PaymentIntent de l’abonnement vers le front-end pour finaliser le paiement en développant le confirmation_secret sur la dernière facture de l’abonnement.

Pour activer comportement d’abonnement amélioré, définissez billing_mode[type] sur flexible. Vous devez utiliser Stripe API version 2025-06-30.basil ou une version ultérieure.

Définissez save_default_payment_method sur on_subscription afin d’enregistrer un moyen de paiement comme moyen de paiement par défaut pour l’abonnement lorsque le paiement aboutit. L’enregistrement d’un moyen de paiement par défaut augmente le taux de réussite des paiements futurs.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    billing_mode: {type: 'flexible'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

À ce stade, l’abonnement est inactive et en attente de paiement. Voici un exemple de réponse. Les champs à sauvegarder impérativement sont en surbrillance, mais vous devez également sauvegarder tous les éléments auxquels votre application accède fréquemment.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Use the Payment Sheet to collect payment details and activate the subscription. You can customize Elements to match the look and feel of your application.

The Payment Sheet securely collects all necessary payment details for a wide variety of payments methods. Learn about the supported payment methods for Payment Sheet and Subscriptions.

Ajouter le composant Payment Element à votre application

Initialiser et présenter le composant Mobile Payment Element à l’aide de la classe PaymentSheet.

import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
import com.stripe.android.paymentsheet.rememberPaymentSheet

@Composable
fun SubscribeView(clientSecret: String) {
    val paymentSheet = rememberPaymentSheet(::onPaymentSheetResult)

    Button(onClick = {
        paymentSheet.presentWithPaymentIntent(
            clientSecret, PaymentSheet.Configuration(
                primaryButtonLabel = "Subscribe for $15/month",
                merchantDisplayName = "My merchant name",
                // Set `allowsDelayedPaymentMethods` to true if your business handles
                // delayed notification payment methods like US bank accounts.
                allowsDelayedPaymentMethods = true
            )
        )
    }) {
        Text(text = "Subscribe")
    }
}

fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    when (paymentSheetResult) {
        is PaymentSheetResult.Canceled -> {
            print("Canceled")
        }

        is PaymentSheetResult.Failed -> {
            print("Error: ${paymentSheetResult.error}")
        }

        is PaymentSheetResult.Completed -> {
            // Display for example, an order confirmation screen
            print("Completed")
        }
    }
}

Le composant Mobile Payment Element affiche un formulaire qui permet à votre client de sélectionner un moyen de paiement. Le formulaire collecte automatiquement toutes les informations de paiement requises pour le moyen de paiement sélectionné.

Si vous définissez allowsDelayedPaymentMethods sur true, les moyens de paiement à notification différée, comme les comptes bancaires étasuniens, seront acceptés. Pour ces moyens de paiement, l’état final du paiement n’est pas connu une fois le processus du PaymentSheet achevé, et le paiement peut plus tard aboutir comme échouer. Si vous prenez en charge ces types de moyens de paiement, informez votre client que sa commande est confirmée et ne la traitez (en lui expédiant son produit, par exemple) qu’une fois le paiement reçu.

Vous pouvez personnaliser le composant Payment Element afin qu’il corresponde au design de votre application en utilisant la propriété appearance de votre objet PaymentSheet.Configuration.

Confirmer le paiement

Le composant Mobile Payment Element crée un PaymentMethod et le premier PaymentIntent de l’abonnement incomplet est confirmé, ce qui déclenche le processus de paiement. Si une authentication forte du client (SCA) est requise pour le paiement, le composant Payment Element gère le processus d’authentification avant de confirmer le PaymentIntent.

Afin de compléter votre intégration, vous devez traiter les webhooks envoyés par Stripe. Les webhooks sont des événements qui se déclenchent lorsqu’un état change dans Stripe, par exemple lorsque des abonnements créent de nouvelles factures. Dans votre application, configurez un gestionnaire HTTP de sorte qu’il accepte les requêtes POST contenant l’événement de webhook, et vérifiez la signature de l’événement :

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Pendant le développement, utilisez l’interface de ligne de commande de Stripe pour observer les webhooks et les transférer vers votre application. Exécutez la commande suivante dans un nouveau terminal pendant que votre application de développement est en cours d’exécution :

stripe listen --forward-to localhost:4242/webhook

Pour le mode production, définissez une URL d’endpoint de webhook dans le Dashboard, ou utilisez l’API Webhook Endpoints.

Les étapes restantes de ce guide vont vous amener à écouter quelques événements. Pour plus d’informations sur les webhooks spécifiques aux abonnements, consultez notre documentation consacrée aux événements Subscription.

Maintenant que l’abonnement est actif, fournissez à votre client l’accès à votre service. Pour ce faire, écoutez les événements customer.subscription.created, customer.subscription.updated et customer.subscription.deleted. Ces événements transmettent un objet Subscription, dans lequel un champ status indique si l’abonnement est actif, en retard de paiement ou annulé. Consultez la documentation consacrée au cycle de vie des abonnements pour prendre connaissance de la liste complète des états.

Dans votre gestionnaire de webhooks :

1. Vérifiez l’état de l’abonnement. S’il est active, cela signifie que votre client a payé son abonnement.
2. Vérifiez le produit auquel le client s’est abonné et fournissez l’accès à votre service. Le fait de vérifier le produit plutôt que le tarif vous assure une plus grande souplesse si vous devez modifier la tarification ou la fréquence de facturation.
3. Sauvegardez les product.id, subscription.id et subscription.status dans votre base de données avec le customer.id déjà stocké. Vérifiez ce dossier au moment de décider des fonctionnalités à activer pour l’utilisateur dans votre application.

L’état d’un abonnement peut changer à tout moment de son cycle de vie, même si votre application n’appelle pas directement Stripe. Par exemple, un renouvellement peut échouer en raison d’une carte expirée, ce qui fait passer l’abonnement à l’état « past due ». Ou, si vous implémentez le portail client, un utilisateur peut choisir d’annuler son abonnement sans accéder directement à votre application. L’implémentation correcte de votre gestionnaire permet de synchroniser l’état de votre application avec celui de Stripe.

Il est courant de laisser aux clients la possibilité d’annuler leur abonnement. Cet exemple vous explique comment ajouter une option d’annulation sur la page des paramètres du compte.

Dans cet exemple, l’ID de l’abonnement est collecté sur votre front-end, mais votre application peut obtenir cette information depuis votre base de données pour votre utilisateur connecté.

Paramètres d’un compte ayant la possibilité d’annuler son abonnement

fun cancelSubscription(subscriptionId: String): SubscriptionResponse? {
    val body = JSONObject().put("subscriptionId", subscriptionId).toString()
        .toRequestBody("application/json".toMediaType())
    val request =
        Request.Builder().url("http://10.0.2.2:4567/cancel-subscription").post(body).build()
    OkHttpClient().newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java)
        }
    }
    return null
}

Sur votre back-end, définissez l’endpoint que votre application appellera.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

Votre back-end reçoit un événement customer.subscription.deleted.

Après l’annulation de l’abonnement, mettez à jour votre base de données pour supprimer l’ID de l’abonnement Stripe précédemment sauvegardé, et limitez l’accès à votre service.

Une fois un abonnement annulé, il ne peut plus être réactivé. Collectez dès lors les informations de facturation actualisées de votre client, mettez à jour son moyen de paiement par défaut et créez un nouvel abonnement à partir du dossier client existant.

Tester les moyens de paiement

Utilisez le tableau suivant pour tester différents scénarios et moyens de paiement.

Écouter des événements

Configurez des webhooks afin qu’ils écoutent les événements de modification d’abonnement, tels que les passages à un autre abonnement et les annulations. En savoir plus sur les webhooks d’abonnement. Vous pouvez afficher les événements dans le Dashboard ou à l’aide de la CLI Stripe.

Pour en savoir plus, consultez la page Tester votre intégration Billing.