Ir a contenido
Crea una cuenta o Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuentaIniciar sesión
Resumen
Billing
ResumenAcerca de las API de facturación
Suscripciones
Impuesto
Resumen
Elaboración de informes
ResumenInformes para varias cuentas
Datos
Resumen

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)

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

Utiliza las páginas alojadas prediseñadas para cobrar los pagos y gestionar tus suscripciones.

Clona un ejemplo de integración de GitHub.

Si desea una versión detallada de esta guía, consulte la página de inicio rápido de la integración de Billing.

Explora la muestra en GitHub o la demo.

Tu próximo desarrollo

Esta guía describe cómo vender suscripciones mensuales de precio fijo utilizando Stripe Checkout.

Esta guía te explica cómo:

  • Modelar tu empresa creando un catálogo de productos.
  • Agregar una Checkout Session a tu sitio, incluidos un botón y las páginas de confirmación y cancelación de transacciones.
  • Monitorear 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.
  • Learn how to use flexible billing mode to access enhanced billing behavior and additional features.

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

Configura 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'

Opcionalmente, instala la CLI de Stripe. La CLI proporciona pruebas de webhook, y puedes ejecutarla para crear tus 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 conocer otros modelos de precios, consulta Ejemplos de Billing.

Crea una Checkout Session
Cliente y servidor

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

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 solicitud, define un punto de conexión que cree la sesión para que tu front-end la llame. Necesitará 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, que es una página de su sitio web a la que Checkout devuelve a tu cliente después de completar el pago.

Opcionalmente, puedes:

If you created a one-time price in step 2, pass that price ID as well. After creating a Checkout Session, redirect your customer to the URL returned in the response.

Puedes habilitar un comportamiento de suscripción más preciso y predecible cuando crees una Checkout Session configurando el tipo de modo de facturación como flexible. Debes utilizar la versión de la API de Stripe 2025-06-30.basil o posterior.

Nota

You can use lookup_keys to fetch prices rather than price IDs. For an example, see the sample application.

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

Este ejemplo personaliza la success_url añadiendo el identificador de sesión. Más información sobre personalización de la página de éxito.

Desde tu Dashboard, activa los métodos de pago que deseas aceptar de tus clientes. 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 recibas un evento checkout.session.completed, utiliza entitlements para aprovisionar la suscripción. Continúa aprovisionando cada mes (si facturas mensualmente) a medida que recibas eventos invoice.paid. Si recibes un evento invoice.payment_failed, notifícalo a tu cliente y envíalo 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 útil de cada objeto de evento, como iinvoice.paid. Almacena los objetos de evento subscription.id y customer.id en tu base de datos para su verificación.

Para realizar pruebas, puedes supervisar los eventos en la pestaña Eventos de Workbench. Para producción, configura un punto de conexión webhook y suscríbete a los tipos de eventos apropiados. Si no conoces tu clave STRIPE_WEBHOOK_SECRET, ve a la vista de detalles del destino de la pestaña Webhooks de Workbench para consultarla.

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 con éxito la sesión de pago, para informarle 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 conocer aún más eventos que supervisar, consulta Webhooks de suscripción.

Configurar el portal de clientes
Dashboard

El portal de clientes les permite a tus clientes gestionar directamente sus suscripciones y facturas existentes.

Utiliza el Dashboard para configurar el portal. Como mínimo, asegúrate de configurar el portal para que los clientes puedan actualizar sus métodos de pago.

Crear una sesión del portal
Servidor

Definir un punto de conexión que cree la sesión del portal de clientes para que tu front-end la llame. El CUSTOMER_ID se refiere al ID de cliente creado por una Checkout Session que guardaste mientras procesabas el evento checkout.session.completed. También puedes establecer un enlace de redirección predeterminado para el portal en el Dashboard.

Pasa un valor opcional return_url para la página de tu sitio a la que redirigir a tu cliente cuando termine de gestionar tu 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 de clientes
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 la cancelación de una suscripción, supervisa eventos adicionales.

Prueba la 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.

Supervisa los acontecimientos

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

Obtén más información sobre Comprobación de la integración con Billing.

Consulta también

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