Crear una integración de suscripciones

El SDK para Android de Stripe es de código abierto y está completamente documentado.

Para instalar el SDK, agrega stripe-android al bloque dependencies de tu archivo 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")
}

Configura el SDK con tu clave publicable de Stripe para que pueda hacer solicitudes a la API de Stripe, así como en tu subclase Application:

import com.stripe.android.PaymentConfiguration

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

Y, después, instala la CLI de Stripe. La CLI te permite hacer pruebas de webhooks y puedes ejecutarla para que la API haga llamadas a Stripe. En esta guía, se muestra cómo utilizar la CLI para configurar un modelo de tarifas en una sección posterior.

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

# Connect the CLI to your dashboard
stripe login

Para obtener más opciones de instalación, consulta Empezar a usar la CLI de Stripe.

Crea los productos con sus precios en el Dashboard o con la CLI de Stripe.

Este ejemplo utiliza un servicio de precio fijo con dos niveles de servicio diferentes: básico y prémium. Para cada opción de nivel de servicio, debes crear un producto y un precio recurrente. (Si quieres agregar un cargo puntual, como el costo de instalación, crea un tercer producto con un precio puntual. Para simplificar, este ejemplo no incluye un cargo puntual).

En este ejemplo, cada producto se factura mensualmente. El precio del producto básico es del 5 USD. El precio del producto prémium es del 15 USD.

Stripe requiere un cliente para cada suscripción. En el front-end de tu aplicación, recopila toda la información necesaria de tus usuarios y envíala al back-end.

Es posible que desees usar una biblioteca de la red para enviar solicitudes de red a tu back-end. Este documento utiliza okhttp, pero puedes utilizar cualquier biblioteca que funcione mejor en tu proyecto.

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

Si necesitas recopilar datos de la dirección, el Address Element te permite recopilar una dirección de envío o facturación para tus clientes. Para obtener más información sobre el Address Element, visita la página de 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")
        }
    }
}

Crea el “Customer Object” de Stripe en el servidor.

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

Permite que tu nuevo cliente elija un plan y luego cree la suscripción. En esta guía, elegirá entre un plan Básico y un plan Prémium.

En tu aplicación, envía el ID de precio seleccionado y el ID del registro del cliente al 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
}

En el back-end, crea una suscripción con estado incomplete usando payment_behavior=default_incomplete. Luego, devuelve el client_secret desde el primer payment intent de la suscripción al front-end para completar el pago expandiendo el confirmation_secret en la factura más reciente de la suscripción.

To enable improved subscription behavior, set billing_mode[type] to flexible. You must use Stripe API version 2025-06-30.basil or later.

Establece save_default_payment_method en on_subscription para guardar el método de pago como predeterminado para una suscripción cuando un pago se realiza correctamente. Guardar un método de pago predeterminado aumenta la tasa de éxito de futuros pagos de suscripción.

# 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

En este punto, Subscription está inactive y en espera del pago. Veamos un ejemplo. Los campos básicos que se deben almacenar aparecen resaltados, pero debes almacenar todos los campos a los que tu aplicación suela acceder.

{
  "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.

Agregar el Payment Element a tu aplicación

Inicializa y presenta el Payment Element móvil usando la clase 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")
        }
    }
}

El Payment Element móvil renderiza una hoja que le permite a tu cliente seleccionar un método de pago. El formulario recopila automáticamente todos los datos de pago necesarios para el método de pago que elijan.

Establecer allowsDelayedPaymentMethods en true permite aceptar métodos de pago de notificación diferida como cuentas bancarias en EE. UU. Para estos métodos de pago, el estado final del pago no se conoce cuando se completa el PaymentSheet, sino que se efectúa con éxito o falla más tarde. Si aceptas este tipo de métodos de pago, infórmale al cliente que su pedido está confirmado y solo finalízalo (por ejemplo, envía el producto) cuando el pago se realice correctamente.

Puedes personalizar el Payment Element para que coincida con el diseño de tu aplicación usando la propiedad appearance en tu objeto PaymentSheet.Configuration.

