Antes de empezar
Revisa estos puntos según tu caso de uso antes de integrar:- Cuenta de Stripe. Billing debe tener habilitado el procesamiento de pagos de terceros. Solicítalo a tu equipo de cuenta de Stripe.
- Países. Tu negocio y tus proveedores de pago deben estar en países que Stripe admita para este modo. Consulta los países admitidos de Stripe.
- Checkout. Los clientes pagan a través de tu checkout de Yuno. Stripe Checkout, la página de factura alojada por Stripe y las tablas de precios de Stripe integradas no funcionan en este modo.
- Emails a clientes. Stripe no envía sus emails de recuperación de ingresos para estos pagos. Tú envías los emails de pago fallido y de actualización de tarjeta desde tus propios sistemas.
- Reintentos. Stripe Smart Retries no está disponible. En su lugar, configuras un calendario de reintentos personalizado o automatizaciones de Billing.
- Disputas y reembolsos. Gestionas ambos en Yuno. Stripe no puede iniciar un reembolso ni gestionar una disputa de un pago que no procesó.
- Tarifas. Stripe cobra tarifas de Billing sobre el volumen que procesa Yuno. Consulta Tarifas de Billing.
- Facturas. Yuno cobra las facturas de las suscripciones de Stripe Billing. Si Stripe pide a Yuno cobrar una factura que no tiene suscripción, Yuno no la cobra y no informa nada a Stripe. Para cobrar una factura única con Yuno, crea el pago tú mismo con el objeto
external_invoice. Consulta Pagar una factura de Stripe (recargas).
Quién hace qué
Cómo funciona
El modo de procesamiento de pagos de terceros de Stripe permite que un procesador externo ejecute los cobros de las suscripciones de Billing. Yuno es ese procesador.Registro y primer pago
Renovaciones y reintentos
Tu backend sigue escuchando los webhooks de Stripe que usa hoy (invoice.paid, customer.subscription.updated y otros) para los derechos de acceso.
Del lado de Yuno, cada pago creado de esta forma incluye el objeto external_subscription en su webhook de pago, para que puedas relacionar un pago de Yuno con una suscripción de Stripe. Consulta Objeto y ejemplos. Las inscripciones de prueba son la excepción: el webhook de inscripción no incluye el objeto, así que correlaciona mediante el pago de verificación (verify.payment.id en la respuesta de la inscripción).
Requisitos previos
- Una cuenta de Yuno con tus proveedores conectados y el enrutamiento publicado.
- Una cuenta de Stripe con Billing y el procesamiento de pagos de terceros habilitados.
- Una clave de API restringida de tu cuenta de Stripe, compartida con tu contacto en Yuno durante el onboarding. Yuno la usa para registrar el endpoint de webhook e informar los pagos. Yuno la almacena cifrada y la usa solo para tu cuenta.
- Un método de pago personalizado que creas en el Stripe Dashboard, en Settings → Payment methods → Custom payment methods. Envía su ID (empieza con
cpmt_) a tu contacto en Yuno junto con la clave restringida. Yuno lo verifica cuando haces el onboarding y lo usa para los pagos de suscripción de cada método de pago que no tenga un método de pago personalizado propio. Para PayPal, consulta PayPal.
Permisos de la clave restringida
Da a la clave restringida estos permisos para los pagos de suscripción, renovaciones, reembolsos y cambios de tarjeta. Write incluye Read. Los nombres de los permisos de Stripe provienen de la referencia de permisos de API de Stripe.Eventos de webhook
Cuando haces el onboarding, Yuno registra un endpoint de webhook en tu cuenta de Stripe. Recibe dos eventos:invoice.payment_attempt_required: Stripe pide a Yuno cobrar una factura.customer.subscription.deleted: la suscripción terminó, por lo que Yuno deja de cobrarla.
Paso 1: Crea la suscripción en Stripe
Crea el cliente y la suscripción en Stripe como lo haces hoy, conpayment_behavior: default_incomplete. Expande latest_invoice en la misma llamada: necesitas su amount_due y currency en el paso 2. Conserva los IDs de customer y subscription.
Paso 2: Cobra el primer pago con Yuno
Ejecuta tu checkout normal de Yuno y crea el pago desde tu backend con dos adiciones:vault_on_success y el objeto external_subscription que vincula el pago con tu suscripción de Stripe. Consulta Crear pago.
Haz coincidir el monto con la factura
Cobra elamount_due de la factura, en la moneda de la factura. amount_due ya incluye impuestos, descuentos y prorrateo. Si el monto o la moneda del pago difieren de los de la factura, Yuno no informa el pago: se cobra al cliente y la factura queda abierta.
Stripe y Yuno formatean los montos de forma distinta, así que convierte ambos campos:
Campos de la solicitud
Si falla el informe a Stripe
Yuno cobra primero e informa a Stripe después. Un informe que falla nunca deshace el pago: permanece aprobado en Yuno, y Yuno no lo cancela ni lo reembolsa.- Reintentos. Cuando no se puede contactar a Stripe o este devuelve un error, Yuno reintenta el informe por su cuenta, con esperas crecientes, durante un tiempo limitado, y luego se detiene. Yuno no reintenta el informe de un primer pago que Stripe rechaza como inválido, o cuyo monto no es el
amount_duede la factura. Hasta que se entregue un informe, la factura permanece abierta en Stripe. En el caso de un primer pago, la suscripción también permaneceincomplete, y Stripe la expira 23 horas después de que la creaste. - Antes del informe. En el caso de un primer pago, Yuno primero crea la referencia del método de pago en Stripe y la establece como predeterminada de la suscripción. Si eso falla, Yuno reintenta durante unos segundos y luego se detiene: no informa nada y no vincula la tarjeta a la suscripción.
- Sin notificación. Yuno no te notifica cuando falla un informe. La señal es una factura que permanece abierta en Stripe después de que el pago en Yuno fue aprobado. Si ves una, contacta a tu contacto en Yuno.
Pagos pendientes
Yuno informa un primer pago a Stripe solo cuando es aprobado. Mientras está pendiente, y si termina rechazado, expirado o cancelado, Yuno no informa nada a Stripe y la factura permanece abierta. Una renovación que queda pendiente se informa a Stripe de inmediato, como un intento sin resultado. Cuando el pago es aprobado, Yuno lo informa como pagado. Si la renovación pendiente termina rechazada, expirada o cancelada, Yuno no informa ese resultado y no cobra las solicitudes posteriores que Stripe envíe para esa factura. Si una factura permanece abierta con un intento pendiente, contacta a tu contacto en Yuno.Si no se puede crear la suscripción
Un primer pago puede terminar enSUCCEEDED sin una suscripción de Stripe detrás. Yuno capturó el dinero, pero no pudo crear ni activar la suscripción en Stripe. Esto ocurre, por ejemplo, cuando al pago le faltan datos que la suscripción necesita, cuando la cotización de impuestos expiró o no se calcularon los impuestos, o cuando un objeto de Stripe que la suscripción necesita ya no existe. Yuno no reembolsa el pago por su cuenta.
Yuno informa cada uno de estos casos una vez, con el webhook subscription.creation_failed. Su data incluye el payment_id, el external_subscription que enviaste, un dead_letter_kind que nombra la causa, un reason legible por personas y occurred_at. Para recibirlo, agrega CREATION_FAILED a los subscription_triggers de tu webhook. Consulta Eventos de webhook.
Cuando llegue el evento, haz una de estas cosas:
- Corrige la causa y reintenta. Usa
dead_letter_kindpara encontrar qué falló, corrígelo (por ejemplo, solicita una nueva cotización de impuestos o vuelve a crear el objeto de Stripe faltante) y ejecuta el registro de nuevo con un pago nuevo. Reembolsa el pago original para que el cliente no pague dos veces. - Reembolsa. Si no vas a reintentar, reembolsa el pago para que no se cobre al cliente una suscripción que no tiene.
Pruebas gratuitas
Cuando el registro inicia con una prueba, no hay primer cobro. En su lugar, el disparador es la verificación de tarjeta de $0 del flujo de inscripción. Crea la suscripción de Stripe contrial_end como de costumbre, luego inscribe la tarjeta mediante el endpoint Inscribir método de pago con el objeto external_subscription anidado dentro de verify:
default_payment_method en Stripe pasa a ser la referencia de Yuno. No se cobra ni se informa nada, porque no hay ninguna factura pendiente. Al terminar la prueba, Stripe emite la primera factura real y Yuno la cobra con credenciales almacenadas conformes con las redes, como cualquier renovación.
Renovaciones
Las renovaciones no requieren código de tu parte. Stripe finaliza la factura y envíainvoice.payment_attempt_required. Yuno cobra la tarjeta almacenada en bóveda como una transacción iniciada por el comercio, a través de tu enrutamiento y cascada de proveedores, e informa el resultado. Cada cobro aparece como un pago normal en tu dashboard de Yuno y en los reportes.
Yuno cobra cada solicitud de Stripe una sola vez. Si Stripe envía el mismo evento de nuevo, Yuno lo ignora. Si Stripe envía una nueva solicitud para una factura que ya está pagada, o cuyo cobro sigue en curso, Yuno tampoco la cobra de nuevo. Una nueva solicitud para una factura cuyo último cobro fue rechazado es el siguiente reintento, y Yuno la cobra.
Pagos fallidos y reintentos
Cuando Yuno informa una renovación fallida, la factura permanece abierta y Stripe mueve la suscripción apast_due. Luego Stripe envía un nuevo evento invoice.payment_attempt_required en cada reintento programado, y Yuno ejecuta cada reintento a través de tu enrutamiento y cascada de proveedores. Yuno informa cada reintento contra el registro de pago existente de la factura.
Configura los reintentos en Stripe con un calendario de reintentos personalizado o automatizaciones de Billing. Los Smart Retries y los emails de recuperación de Stripe no funcionan en el modo de procesamiento de terceros. Ambas son limitaciones de Stripe, ajenas a los Smart Retries de Yuno, que se aplican a las suscripciones gestionadas por Yuno.
Rechazos definitivos y temporales
Un calendario de reintentos personalizado se ejecuta igual para cada factura fallida. Stripe no ve el motivo del rechazo, así que una tarjeta robada o una cuenta cerrada recibe los mismos reintentos que unos fondos insuficientes. Las redes de tarjetas limitan los reintentos en rechazos que no pueden tener éxito, y los reintentos repetidos sobre ellos pueden generar tarifas de red adicionales. Mantén el calendario de reintentos corto, y cancela la suscripción o marca la factura comouncollectible cuando el motivo del rechazo en Yuno muestre que un reintento no puede tener éxito.
Yuno no clasifica los rechazos como definitivos o temporales, y un intento fallido llega a Stripe sin motivo ni código: solo que falló, y cuándo. Yuno tampoco omite un reintento después de un rechazo: cobra cada reintento que Stripe pide. Detener los reintentos depende de ti, a partir del motivo del rechazo en Yuno.
Detecta el último intento
Stripe no tiene un evento dedicado de “reintentos agotados”. Considera un fallo como final cuando:- Tu backend recibe
invoice.payment_failed, oinvoice.updatedcuando usas automatizaciones, y - El
next_payment_attemptde la factura esnull.
Cambia la tarjeta del cliente
Usa este flujo para cambiar la tarjeta de una suscripción, incluida unapast_due:
Lleva al cliente de vuelta a tu checkout de Yuno
Cobra un nuevo pago o una verificación
external_subscription.id y vault_on_success: true. Una verificación cambia la tarjeta sin cobrar al cliente.Yuno cambia el valor predeterminado en Stripe
Cambia a un método de pago que el cliente ya inscribió
Si el cliente ya tiene otro método de pago almacenado en bóveda en Yuno, puedes mover la suscripción a ese método sin llevar al cliente de vuelta al checkout. Llama a Cambiar el método de pago de una suscripción externa con el ID de la suscripción de Stripe en la ruta, y envía el ID de cliente de Yuno encustomer_payer.id (no el ID cus_ de Stripe) y el nuevo vaulted_token.
No se realiza ningún pago: Yuno no cobra al cliente y no ejecuta una verificación de $0 ni 3DS. Yuno establece el nuevo método de pago como predeterminado de la suscripción en Stripe, y las próximas renovaciones lo cobran. Si Stripe no confirma el cambio, la suscripción conserva su método de pago anterior y la API devuelve 502 BILLING_PLATFORM_ERROR: reintenta con un nuevo X-Idempotency-Key.
Esta API se habilita por cuenta. Contacta a tu Key Account Manager para solicitar acceso.
Portal del cliente
El portal del cliente de Stripe funciona con estas suscripciones. Los clientes pueden actualizar la suscripción, cambiar de método de pago, establecer un método de pago predeterminado y cancelar. El portal tampoco puede agregar un descuento a una suscripción con un método de pago personalizado cuando el comportamiento de prorrateo de la sesión del portal esalways_invoice.
Qué ves en Stripe
Dos cosas en el dashboard de Stripe parecen incorrectas y no lo son:- Un pago cancelado en cada factura. Stripe crea su propio PaymentIntent para cada factura
charge_automaticallyy lo cancela una vez que Yuno informa el pago. Cada factura incluye una entradaCanceledjunto a la de Yuno. Stripe documenta esto como comportamiento esperado. No cambia ni la factura ni el estado de la suscripción. - Una entrada de pago por factura, no una por intento. Yuno informa cada reintento contra el registro de pago existente. Una factura recuperada muestra un pago con el historial de sus intentos, no una entrada fallida más una exitosa.
metadata que envías también se copia a los registros de pago de Stripe. Consulta Los metadatos de tu pago en el registro de pago de Stripe.
Reembolsos
Reembolsa a través de la API o del dashboard de Yuno como con cualquier pago. Yuno informa el reembolso a Stripe y crea la nota de crédito correspondiente, para que tus registros de Stripe se mantengan consistentes. Se admiten reembolsos totales y parciales. Para los pagos realizados conexternal_invoice (recargas), consulta Reembolsos.
Disputas
Stripe no puede gestionar disputas de pagos que no procesó. Un contracargo en uno de estos pagos te llega a través del proveedor de Yuno que procesó el cobro, y lo gestionas en Yuno. Consulta Gestión de contracargos.Tarifas de Billing
Stripe cuenta el volumen que procesa Yuno dentro de tu volumen total de Stripe Billing y lo cobra según tu contrato de Billing. Las facturas únicas pagadas a través de un procesador de terceros también se facturan según los precios de Invoicing de Stripe.Prueba en sandbox
- Vincula tu sandbox. Haz el onboarding de tu cuenta sandbox de Yuno con una clave restringida y un ID de método de pago personalizado del modo de prueba de Stripe. Yuno los gestiona, y las facturas de los test clocks de Stripe, igual que las de producción.
- Registro y renovaciones. Crea la suscripción en un test clock de Stripe, paga la primera factura a través de tu checkout sandbox de Yuno y luego avanza el reloj más allá de la fecha de renovación. Verifica que aparezca un nuevo pago en Yuno y que la factura esté pagada en Stripe.
- Reintentos. Usa una tarjeta de prueba de Yuno que rechace, luego avanza el reloj más allá de
next_payment_attempt. Si el evento de reintento no llega, avanza el reloj de nuevo aproximadamente un minuto. - Cobro de deuda en tiempo real. Para validar el cobro de deuda tal como opera producción, crea una suscripción sin test clock con un calendario de reintentos personalizado corto y déjala correr.
Lista de verificación de integración
Stripe: habilita el procesamiento de pagos de terceros
Onboarding de Yuno: comparte una clave de API restringida de Stripe y un ID de método de pago personalizado
Stripe: configura los reintentos
Stripe: restringe el portal del cliente
Backend: crea la suscripción
payment_behavior: default_incomplete y expande latest_invoice.Backend: crea el primer pago en Yuno
vault_on_success: true, external_subscription y el amount_due convertido dentro de las 23 horas.Backend: gestiona las pruebas gratuitas
verify.external_subscription para las suscripciones con trial_end.Backend: gestiona el último intento fallido
next_payment_attempt: null e inicia tus emails de cobro de deuda y el flujo de actualización de tarjeta.Prueba en sandbox
Solución de problemas
PayPal
Puedes cobrar pagos de suscripción con PayPal mediante la integración de Stripe Billing. El primer pago guarda la cuenta de PayPal del cliente, y cada renovación cobra esa cuenta guardada. PayPal se habilita por organización: tu Technical Account Manager lo activa después de los pasos siguientes.Antes de empezar
Completa estos pasos con tu Technical Account Manager (TAM):- Comparte los datos de tu cuenta de PayPal. Tanto para sandbox como para producción: tu Merchant ID de PayPal (el payer ID que aparece en tu dashboard de PayPal), la vertical de negocio que PayPal asignó a tu cuenta y si PayPal marca tu cuenta como de alto riesgo. Tu TAM los configura en tu conexión de PayPal en Yuno. Los pagos de suscripción con PayPal no se pueden procesar sin ellos.
- Habilita Vault en PayPal. En las apps de PayPal conectadas a Yuno, sandbox y producción, habilita Vault (guardar métodos de pago). Las renovaciones cobran la cuenta de PayPal guardada, por lo que Vault es obligatorio.
- Crea un método de pago personalizado “PayPal” en Stripe. En el Stripe Dashboard, ve a Settings → Payment methods → Custom payment methods y crea uno llamado PayPal. Si quieres que los pagos con tarjeta aparezcan como Card, crea también uno “Card”. Hazlo tanto en modo producción como en modo de prueba, y envía los IDs (empiezan con
cpmt_) a tu TAM.
Qué esperar
- Los pagos de suscripción y las renovaciones realizados con PayPal aparecen en Stripe con el nombre de método de pago PayPal. Los pagos de recarga aparecen como Yuno.
- PayPal no puede verificar una cuenta con un pago de 0.00, como lo hacen las tarjetas. Cuando una suscripción empieza con una prueba, envía un pago de 1.00 en la moneda de la suscripción, con el objeto
external_subscriptionde la suscripción. Yuno lo reembolsa automáticamente y no lo informa a Stripe como un pago. Esto se habilita por organización; hasta entonces, el 1.00 no se reembolsa automáticamente.