Crear una integración de suscripciones

Crear y administrar las suscripciones para aceptar pagos recurrentes.

Web

iOS

Android

React Native

togethere.work

Esfuerzo de integración

Baja codificación (low code)

Personalización de la interfaz de usuario

Personaliza la apariencia.

Tipo de integración

Usa formularios integrados prediseñados para cobrar pagos y administrar suscripciones.

Configurar el servidor

Configurar Stripe

Instala el cliente de Stripe que prefieras:

Crear un producto y un precio

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: Precio estándar | 15 USD
Producto básico: servicio básico con las funcionalidades mínimas
- Precio: Precio estándar | 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 múltiples intervalos de facturación, usa Checkout para aumentar las ventas destinadas a los clientes con intervalos de facturación más prolongados y obtener más ingresos por adelantado.

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

Crear una sesión de Checkout

Agrega a tu servidor un punto de conexión que cree una sesión de Checkout.

Cuando crees la sesión de Checkout, especifica los siguientes parámetros:

Para utilizar el formulario de Checkout integrado, establece ui_mode en embedded.
Para crear suscripciones cuando el cliente realiza la compra, establece el modo en subscription.
Para definir la página a la que regresa tu cliente después de completar o intentar el pago, especifica una return_url. Incluye la variable de plantilla {CHECKOUT_SESSION_ID} en la URL. Checkout reemplaza la variable con el ID de la sesión de Checkout antes de redirigir a tu cliente. Creas y alojas la página de retorno en tu sitio web.

Para montar Checkout, usa el client_secret de la sesión de Checkout que se devuelve en la respuesta.

Crear tu página de suscripciones
Cliente

Montar Checkout

Cargar Stripe.js

Utiliza Stripe.js para cumplir con la normativa PCI asegurándote de que los datos del pago se envíen directamente a Stripe sin que pasen por tu servidor. Carga siempre Stripe.js desde js.stripe.com para cumplir con la normativa. No incluyas el script en un paquete ni lo alojes por tu cuenta.

Definir el formulario de pago

Para recopilar la información del cliente en modo seguro, crea un marcador de posición div vacío. Stripe inserta un iframe en el div.

Checkout está disponible como parte de Stripe.js. Incluye el script de Stripe.js en tu página agregándolo al encabezado de tu archivo HTML. A continuación, crea un nodo DOM vacío (contenedor) para usarlo en el montaje.

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Accept a payment</title>
    <meta name="description" content="A demo of a payment on Stripe" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="style.css" />
    <!-- Add the Stripe.js script here -->
    <script src="https://js.stripe.com/basil/stripe.js"></script>
    <script src="checkout.js" defer></script>
  </head>
  <body>
    <!-- Display a payment form -->
      <div id="checkout">
        <!-- Checkout inserts the payment form here -->
      </div>
  </body>
</html>

Inicializar Stripe.js

Inicializa Stripe.js con la clave publicable de tu API.

Recuperar un secreto de cliente de una sesión de Checkout

Crea una función fetchClientSecret asíncrona que haga una solicitud a tu servidor para que cree una sesión de Checkout y recupere el secreto de cliente.

Inicializar Checkout

Inicia Checkout con tu función fetchClientSecret y móntala en el marcador de posición <div> en tu formulario de pago. Checkout se representa en un iframe que envía la información del pago a Stripe en modo seguro a través de una conexión HTTPS.

Evita colocar Checkout en otro iframe, ya que algunos métodos de pago requieren un redireccionamiento a otra página para confirmar el pago.

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Mostrar página de devolución

Luego de que el cliente intente realizar el pago, Stripe lo redirige a una página de retorno que alojas en tu sitio. Cuando creaste la sesión de Checkout, especificaste la URL de la página de retorno en el parámetro return_url.

Nota

Durante el proceso de pago, algunos métodos de pago redirigen al cliente a una página intermedia, como una página de autorización bancaria. Cuando completen esa página, Stripe los redirigirá a tu página de devoluciones.

Crea un punto de conexión para recuperar una sesión de Checkout

Agrega un punto de conexión para recuperar el estado de una sesión de Checkout con el ID de la sesión de Checkout en la URL.

Recuperar una sesión de Checkout

Para usar los detalles de la sesión de Checkout, haz una solicitud de inmediato al punto de conexión de tu servidor para recuperar el estado de la sesión de Checkout usando el ID de sesión de Checkout en la URL apenas se cargue la página de retorno.

Administrar la sesión

Gestiona el resultado según el estado de la sesión:

complete: El pago se efectuó con éxito. Usa la información de la sesión de Checkout para mostrar una página que indique que el pago se realizó correctamente.
open: El pago falló o se canceló. Vuelve a mostrar Checkout para que el cliente pueda volver a intentarlo.

return.js
// Retrieve a Checkout Session
// Use the session ID
initialize();

async function initialize() {
  const queryString = window.location.search;
  const urlParams = new URLSearchParams(queryString);
  const sessionId = urlParams.get('session_id');
  const response = await fetch(`/session-status?session_id=${sessionId}`);
  const session = await response.json();
// Handle the session according to its status
  if (session.status == 'open') {
    // Remount embedded Checkout
    window.location.replace('http://localhost:4242/checkout.html')
  } else if (session.status == 'complete') {
    document.getElementById('success').classList.remove('hidden');
    document.getElementById('customer-email').textContent = session.customer_email;
    // Show success page
    // Optionally use session.payment_status or session.customer_email
    // to customize the success page
  }
}

server.js
// Add an endpoint to fetch the Checkout Session status
app.get('/session_status', async (req, res) => {
  const session = await stripe.checkout.sessions.retrieve(req.query.session_id);
  const customer = await stripe.customers.retrieve(session.customer);

  res.send({
    status: session.status,
    payment_status: session.payment_status,
    customer_email: customer.email
  });
});

OpcionalConfigurar el portal de clientes

Dar acceso

Ahora que la suscripción está activa, brinda acceso a tu servicio a los usuarios. 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 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 los estados. Para obtener más información sobre cómo gestionar el acceso a la funcionalidad de tu producto, consulta la documentación sobre la integración de derechos.

En tu controlador de webhook:

Verifica el estado de la suscripción. Si está active, el usuario pagó por tu producto.
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.
Almacena el product.id, subscription.id y 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 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.

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 pago	Escenario	Cómo hacer la prueba
Débito directo BECS	Tu cliente paga correctamente con débito directo BECS.	Completa el formulario con el número de cuenta `900123456` y BSB `000-000`. El PaymentIntent confirmado pasa inicialmente al estado `processing` y, tres minutos más tarde, a `succeeded`.
Débito directo BECS	El 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 `000-000`.
Tarjeta de crédito	El 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édito	El 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édito	La 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 SEPA	Tu 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 SEPA	El 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.

Obtén más información sobre cómo probar tu integración con Billing.