Ir a contenido
Crea una cuenta
 o
Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuenta
Iniciar sesión
ResumenActualiza tu integración
Pagos electrónicos
ResumenEncuentra tu caso de usoPagos administrados
Crea una página del proceso de compra
Métodos de pago
Interfaces de pago
Escenarios de pago
Pagos en persona
Más allá de los pagos

Crear una integración de suscripciones

Crear y administrar las suscripciones para aceptar pagos recurrentes.

Página de suscripción a Checkout
Baja codificación (low code)

Personalizar el logotipo, las imágenes y los colores.

Usa formularios prediseñados alojados para hacer cobros y administrar suscripciones.

Clona un modelo de integración desde GitHub.

Para obtener una versión más completa de esta guía, consulta la sección de inicio rápido para integraciones de Billing.

Explora el ejemplo en GitHub o la demostración.

Lo que podrás hacer

En esta guía, se describe cómo vender suscripciones mensuales de precio fijo usando Stripe Checkout.

En esta guía, se explica cómo hacer lo siguiente:

  • Modelar tu empresa creando un catálogo de productos
  • Agregar una sesión de Checkout a tu sitio, incluidos un botón y las páginas de confirmación y cancelación
  • Supervisar los eventos de suscripción y brindar acceso a tu servicio
  • Configura el portal de clientes
  • Agregar una sesión del portal de clientes a tu sitio, incluidos un botón y el redireccionamiento
  • Permitir que tus clientes administren sus suscripciones a través del portal
  • Aprenda a usar el modo facturación flexible para acceder a un comportamiento de facturación mejorado y funcionalidades adicionales.

Después de completar la integración, puedes ampliarla a lo siguiente:

Configurar Stripe

Instala el cliente de Stripe que prefieras:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Instala la CLI de Stripe (opcional). La CLI te permite hacer pruebas de webhooks y puedes ejecutarla para crear productos y precios.

Command Line
homebrew
Instalar desde fuente
No results
# 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.

Crear el modelo de tarifas
Dashboard o 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.

Ve a la página Agregar un producto y crea dos productos. Agrega un precio a cada producto, cada uno con un período de facturación mensual recurrente:

  • Producto prémium: servicio prémium con más funcionalidades

    • Precio: Tarifa plana | 15 USD

  • Producto básico: servicio básico con las funcionalidades mínimas

    • Precio: Tarifa plana | 5 USD

Después de crear los precios, registra los ID de precio para usarlos en otros pasos. Los ID de precio se ven así: price_G0FvDp6vZvdwRZ.

Cuando esté todo listo, usa el botón Copiar en modo activo, en la parte superior derecha de la página, para clonar el producto y pasarlo de entorno de prueba a modo activo.

Si ofreces varios períodos de facturación, usa el proceso de compra para las ventas adicionales a los clientes en períodos de facturación más largos y cobra más ingresos por adelantado.

Para ver otros modelos de tarifas, consulta los ejemplos de Billing.

Crear una sesión de Checkout
Cliente y servidor

Agrega un botón de finalización de compra en tu sitio web que llame a un punto de conexión del lado del servidor para crear una sesión de Checkout.

index.html
Visualizar el ejemplo completo
<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <!-- Note: If using PHP set the action to /create-checkout-session.php -->

      <input type="hidden" name="priceId" value="price_G0FvDp6vZvdwRZ" />
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

En el back-end de tu aplicación, define un punto de conexión que cree la sesión para que el front-end haga la llamada. Necesitas estos valores:

  • El ID de precio de la suscripción por la que el cliente ha creado la cuenta (tu front-end especifica este valor).
  • Tu success_url, una página en tu sitio web a la que Checkout redirige al cliente después de que efectúa el pago.

Opcionalmente, puedes:

Si creaste un precio único en el paso 2, especifica también el ID de ese precio. Después de crear una Checkout Session, debes redirigir a tu cliente a la URL que se devuelve en la respuesta.

Puedes habilitar un comportamiento de suscripción más preciso y predecible cuando creas una sesión de proceso de compra al configurar billing_mode[type] como flexible. Debes usar la versión Stripe API 2025-06-30.basil o posterior.

