Integración inicial con Stripe

Adapty admite flows de web2app rastreando los pagos y suscripciones realizados a través de Stripe.

Esta integración cubre las compras iniciadas desde la web (Stripe Checkout, páginas de pago alojadas, Payment Links o flujos web personalizados) y las sincroniza con el acceso en la app móvil y los análisis.

Es útil en los siguientes escenarios:

• Proporcionar automáticamente acceso a las funciones de pago a usuarios que compraron en la web pero que posteriormente instalaron la app e iniciaron sesión en su cuenta
• Tener todos los análisis de suscripciones en un único Adapty Dashboard (incluidas cohortes, predicciones y el resto de nuestras herramientas de análisis)

Aunque las compras web son cada vez más populares para las apps, Apple App Store permite un sistema diferente al de las compras in-app únicamente para bienes digitales y solo en EE. UU. Asegúrate de no promocionar tus suscripciones web dentro de tu app para otros países. De lo contrario, tu app podría ser rechazada o eliminada.

Los pasos a continuación explican cómo configurar la integración con Stripe.

1. Conecta Stripe a Adapty

Esta integración se basa principalmente en que Adapty obtenga datos de suscripción de Stripe a través del webhook. Por lo tanto, necesitas conectar tu cuenta de Adapty a tu cuenta de Stripe proporcionando las claves API y usando la URL del webhook de Adapty en Stripe. Para automatizar la configuración del webhook, instala la app de Adapty en Stripe:

0. Determina si vas a conectar Stripe en modo de prueba o en modo en vivo. Si lo haces inicialmente en modo de prueba, tendrás que repetir los pasos a continuación para el modo en vivo también.

1. Ve al Stripe App Marketplace e instala la app de Adapty. Ten en cuenta que el modo sandbox no admite la instalación de apps. Solo puedes hacerlo en modo de producción o de prueba.

2. Otorga los permisos necesarios a la app. Esto permitirá que Adapty acceda a los datos e historial de suscripciones. Luego, haz clic en Continue to app settings para continuar.

En la parte inferior del pop-up de permisos, puedes seleccionar si instalar la app en modo en vivo o de prueba.

3. En el pop-up, genera una nueva clave restringida. Tendrás que verificar tu identidad mediante tu correo electrónico, Touch ID o clave de seguridad. Una vez que generes una clave, no podrás volver a verla, así que guárdala de forma segura en un gestor de contraseñas o un almacén de secretos.

4. Copia la clave generada del pop-up y ve a App Settings → Stripe en Adapty. Pega la clave en la sección Stripe App Restricted API Key según tu modo. Ten en cuenta que debes generar claves diferentes para los modos de prueba y en vivo.

¡Todo listo! A continuación, crea tus productos en Stripe y añádelos a Adapty.

Flujo de instalación obsoleto

1. Ve a Developers → API Keys en Stripe:

2. Haz clic en el botón Reveal live (test) key junto al título Secret key, cópiala y ve a App Settings → Stripe en Adapty. Pega la clave aquí:

3. A continuación, copia la URL del webhook que aparece en la parte inferior de la misma página en Adapty. Ve a Developers → Webhooks en Stripe y haz clic en el botón Add endpoint:

4. Pega la URL del webhook de Adapty en el campo Endpoint URL. Luego elige Latest API version en el campo Version del webhook. A continuación, selecciona los siguientes eventos:

• charge.refunded
  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
  • invoice.created
  • invoice.updated
  • payment_intent.succeeded

5. Pulsa “Add endpoint” y luego pulsa “Reveal” bajo “Signing secret”. Esta es la clave que se usa para decodificar los datos del webhook en el lado de Adapty; cópiala después de revelarla:

6. Por último, pega esta clave en App Settings → Stripe de Adapty, bajo “Stripe Webhook Secret”:

2. Crea productos en Stripe

Ve al Catálogo de productos de Stripe y crea los productos que deseas vender junto con sus planes de precios. Ten en cuenta que Stripe permite tener múltiples planes de precios por producto, lo cual es útil para adaptar tu oferta sin necesidad de crear productos adicionales.

3. Añade productos de Stripe a Adapty

Tratamos Stripe igual que el App Store y Google Play: es simplemente otra store donde vendes tus productos digitales. Por eso se configura de forma similar: simplemente añade productos de Stripe (concretamente su product_id y price_id) a la sección de Productos de Adapty:

