Crear una integración de suscripciones

Instala el cliente de Stripe que prefieras:

# Available as a gem
sudo gem install stripe

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

A continuación, instala la CLI de Stripe. La CLI proporciona pruebas de webhooks y puedes ejecutarla para realizar llamadas API a Stripe. Esta guía muestra cómo utilizar la CLI para configurar un modelo de precios 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 necesita un cliente para cada suscripción. En el front-end de tu aplicación, recopila cualquier información necesaria de tus usuarios y pásala al back-end.

If you need to collect address details, the Address Element enables you to collect a shipping or billing address for your customers. For more information on the Address Element, see the Address Element page.

<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

Crea el objeto Customer 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 cliente elija un plan y, a continuación, crea la suscripción. En el ejemplo de esta guía, el cliente elige entre un plan Básico o un plan Premium.

En el front end, pasa el ID del precio seleccionado y el ID del registro del cliente al back end.

fetch('/create-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    priceId: priceId,
    customerId: customerId,
  }),
})

En el back end, cree la suscripción con un estado incompleto utilizando payment_behavior=default_incomplete. A continuación, devuelve el client_secret del primer PaymentIntent de la suscripción al front end para completar el pago. Para ello, expande el confirmation_secret en la última factura de la suscripción.

Para habilitar el comportamiento de suscripción mejorado, establece billing_mode[type] en flexible. Debes utilizar la versión de la API de Stripe 2025-06-30.basil o posterior.

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

# 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

La suscripción ahora está inactiva y a la espera de pago. El ejemplo de respuesta que figura a continuación destaca los campos mínimos que deben almacenarse, pero puedes almacenar los campos a los que tu solicitud accede con frecuencia.

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

Utiliza Stripe Elements para cobrar los datos de pago y activar la suscripción. Puedes personalizar Elements para que se adapte al aspecto de tu solicitud.

El Payment Element admite Link, tarjetas de crédito, débito directo SEPA y débito directo BECS para suscripciones. Puedes mostrar los métodos de pago habilitados y recopilar de forma segura los datos de pago según la selección de tu cliente.

Configurar Stripe Elements

El Payment Element se encuentra disponible automáticamente como funcionalidad de Stripe.js. Incluye el script de Stripe.js en tu página de confirmación de compra agregándolo al head de tu archivo HTML. Siempre debes cargar Stripe.js directamente desde js.stripe.com para cumplir con la normativa PCI. No incluyas el script en un paquete ni alojes una copia en tus sistemas.

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>

Crea una instancia de Stripe con el siguiente JavaScript en tu página de pago:

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Agrega el Payment Element a tu página

El Payment Element necesita un lugar donde residir en tu página de pago. Crea un nodo DOM vacío (contenedor) con una ID única en tu formulario de pago.

<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Subscribe</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Una vez cargado el formulario, cree una instancia de Payment Element y móntalo en el nodo DOM contenedor. Cuando creaste la suscripción, pasaste el valor client_secret al front-end. Pasa este valor como una opción cuando crees una instancia de Elements.

const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in the payment form, passing the client secret obtained in step 5
const elements = stripe.elements(options);

const paymentElementOptions = {
  layout: "tabs",
};

// Create and mount the Payment Element
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

El elemento de pago muestra un formulario dinámico 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 seleccionen.

Configuraciones opcionales del Payment Element

Opcionalmente, puedes hacer lo siguiente:

• Customize the Payment Element to match the design of your site by passing the appearance object into options when creating an instance of Elements.
• Configura la interfaz de Apple Pay para que devuelva un token de comerciante para admitir pagos recurrentes, recargas automáticas y pagos aplazados.

Completar pago

Utiliza stripe.confirmPayment para completar el pago utilizando los datos del elemento de pago y activar la suscripción. Esto crea un método de pago, confirma la primera intención de pago de la suscripción incompleta y realiza el cargo. Si se requiere la autenticación reforzada de clientes (SCA) (SCA) para el pago, el elemento de pago se encarga del proceso de autenticación antes de confirmar la intención de pago.

