Crear una integración de suscripciones

El SDK para React Native es de código abierto y está plenamente documentado. Internamente, utiliza SDK para iOS nativo y Android. Para instalar el SDK para React Native de Stripe, ejecuta uno de los siguientes comandos en el directorio del proyecto (según el administrador de paquetes que utilices):

yarn add @stripe/stripe-react-native

A continuación, instala otras dependencias necesarias:

• For iOS, go to the ios directory and run pod install to ensure that you also install the required native dependencies.
• Para Android, no hay más dependencias para instalar.

Inicialización de Stripe

Para inicializar Stripe en tu aplicación React Native, ajusta tu pantalla de pago con el componente StripeProvider o usa el método de inicialización initStripe. Solo se requiere la clave publicable de la API en publishableKey. El siguiente ejemplo muestra cómo inicializar Stripe usando el componente StripeProvider.

import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}

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.

import React from 'react';
import {View, TextInput, StyleSheet, Button, Platform} from 'react-native';

function RegisterView() {
  const [email, setEmail] = React.useState('');

  const createCustomer = async () => {
    const apiEndpoint =
      Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
    const response = await fetch(`${apiEndpoint}/create-customer`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: email,
      }),
    });
    if (response.status === 200) {
      const customer = await response.json();
      console.log(customer);
    }
  };

  return (
    <View>
      <TextInput
        style={styles.input}
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
      />
      <Button
        title="Register"
        onPress={async () => {
          await createCustomer();
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  input: {
    height: 40,
    margin: 12,
    borderWidth: 1,
    padding: 10,
  },
});

export default RegisterView;

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.

const createSubscription = async (priceId, customerId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/create-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId: priceId,
      customerId: customerId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};

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: '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,

Usa el Mobile Payment Element para recopilar los datos de pago y activar la suscripción. Puedes personalizar Elements para que coincida con el aspecto de tu aplicación.

Mobile Payment Element recopila de forma segura todos los detalles de pago necesarios para una amplia variedad de métodos de pago. Obtén información sobre los métodos de pago admitidos para Mobile Payment Element y Subscriptions.

Agregar el Payment Element a tu aplicación

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

import React from 'react';
import {useStripe, PaymentSheetError} from '@stripe/stripe-react-native';
import {View, Button} from 'react-native';

function SubscribeView({clientSecret}) {
  const {initPaymentSheet, presentPaymentSheet} = useStripe();

  React.useEffect(() => {
    const initializePaymentSheet = async () => {
      const {error} = await initPaymentSheet({
        paymentIntentClientSecret: clientSecret,
        returnURL: 'stripe-example://payment-sheet',
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        allowsDelayedPaymentMethods: true,
      });
      if (error) {
        // Handle error
      }
    };

    initializePaymentSheet();
  }, [clientSecret, initPaymentSheet]);

  return (
    <View>
      <Button
        title="Subscribe"
        onPress={async () => {
          const {error} = await presentPaymentSheet();
          if (error) {
            if (error.code === PaymentSheetError.Failed) {
              // Handle failed
            } else if (error.code === PaymentSheetError.Canceled) {
              // Handle canceled
            }
          } else {
            // Payment succeeded
          }
        }}
      />
    </View>
  );
}

export default SubscribeView;

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.

Cuando un cliente sale de tu aplicación (por ejemplo, para autenticarse en Safari o en su aplicación bancaria), proporciona una forma de regresar automáticamente a tu aplicación. Muchos tipos de métodos de pago requieren una URL de retorno. Si no la proporcionas, no podemos presentarles a tus usuarios métodos de pago que requieran una URL de retorno, incluso si los habilitaste.

Para proporcionar una URL de retorno:

1. Registra una URL personalizada. No se admiten vínculos universales.
2. Configura tu URL personalizada.
3. Configura tu componente raíz para reenviar la URL al SDK de Stripe como se muestra a continuación.

import { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}

Además, al llamar al método initPaymentSheet, debes especificar returnURL:

await initPaymentSheet({
  ...
  returnURL: 'your-app://stripe-redirect',
  ...
});

Para obtener más información sobre esquemas URL nativos, consulta la documentación para Android e iOS.

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.

You need to listen to a few events to complete the remaining steps in this guide. See Subscription events for more details about subscription-specific webhooks.

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

const cancelSubscription = async subscriptionId => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/cancel-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};

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.