Nota

Puedes usar lookup_keys para obtener los precios en lugar de los ID de los precios. Consulta la aplicación de ejemplo para ver un ejemplo.

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Visualizar el ejemplo completo
# 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'


# The price ID passed from the front end.
#   price_id = params['priceId']
price_id = '{{PRICE_ID}}'

session = Stripe::Checkout::Session.create({
  success_url: 'https://example.com/success.html?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/canceled.html',
  mode: 'subscription',
  line_items: [{
    # For usage-based billing, don't pass quantity
    quantity: 1,
    price: price_id,
  }],
  subscription_data: {
    billing_mode: { type: 'flexible' }
  }
})

# Redirect to the URL returned on the session
#   redirect session.url, 303

En este ejemplo, success_url se personaliza agregando el ID de sesión. Para obtener más información sobre este enfoque, consulta la sección Personaliza la página de confirmación de la documentación.

Desde el Dashboard, habilita los métodos de pago de tus clientes que quieras aceptar. Checkout admite varios métodos de pago.

Dar acceso a las suscripciones y monitorearlas
Servidor

Una vez que la suscripción se ha completado con éxito, el cliente regresa a su sitio web en la dirección success_url, que inicia un evento checkout.session.completed webhook. Cuando reciba un evento checkout.session.completed, utilice entitlements para aprovisionar la suscripción. Continúe aprovisionando cada mes (si factura mensualmente) a medida que reciba eventos invoice.paid. Si recibe un evento invoice.payment_failed, notifíquelo a su cliente y envíelo al portal de clientes para que actualice su método de pago.

Para determinar el siguiente paso para la lógica de tu sistema, comprueba el tipo de evento y analiza la carga de cada objeto de evento, como invoice.paid. Almacena los objetos de evento subscription.id y customer.id en tu base de datos para su verificación.

Para realizar pruebas, puede supervisar los eventos en la pestaña Eventos de Workbench. Para producción, configure un punto de conexión webhook y suscríbase a los tipos de eventos apropiados. Si no conoce su clave STRIPE_WEBHOOK_SECRET, vaya a la vista de detalles del destino de la pestaña Webhooks en Workbench para verla.

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Visualizar el ejemplo completo
# 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
  webhook_secret = 
'{{STRIPE_WEBHOOK_SECRET}}'

  payload = request.body.read
  if !webhook_secret.empty?
    # Retrieve the event by verifying the signature using the raw body and secret if webhook signing is configured.
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    event = nil

    begin
      event = Stripe::Webhook.construct_event(
        payload, sig_header, webhook_secret
      )
    rescue JSON::ParserError => e
      # Invalid payload
      status 400
      return
    rescue Stripe::SignatureVerificationError => e
      # Invalid signature
      puts '⚠️  Webhook signature verification failed.'
      status 400
      return
    end
  else
    data = JSON.parse(payload, symbolize_names: true)
    event = Stripe::Event.construct_from(data)
  end
  # Get the type of webhook event sent
  event_type = event['type']
  data = event['data']
  data_object = data['object']

  case event_type
  when 'checkout.session.completed'
    # Payment is successful and the subscription is created.
    # You should provision the subscription and save the customer ID to your database.
  when 'invoice.paid'
    # Continue to provision the subscription as payments continue to be made.
    # Store the status in your database and check when a user accesses your service.
    # This approach helps you avoid hitting rate limits.
  when 'invoice.payment_failed'
    # The payment failed or the customer doesn't have a valid payment method.
    # The subscription becomes past_due. Notify your customer and send them to the
    # customer portal to update their payment information.
  else
    puts "Unhandled event type: \#{event.type}"
  end

  status 200
end

Como mínimo, debes monitorear estos tipos de eventos:

Nombre del eventoDescripción
checkout.session.completedSe envía cuando un cliente completa correctamente la sesión de Checkout, notificándote una nueva compra.
invoice.paidSe envía en cada período de facturación cuando se realiza correctamente un pago.
invoice.payment_failedSe envía en cada período de facturación si hay un problema con el método de pago del cliente.

