Crear una integración de suscripciones

El SDK para iOS de Stripe es de código abierto, está plenamente documentado y es compatible con aplicaciones que admiten iOS 13 o posterior.

Configura el SDK con tu clave publicable de Stripe al iniciar la aplicación. Esto permite que tu aplicación haga solicitudes a la API de Stripe.

import UIKit
import StripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        StripeAPI.defaultPublishableKey = 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        // do any other necessary launch configuration
        return true
    }
}

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.

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.

struct RegisterView: View {
    @State var email = ""
    var body: some View {
        VStack {
            TextField(text: $email) {
                Text("Email")
            }
            Button {
                Task {
                    var request = URLRequest(url: URL(string: "http://localhost:4242/create-customer")!)
                    request.httpMethod = "POST"
                    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
                    request.httpBody = try! JSONEncoder().encode(["email": email])
                    let (data, _) = try! await URLSession.shared.data(for: request)
                    let responseJSON = try! JSONSerialization.jsonObject(with: data)
                    // Return the customer ID here
                    print(responseJSON["customer"])
                }
            } label: {
                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.

func createSubscription(priceId: String, customerId: String) async -> SubscriptionsResponse {
    var request = URLRequest(url: URL(string: "http://localhost:4242/create-subscription")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try! JSONEncoder().encode(["customerId": customerId, "priceId": priceId])
    let (responseData, _) = try! await URLSession.shared.data(for: request)
    // SubscriptionsResponse is a Decodable struct conforming to the expected response from your backend.
    // It should include the client_secret, as discussed below.
    let subscriptionsResponse = try! JSONDecoder().decode(SubscriptionsResponse.self, from: responseData)
    return subscriptionsResponse
}

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,

Utiliza Payment Sheet para recolectar detalles del pago y activar la suscripción. Puedes personalizar Elements para que coincida con la apariencia de tu solicitud.

Payment Sheet recopila de forma segura todos los detalles de pago necesarios para una amplia variedad de métodos de pago. Más información sobre los métodos de pago admitidos para Payment Sheet y Subscriptions.

Agregar el Payment Element a tu aplicación

Inicializa y presenta el Payment Element móvil usando la clase PaymentSheet.

struct SubscribeView: View {
    let paymentSheet: PaymentSheet
    @State var isPaymentSheetPresented = false
    init(clientSecret: String) {
        var config = PaymentSheet.Configuration()
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        config.allowsDelayedPaymentMethods = true
        config.primaryButtonLabel = "Subscribe for $15/month"
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: clientSecret, configuration: config)
    }
    var body: some View {
        Button {
            isPaymentSheetPresented = true
        } label: {
            Text("Subscribe")
        }.paymentSheet(isPresented: $isPaymentSheetPresented, paymentSheet: paymentSheet) { result in
            switch result {
            case .completed:
                // Handle completion
            case .canceled:
                break
            case .failed(let error):
                // Handle error
            }
        }
    }
}

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.

El cliente puede salir de tu aplicación para autenticarse (por ejemplo, en Safari o en su aplicación bancaria). Para permitirles que regresen automáticamente a tu aplicación después de autenticarse, configura un esquema de URL personalizado y define el delegado de la aplicación para que envíe la URL al SDK. Stripe no admite enlaces universales.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

Además, debes definir la returnURL del objeto PaymentSheet.Configuration en la URL de tu aplicación.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

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

func cancelSubscription() {
    var request = URLRequest(url: URL(string: "http://localhost:4242/cancel-subscription")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscription.id])
    let (subscriptionResponse, _) = try! await URLSession.shared.data(for: request)
    // Update the state to show the subscription has been cancelled
}

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.