Guía de integración con Stripe: conecta FlyCode a Stripe Billing
Conecta FlyCode a Stripe Billing paso a paso: requisitos previos, instalación de la app verificada de Stripe, cambios en la configuración de reintentos y email, llamadas a la API y lista de verificación para salir en producción.
Para quién es esto
Empresas de suscripción que facturan a través de Stripe Billing (suscripciones y facturas) y que desean recuperar más pagos fallidos que con Stripe Smart Retries por sí solo. Si facturas a través de Shopify, Recharge, Skio, Braintree o PayPal, consulta Plataformas de pago y suscripción compatibles.
En qué se diferencia FlyCode de la recuperación integrada de Stripe
Stripe Smart Retries aplica una estrategia de reintento entrenada en todos los comercios de Stripe y limita los intentos a 8 por factura. FlyCode entrena un modelo con tus propias transacciones y las respuestas de los emisores, elige el momento del reintento para cada factura, coordina los correos con los reintentos en lugar de enviar un correo en cada intento y puede cobrar una tarjeta de respaldo registrada. Por lo general, los comercios recuperan alrededor de un 20 por ciento más de pagos fallidos, un aumento de entre el 5 y el 9 por ciento en ARR. Detalles: Guía completa de Stripe Smart Retries.
Requisitos previos
Una cuenta de Stripe que usa Stripe Billing para suscripciones, con permiso para instalar aplicaciones (rol de Administrador o Desarrollador).
Acceso a la configuración de Revenue Recovery de Stripe (Configuración, Billing, Revenue recovery).
Una cuenta de FlyCode. Si aún no tienes una, empieza aquí; la instalación desde el marketplace también inicia el flujo de registro.
Opcional: si quieres que FlyCode envíe correos de recuperación desde tu dominio, la capacidad de añadir registros DNS SPF y DKIM para un subdominio de envío.
Configuración
Instala la aplicación FlyCode
Abre la aplicación FlyCode en el Stripe App Marketplace y haz clic en Instalar. Revisa y confirma los permisos que muestra Stripe: FlyCode lee clientes, suscripciones, facturas, intenciones de pago y cargos, y escribe metadatos de factura, pagos de factura y estado de la suscripción. Nada más. Al instalarse, FlyCode carga todas las facturas que actualmente están en estado de error para que la recuperación empiece con tu cartera actual vencida, no solo con nuevos fallos.
Configura los ajustes de reintento de Stripe
Ve a Revenue recovery, Reintentos y realiza estos cambios en este orden.
Estado de la suscripción y de la factura después de una recuperación fallida: configúralo en «dejar como vencida». Esto permite que FlyCode gestione los estados posteriores a la recuperación sin que Stripe cancele las suscripciones según su propio cronograma.
Reintentos con tarjeta: elige «Personalizado» y configura 3 reintentos con un intervalo de 7 días, para un período máximo de recuperación de 7 días. Esto mantiene al mínimo los reintentos propios de Stripe para que el motor de FlyCode controle el momento del reintento.
Reintentos ACH: si aceptas ACH, deja activado el interruptor de reintentos ACH. La recuperación con tarjeta de FlyCode no sustituye los reintentos de débito bancario de Stripe.
Configura los ajustes de correo de Stripe
Ve a Revenue recovery, Correos.
Correos por pago fallido: si estás usando las notificaciones de recuperación de FlyCode (recomendado), desactiva los correos predeterminados de recuperación de pagos de Stripe para que los clientes no reciban dos conjuntos de mensajes.
Correos por débito ACH fallido: si aceptas ACH, déjalos activados.
Correos de recordatorio de tarjeta: mantén activados los correos de recordatorio de tarjeta de Stripe.
Configura las preferencias de FlyCode y activa
En FlyCode, confirma dos preferencias: el modo de reintento (deja la programación predeterminada guiada por el modelo, salvo que tengas un motivo para no hacerlo) y si FlyCode enviará correos de recuperación en tu nombre. Si lo hace, añade los registros SPF y DKIM que te proporciona FlyCode para que los mensajes se autentiquen desde tu dominio. Luego activa la aplicación. FlyCode comienza a trabajar de inmediato en las facturas fallidas abiertas.
Cómo funciona la integración
La aplicación FlyCode conecta tu cuenta de Stripe con el motor de recuperación de FlyCode. Escucha eventos webhook de Stripe para obtener actualizaciones en tiempo real sobre suscripciones y pagos, pasa los datos relevantes al motor y ejecuta las decisiones del motor a través de la API de Stripe. Todo se ejecuta de forma transparente y se refleja en tu panel de Stripe.
Lo que FlyCode lee: eventos webhook
La aplicación solo se suscribe a los eventos de Stripe necesarios para la recuperación y la gestión de suscripciones: eventos de factura (creada, finalizada, pago fallido, pagada, actualizada), eventos de intención de pago y cargo (pago fallido, সফলido), y eventos de cliente y suscripción (creado, actualizado, eliminado). Estos proporcionan al motor el código de rechazo, los detalles de la tarjeta y del emisor, y el historial de la cuenta que necesita para programar cada reintento. La aplicación usa su propia suscripción de eventos con alcance de aplicación y no toca los puntos de conexión webhook creados por tu equipo o por otras aplicaciones.
Lo que FlyCode escribe: llamadas a la API de Stripe
Estas son las únicas llamadas de escritura (POST) que hace la aplicación FlyCode. Cada una queda registrada en el portal para desarrolladores de Stripe y es visible en el objeto correspondiente del panel.
Marcar una factura como en recuperación
Actualizar factura: añade metadatos flycode_recovery: true
Cuando una factura de suscripción fallida entra en recuperación
Campo de metadatos en la página de la factura; entrada de Actualizar factura en el registro de eventos de la factura
Reintentar una factura fallida
Cuando el motor decide el momento del reintento
Entrada en la actividad reciente de la factura; nuevo cargo bajo la intención de pago original (sin objetos de pago adicionales)
Cancelar una suscripción irrecuperable (opcional, activado por defecto)
Cancelar suscripción, con cancellation_details
Después del número máximo de reintentos sin éxito
Suscripción mostrada como cancelada con el evento de cancelación
Cerrar la factura no recuperada (opcional, activado por defecto)
Anular factura o Marcar como incobrable, según prefieras
En el mismo momento que la cancelación; también se aplica a las facturas abiertas posteriores de la misma suscripción
Estado de la factura anulada o incobrable con el evento registrado
Antes de cada escritura, la aplicación vuelve a leer el estado actual del objeto de Stripe. Si una factura ya fue pagada, anulada o cancelada por otro sistema, FlyCode no realiza ninguna acción. Esto hace que la integración sea idempotente y evita cargos duplicados o conflictos de estado.
Correos de recuperación
Para obtener los mejores resultados y una experiencia de marca coherente, desactiva los correos de recuperación predeterminados de Stripe y usa las notificaciones de FlyCode. El motor las activa en sincronía con el calendario de reintentos (sin correo después de un rechazo temporal mientras un reintento aún tiene buenas posibilidades), se envían desde tu propio dominio en el idioma de tu marca y se programan según las horas locales del cliente. Consulta Seguimiento de pagos fallidos.
Lista de verificación para la puesta en marcha
Qué esperar después de ponerlo en marcha
Facturas abiertas en recuperación. En Stripe, abre Facturas y aplica este filtro (estado abierto, facturas de suscripción, total superior a cero). Haz clic en «Editar columnas» y añade «FlyCode Recovery (metadata)» para ver la marca de recuperación en cada fila.
Tasa de recuperación. Sigue usando el panel de Revenue Recovery de Stripe. Las facturas recuperadas por FlyCode aparecen allí como recuperadas; la visualización de Stripe no cambia. El panel propio de FlyCode añade la recuperación por código de rechazo, la velocidad de recuperación, los intentos por factura recuperada y los ingresos recuperados frente a tu línea base previa a FlyCode.
Cronograma. Por lo general, el motor necesita de 6 a 8 semanas para optimizar su modelo para tu base de clientes; la recuperación mejora durante ese período. La función Go Back in Time de FlyCode también revisita facturas que fallaron hasta unos 60 días antes de la activación, por lo que las tasas de recuperación de meses anteriores pueden aumentar después de ponerlo en marcha.
La cifra de «En recuperación» de Stripe. En el desglose de Revenue Recovery, Stripe define «En recuperación» según la duración máxima personalizada de reintentos que configures (7 días), no según la ventana real de recuperación de FlyCode, por lo que ese segmento naranja subestima las facturas en las que FlyCode sigue trabajando. Usa el filtro de facturas de arriba o el panel de FlyCode para obtener la cifra exacta.
Solución de problemas
Los clientes recibieron dos correos sobre el mismo pago fallido. Los correos de recuperación predeterminados de Stripe siguen activados. Desactívalos en Revenue recovery, Correos (Paso 3), o configura FlyCode en solo reintentos si quieres que Stripe u otra herramienta gestione los mensajes.
Stripe sigue reintentando según su propio cronograma. Los reintentos con tarjeta no están configurados en Personalizado, 3 reintentos a intervalos de 7 días (Paso 2). Dos motores de reintento en una misma tarjeta pueden superar los límites de intentos de la red de tarjetas y reducir las tasas de autorización.
Se canceló una suscripción después de que FlyCode agotara sus reintentos, y no esperábamos que ocurriera. Los pasos de cancelación y limpieza de facturas están activados por defecto. Desactívalos en FlyCode si prefieres mantener las suscripciones no recuperadas como vencidas, y ten en cuenta que la salvaguarda ya evita la cancelación cuando se ha pagado una factura posterior.
Una factura no muestra los flycode_recovery metadatos. Solo las facturas de suscripción fallidas entran en recuperación; las facturas únicas y las facturas que fallaron antes de la ventana de retrocarga de la aplicación no se etiquetan. Comprueba que la factura sea una factura de suscripción con estado abierto y fallo de pago, y que la aplicación esté activada.
La tasa de recuperación en Stripe parece sin cambios en las primeras semanas. El modelo está en su período de optimización de 6 a 8 semanas, y el panel de Stripe atribuye las facturas recuperadas sin distinguir las de FlyCode. Compárala con tu línea base en el panel de FlyCode, que es lo que usa la facturación basada en resultados.
La cantidad de «En recuperación» en Stripe parece demasiado baja. Es lo esperado; consulta la nota anterior sobre cómo la define Stripe.
¿Sigues atascado? Envía un correo al soporte o reserva tiempo con el equipo.
Preguntas frecuentes
¿FlyCode necesita tiempo de ingeniería? No. La instalación es una aplicación de Stripe; los únicos pasos manuales son los ajustes de Stripe anteriores. La mayoría de los comercios están en producción en menos de una hora.
¿FlyCode interferirá con mis webhooks o aplicaciones existentes? No. Usa su propia suscripción de eventos con alcance de aplicación, nunca modifica tus puntos de conexión webhook, reglas de Radar ni otras aplicaciones, y vuelve a comprobar el estado del objeto antes de cada escritura.
¿FlyCode toca los fondos? No. Los reintentos son llamadas de Pagar factura a través de tu cuenta de Stripe; los ingresos recuperados se liquidan en tu saldo de Stripe con normalidad.
¿Puedo mantener activado Stripe Smart Retries? Mantienes técnicamente activada la función de reintentos de Stripe, pero minimizada al cronograma personalizado del Paso 2 para que FlyCode controle el momento. Ejecutar ambos en paralelo de forma completa desperdicia intentos.
¿Qué ocurre con las facturas que ya fallaban antes de que lo instalara? Se cargan al instalarse y entran en recuperación; la función Go Back in Time cubre aproximadamente los 60 días anteriores.
¿Cómo se cobra FlyCode en Stripe? Basado en resultados: una parte de los ingresos recuperados por encima de tu línea base, nada de lo que Stripe habría recuperado de todos modos. Consulta ¿Cómo se cobra FlyCode para los usuarios de Stripe?
Relacionado
FlyCode y Stripe en el Centro de ayuda
Última actualización
¿Te fue útil?