Para ver más eventos que se pueden monitorear, consulta la sección Webhooks de suscripciones.

Configurar el portal de clientes
Dashboard

El portal de clientes permite que tus clientes administren directamente sus suscripciones y facturas actuales.

Usa el Dashboard para configurar el portal. Como mínimo, asegúrate de configurarlo de modo tal que los clientes puedan actualizar sus métodos de pago. Consulta Cómo integrar el portal de clientes para obtener más información sobre otros parámetros de configuración.

Crear una sesión del portal
Servidor

Define an endpoint that creates the customer portal session for your frontend to call. Here CUSTOMER_ID refers to the customer ID created by a Checkout Session that you saved while processing the checkout.session.completed event. You can also set a default redirect link for the portal in the Dashboard.

Especifica un valor return_url opcional para la página en tu sitio web a la que se redireccionará al cliente una vez que termine de gestionar la suscripción:

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Visualizar el ejemplo completo
# 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'


# This is the URL that users are redirected to after they're done
# managing their billing.
return_url = 
'{{DOMAIN_URL}}'

customer_id = 
'{{CUSTOMER_ID}}'


session = Stripe::BillingPortal::Session.create({
  customer: customer_id,
  return_url: return_url,
})

# Redirect to the URL for the session
#   redirect session.url, 303

Dirigir a los clientes al portal
Cliente

En el front-end, agrega un botón a la página de la dirección success_url que proporcione un enlace al portal de clientes:

success.html
Visualizar el ejemplo completo
<html>
  <head>
    <title>Manage Billing</title>
  </head>
  <body>
    <form action="/customer-portal" method="POST">
      <!-- Note: If using PHP set the action to /customer-portal.php -->
      <button type="submit">Manage Billing</button>
    </form>
  </body>
</html>

Después de salir del portal de clientes, el cliente vuelve a tu sitio web en la return_url. Sigue monitoreando los eventos para hacer el seguimiento del estado de la suscripción del cliente.

Si configuras el portal de clientes para permitir acciones como cancelar una suscripción, consulta Cómo integrar el portal de clientes para ver qué otros eventos puedes monitorear.

Probar tu integración

Prueba métodos de pago

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

Método de pagoEscenarioCómo hacer la prueba
Débito directo BECSTu cliente paga correctamente con débito directo BECS.Completa el formulario con el número de cuenta 900123456 y BSB 000000. El PaymentIntent confirmado pasa en un principio al estado en proceso y, tres minutos más tarde, a finalizado con éxito.
Débito directo BECSEl pago de tu cliente falla con un código de error account_closed.Completa el formulario con el número de cuenta 111111113 y BSB 000000.
Tarjeta de créditoEl pago con tarjeta se efectúa correctamente y no requiere autenticación.Completa el formulario de tarjeta de crédito con el número de tarjeta 4242 4242 4242 4242 y cualquier fecha de vencimiento, CVC y código postal.
Tarjeta de créditoEl pago con tarjeta requiere autenticación.Completa el formulario de tarjeta de crédito con el número de tarjeta 4000 0025 0000 3155 y cualquier fecha de vencimiento, CVC y código postal.
Tarjeta de créditoLa tarjeta es rechazada con el código insufficient_funds.Completa el formulario de tarjeta de crédito con el número de tarjeta 4000 0000 0000 9995 y cualquier fecha de vencimiento, CVC y código postal.
Débito directo SEPATu cliente paga correctamente con débito directo SEPA.Completa el formulario con el número de cuenta AT321904300235473204. El PaymentIntent confirmado pasa inicialmente al estado “en proceso” y, tres minutos más tarde, a “completado”.
Débito directo SEPAEl estado de PaymentIntent de tu cliente pasa de processing a requires_payment_method.Completa el formulario con el número de cuenta AT861904300235473202.

Eventos de monitoreo

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 consultar los eventos en el Dashboard o con la CLI de Stripe.

Para obtener más detalles sobre cómo probar tu integración con Billing, lee la guía.

Consulta también

¿Te fue útil esta página?
SíNo