Los IDs de producto en Stripe tienen el formato prod_... y los IDs de precio tienen el formato price_.... Son fáciles de encontrar para cada producto en el Catálogo de productos de Stripe, una vez que abres cualquier producto:

Una vez que hayas añadido todos los productos necesarios, el siguiente paso es informar a Stripe sobre qué usuario está realizando la compra, para que Adapty pueda identificarlo.

4. Enriquece las compras web con tu ID de usuario

Adapty se basa en los webhooks de Stripe para proporcionar y actualizar los niveles de acceso de los usuarios como única fuente de información. Sin embargo, debes proporcionar información adicional desde tu lado cuando trabajes con Stripe para que esta integración funcione correctamente.

Para que los niveles de acceso sean coherentes entre plataformas (web o móvil), debes asegurarte de que haya un único ID de usuario en el que basarte, que Adapty pueda reconocer a través de los webhooks. Puede ser el correo electrónico del usuario, su número de teléfono o cualquier otro ID del sistema de autenticación que estés utilizando. Adapty denomina este valor customer_user_id.

Adapty lee el ID de usuario desde una fuente — la seleccionada en Profile creation behavior en App Settings → Stripe. No es una cadena de respaldo: si la fuente seleccionada está vacía para una transacción concreta, la compra queda anónima aunque el ID esté presente en otro lugar de los datos de Stripe. Consulta Profile creation behavior para ver todas las fuentes disponibles.

Elige la opción que coincida con cómo creas las compras en Stripe.

Sesiones de pago y suscripciones creadas a través de la API de Stripe

Mantén Profile creation behavior configurado en Use customer_user_id from metadata (default). Luego, accede a la parte de tu código que inicializa el pago a través de Stripe — y añade este ID de usuario al objeto metadata de Stripe Subscription (sub_...) o de Checkout Session (ses_...) como customer_user_id, así:

{'customer_user_id': "YOUR_USER_ID"}

Esta simple adición es lo único que tienes que hacer en tu código. Después de eso, Adapty procesará todos los webhooks que reciba de Stripe, extraerá este metadata y asociará correctamente las suscripciones con tus clientes.

Links de pago (sin código)

Si vendes mediante Stripe Payment Links y no tienes backend para establecer metadata, pasa el ID de usuario en el parámetro de consulta client_reference_id del enlace:

https://buy.stripe.com/your_link?client_reference_id=YOUR_USER_ID

Stripe almacena este valor en la Checkout Session y lo envía a Adapty en el evento checkout.session.completed. Funciona tanto para suscripciones como para compras únicas.

5. Proporciona acceso a los usuarios en el móvil

Para asegurarte de que los usuarios móviles que llegan desde la web puedan acceder a las funciones de pago, simplemente llama a Adapty.activate() o Adapty.identify() con el mismo customer_user_id que proporcionaste en el paso anterior (consulta Identificación de usuarios iOS, Android, React Native, Flutter y Unity para más información).

6. Prueba tu integración

Asegúrate de haber completado los pasos anteriores tanto para Sandbox como para Producción. Las transacciones que realices desde el modo de prueba de Stripe se considerarán Sandbox en Adapty.

Comportamiento de creación de perfiles

Adapty debe vincular una compra a un perfil de cliente para que esté disponible en el móvil; por eso, de forma predeterminada, crea perfiles al recibir webhooks de Stripe. Puedes elegir qué usar como ID de usuario del cliente en Adapty:

1. Por defecto y recomendado: Usar customer_user_id de los metadatos — el customer_user_id que proporcionaste en los metadatos en el paso 4 anterior
2. Usar el email del objeto Customer de Stripe (ver documentación de Stripe)
3. Usar client_reference_id del objeto Session de Stripe (ver documentación de Stripe) — la opción a usar con Payment Links

Puedes configurar qué ID quieres usar en App Settings → Stripe. Adapty utiliza únicamente el origen que selecciones aquí para cada transacción de Stripe en la app; no recurre a los demás orígenes como alternativa.

También tienes una cuarta opción para no crear perfiles en absoluto, pero no se recomienda debido a las limitaciones de Analytics mencionadas anteriormente.

Limitaciones actuales

Actualizaciones, degradaciones y prorrateo