Proporciona una dirección return_url para indicar a dónde redirige Stripe al usuario después de completar el pago. Tu usuario podría redirigirse primero a un sitio intermedio, como una página de autorización bancaria, antes de redirigirse a la return_url. Los pagos con tarjeta redirigen inmediatamente a la return_url cuando el pago se realiza correctamente.

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point is reached only if there's an immediate error when
    // confirming the payment. Show an error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer redirects to your `return_url`. For some payment
    // methods, such as iDEAL, your customer redirects to an intermediate
    // site first to authorize the payment, and then redirects to the `return_url`.
  }
});

Cuando tu cliente envía un pago, Stripe lo redirige a return_url e incluye los siguientes parámetros de consulta de URL. La página de retorno puede usarlos para obtener el estado del PaymentIntent a fin de mostrarle el estado del pago al cliente.

Cuando especificas la return_url, también puedes adjuntar tus propios parámetros de consulta para usarlos en la página de retorno.

Cuando el cliente es redirigido a tu sitio, puedes usar el payment_intent_client_secret para consultar el PaymentIntent y mostrarle el estado de la transacción a tu cliente.

Utiliza uno de los parámetros de consulta para recuperar el PaymentIntent. Inspecciona el estado del PaymentIntent para decidir qué mostrar a tus clientes. También puedes añadir tus propios parámetros de consulta al proporcionar la return_url, que persisten a través del proceso de redirección.

// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods [immediately succeed or fail][0] upon
  // confirmation, while others first enter a `processing` status.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

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, see https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Durante el desarrollo, utiliza la CLI de Stripe para observar los webhooks y reenviarlos a tu solicitud. Ejecuta lo siguiente en un terminal nuevo mientras se ejecuta tu aplicación de desarrollo:

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

Para la producción, configura un punto de conexión webhook en Workbench, o utiliza la API Webhook Endpoints.

Escucha algunos eventos para completar los pasos restantes de esta guía. Consulta Eventos de suscripción y obtén más detalles sobre los webhooks específicos de la suscripción.

Ahora que la suscripción está activa, dale a tu usuario acceso a tu servicio. Para ello, escucha los eventos customer.subscription.created, customer.subscription.updated, y customer.subscription.deleted. Estos eventos pasan un objeto Subscription que contiene un 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 estados.

En tu controlador de webhook:

1. Verifica el estado de la suscripción. Si es activo, tu usuario ha pagado por su 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 tengas que cambiar el precio o el período de facturación.
3. Almacena el product.id, subscription.id y el subscription.status en tu base de datos junto con customer.id que ya guardaste. Consulta este registro cuando tengas que determinar qué funcionalidades habilitar para el usuario en tu aplicación.

El estado de la suscripción puede cambiar en cualquier momento de su ciclo de vida, incluso si tu solicitud 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, si usas el portal de clientes, un usuario puede optar por cancelar la suscripción sin ingresar a tu aplicación directamente. El uso correcto del controlador mantiene el estado de tu solicitud sincronizado con Stripe.

Puedes permitir que los clientes cancelen sus suscripciones. El ejemplo siguiente añade una opción de cancelación a la página de configuración de la cuenta.

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

function cancelSubscription(subscriptionId) {
  return fetch('/cancel-subscription', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(cancelSubscriptionResponse => {
      // Display to the user that the subscription has been canceled.
    });
}

En el back-end, define el punto de conexión para que el front-end 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

En tu aplicación, se 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 se cancela una suscripción, no se puede reactivar. En su lugar, recopila la información de facturación actualizada de tu cliente, actualiza su método de pago predeterminado y crea una nueva suscripción con tu registro de cliente existente.

Prueba métodos de pago

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

Supervisa los acontecimientos

Configura webhooks para escuchar los eventos de cambio de suscripción, como actualizaciones y cancelaciones. Más información sobre webhooks de suscripción. Puedes ver los eventos en el Dashboard o con Stripe CLI.

Para más detalles, consulta Comprobación de la integración con Billing.