Confirmar pago

El Payment Element móvil crea un PaymentMethod y confirma que el primer PaymentIntent de la suscripción está incompleto, lo que genera un cargo. Si se requiere autenticación reforzada de clientes (SCA) para el pago, el Payment Element se encarga del proceso de autenticación antes de confirmar el PaymentIntent.

Para completar la integración, tienes que procesar los webhooks que envió Stripe. Estos son eventos que se originan cada vez que un estado dentro de Stripe cambia, por ejemplo, cuando las suscripciones crean facturas nuevas. En tu aplicación, configura un controlador de HTTP para aceptar una solicitud POST que contenga el evento de webhook y verifica la firma del evento:

# 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?

Durante el desarrollo, usa la CLI de Stripe para observar los webhooks y reenviarlos a tu aplicación. Ejecuta lo siguiente en una nueva terminal mientras tu aplicación de desarrollo está funcionando:

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

Para la producción, configura una URL de punto de conexión de webhook en el Dashboard o utiliza la API Webhook Endpoints.

Necesita escuchar algunos eventos para completar los pasos restantes de esta guía. Consulte Eventos de suscripción para más detalles sobre los webhooks específicos de suscripción.

Ahora que la suscripción está activa, bríndales a los usuarios acceso a tu servicio. Para ello, escucha los eventos customer.subscription.created, customer.subscription.updated y customer.subscription.deleted. Estos eventos muestran un objeto de suscripción que contiene el campo status que indica si la suscripción está activa, vencida o cancelada. Consulta el ciclo de vida de la suscripción para obtener una lista completa de los estados.

En tu controlador de webhook:

1. Verifica el estado de la suscripción. Si está active entonces el usuario pagó por tu producto.
2. Revisa el producto al que se suscribió el cliente y bríndale acceso al servicio. Es mejor revisar el producto que el precio porque te da más flexibilidad en caso de que necesites cambiar la tarifa o el intervalo de facturación.
3. Almacena el product.id, subscription.id y subscription.status en tu base de datos junto con el customer.id que ya has guardado. Comprueba este registro al determinar qué características habilitar para el usuario en la aplicación.

El estado de una suscripción puede cambiar en cualquier momento de su ciclo de vida, incluso si tu aplicación no hace ninguna llamada directa a Stripe. Por ejemplo, se puede producir un error de renovación debido a una tarjeta de crédito vencida, lo que genera que el estado de la suscripción pase a vencido. O bien, si implementas el portal de clientes, un usuario puede cancelar su suscripción sin visitar directamente tu aplicación. El uso correcto del controlador mantiene el estado de tu aplicación sincronizado con Stripe.

Con frecuencia, se les permite a los clientes cancelar su suscripción. En este ejemplo, se agrega la opción de cancelación en la página de configuración de la cuenta.

En este ejemplo, el ID de la suscripción se recopila en el front-end, pero tu aplicación puede obtener esta información de tu base de datos para el usuario que ha iniciado sesión.

Configuración de la cuenta con la posibilidad de cancelar la suscripción

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
}

En el back-end, define el punto de conexión para que la aplicación haga la llamada.

# 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

Tu back-end recibe un evento customer.subscription.deleted.

Una vez que se cancela la suscripción, actualiza tu base de datos para eliminar el ID de suscripción de Stripe que estaba almacenado y limitar el acceso al servicio.

Cuando una suscripción se cancela, no se puede reactivar. En su lugar, recopila información de facturación actualizada de tu cliente, actualiza su método de pago predeterminado y crea una nueva suscripción con su registro de cliente existente.

Prueba métodos de pago

Usa la siguiente tabla para probar diferentes métodos y escenarios de pago.

Supervisa eventos

Configura webhooks para recibir notificaciones de los eventos de cambios en las suscripciones, como actualizaciones y cancelaciones. Obtén más información sobre los webhooks de suscripciones. Puedes ver los eventos en el Dashboard o con la CLI de Stripe.

Para obtener más detalles, consulta cómo probar tu integración con Billing.