Los cambios de suscripción, como actualizaciones o degradaciones, pueden dar lugar a cargos prorrateados. Adapty no tendrá en cuenta estos cargos en los cálculos de ingresos. Lo mejor es deshabilitar estas opciones manualmente desde el dashboard de Stripe. También puedes desactivarlas estableciendo el valor del atributo proration_behaviour en none a través de la API de Stripe.

Cancelaciones

Stripe tiene dos opciones de cancelación de suscripción:

1. Cancelación inmediata: La suscripción se cancela de inmediato con o sin opciones de prorrateo
2. Cancelación al final del período: La suscripción se cancela al final del período de facturación actual (similar a las suscripciones in-app en las tiendas de apps).

Adapty admite ambas opciones, pero el cálculo de ingresos para la cancelación inmediata no tendrá en cuenta la opción de prorrateo.

Problemas de facturación y período de gracia

Cuando un cliente tiene un problema con su pago, Adapty generará un evento de problema de facturación y se revocará el acceso. Aún no admitimos el período de gracia de Stripe; esto formará parte de futuras versiones.

Reembolsos

Adapty solo realiza el seguimiento de reembolsos totales. Los reembolsos prorrateados o parciales no están disponibles actualmente.

Unicidad del ID de transacción

Adapty empareja perfiles y transacciones usando store_transaction_id y store_original_transaction_id. Estos deben ser únicos entre los entornos de prueba y producción.

Por qué importa

Si el mismo ID de transacción existe en ambos entornos, Adapty los trata como una sola transacción, lo que provoca:

• Que las compras de producción hereden los niveles de acceso y los IDs de producto de prueba
• IDs de producto y entornos incorrectos en las respuestas de la API
• Vinculación de perfiles y eventos de suscripción interrumpidos

Cómo garantizar la unicidad

Los IDs de factura de Stripe pueden solaparse entre los entornos de prueba y en vivo. Para evitar colisiones entre entornos, elige una opción:

Opción 1: Numeración a nivel de cuenta con prefijos de entorno

Configura prefijos por separado para cada entorno:

1. En el dashboard de Stripe, cambia al modo de prueba.
2. Ve a Settings → Billing → Invoices.
3. Establece Invoice numbering en Sequentially across your account.
4. Establece Invoice prefix en TEST- (u otro prefijo específico para el entorno de prueba).
5. Cambia al modo en vivo y repite los pasos 2-4, usando LIVE- (u otro prefijo específico para el entorno en vivo) como prefijo.

Opción 2: Numeración a nivel de cliente

Establece Invoice numbering en la pestaña Stripe settings -> Billing -> Invoices como Sequentially for each customer (customer-level).

Incluso con la configuración anterior, si eliminas una factura, Stripe puede reutilizar ese ID para nuevas facturas del mismo cliente. Lo mejor es evitar eliminar facturas siempre que sea posible.

Compras únicas mediante Stripe Checkout o Payment Links

Adapty registra las compras únicas (que no son suscripciones) realizadas a través de Stripe Checkout (mode=payment) o Payment Links a partir del evento checkout.session.completed. Asegúrate de que este evento esté habilitado en tu endpoint de webhook de Adapty en Stripe — los endpoints creados antes de que Adapty añadiera compatibilidad con Payment Links no lo incluyen. Consulta el paso 4 para saber cómo comprobarlo.

Adapty toma el producto del primer elemento de línea de la sesión, por lo que una sesión que vende varios productos solo registra el primero.

Los reembolsos para estas compras aún no se aplican: Stripe entrega charge.refunded, pero Adapty no revoca el acceso para una compra única realizada a través de Checkout o un Payment Link. Los reembolsos de suscripciones y de compras únicas facturadas a través de una factura de Stripe funcionan con normalidad.

Aprovecha al máximo tus datos de Stripe

Una vez que te integres con Stripe, Adapty está listo para proporcionar insights de inmediato. Para sacar el máximo partido a tus datos de Stripe, puedes configurar integraciones adicionales de Adapty para reenviar eventos de Stripe, reuniendo toda la analítica de suscripciones en un único Adapty Dashboard.

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

Integraciones que puedes usar para reenviar y analizar tus eventos de Stripe:

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

Eventos de Stripe compatibles

Adapty admite los siguientes eventos de Stripe:

• charge.refunded
• checkout.session.completed
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded