Integración inicial con Stripe

Adapty admite flujos de suscripción web2app rastreando pagos y suscripciones web realizados a través de Stripe.

Esta integración cubre compras iniciadas en la web (Stripe Checkout, páginas de pago alojadas o flujos web personalizados) y las sincroniza con el acceso a la app móvil y con los datos de analítica.

Es útil en los siguientes escenarios:

• Proporcionar automáticamente acceso a funciones de pago a usuarios que compraron en la web y después instalaron la app e iniciaron sesión en su cuenta
• Centralizar toda la analítica de suscripciones en un único Adapty Dashboard (incluidas cohortes, predicciones y el resto de las herramientas de analítica)

Aunque las compras web son cada vez más populares para las apps, la Apple App Store solo permite un sistema diferente al de las compras in-app para bienes digitales en Estados Unidos. Asegúrate de no promocionar tus suscripciones web dentro de la app en otros países, ya que podrías recibir un rechazo o un baneo.

A continuación se describen los pasos para configurar la integración con Stripe.

1. Conectar Stripe a Adapty

Esta integración se basa principalmente en que Adapty obtenga datos de suscripciones de Stripe a través del webhook. Por eso, debes conectar tu cuenta de Adapty a tu cuenta de Stripe proporcionando las API Keys 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. Decide si vas a conectar Stripe en modo test o en modo live. Si lo haces primero en modo test, deberás repetir los pasos a continuación para el modo live.

1. Ve al Stripe App Marketplace e instala la app de Adapty. Ten en cuenta que el modo sandbox no permite instalar apps; solo puedes hacerlo en modo de producción o test.

2. Concede a la app los permisos necesarios. Esto permitirá a Adapty acceder 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 elegir si instalar la app en modo live o test.

3. En el pop-up, genera una nueva clave restringida. Deberás verificar tu identidad mediante tu correo electrónico, Touch ID o clave de seguridad. Una vez generada la 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 test y live.

¡Listo! A continuación, crea tus productos en Stripe y agrégalos 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 button 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 Webhook URL de 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
   • 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 “Reveal” bajo “Signing secret”. Esta es la clave que se usa para decodificar los datos del webhook en Adapty; cópiala tras revelarla:

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

2. Crear productos en Stripe

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

3. Añadir productos de Stripe a Adapty

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

Los IDs de producto en Stripe tienen el formato prod_... y los IDs de precio 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 añadidos todos los productos necesarios, el siguiente paso es informar a Stripe sobre qué usuario está realizando la compra, para que Adapty pueda identificarlo.

4. Enriquecer las compras web con tu ID de usuario

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

Para que los niveles de acceso sean consistentes entre plataformas (web o móvil), debes asegurarte de que haya un único ID de usuario en el que Adapty pueda basarse al reconocer los webhooks. Puede ser el correo electrónico, el número de teléfono o cualquier otro ID del sistema de autenticación que utilices.

Decide qué ID quieres usar para identificar a tus usuarios. 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 la Suscripción de Stripe (sub_...) o del objeto Checkout Session (ses_...) con la clave 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.

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

Para asegurarte de que tus 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 Identificar usuarios iOS, Android, React Native, Flutter y Unity para más información).

6. Probar 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 Test de Stripe se considerarán Sandbox en Adapty.

Comportamiento de creación de perfiles

Adapty necesita 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: el customer_user_id que proporcionaste en el metadata en el paso 4 anterior
2. El campo email del objeto Customer de Stripe (consulta la documentación de Stripe)
3. El campo client_reference_id del objeto Session de Stripe (consulta la documentación de Stripe)

Puedes configurar qué ID quieres usar en App Settings → Stripe.

También tienes una cuarta opción: no crear perfiles en absoluto, aunque no se recomienda por las limitaciones descritas anteriormente en Analytics.

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 suscripciones:

1. Cancelación inmediata: la suscripción se cancela de inmediato con o sin opción 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 los stores 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. De momento no admitimos el período de gracia de Stripe; esto formará parte de versiones futuras.

Reembolsos

Adapty solo rastrea reembolsos totales. Los reembolsos parciales o por prorrateo no están soportados actualmente.

Unicidad del ID de transacción

Adapty vincula perfiles y transacciones usando store_transaction_id y store_original_transaction_id. Estos deben ser únicos entre los entornos de Test y Producción.

Por qué esto 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 Test
• IDs de producto y entornos incorrectos en las respuestas de la API
• Problemas en la vinculación de perfiles y en los eventos de suscripción

Cómo garantizar la unicidad

Los IDs de factura de Stripe pueden solaparse entre los entornos Test y Live. Para evitar colisiones entre entornos, elige una de estas opciones:

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

Configura prefijos por separado para cada entorno:

1. En el Stripe Dashboard, cambia al modo Test.
2. Ve a Settings → Billing → Invoices.
3. Establece Invoice numbering en Sequentially across your account.
4. Establece Invoice prefix en TEST- (o cualquier otro prefijo específico del entorno de test).
5. Cambia al modo Live y repite los pasos 2-4, usando LIVE- (o cualquier otro prefijo específico del entorno de producción) como prefijo.

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

Establece Invoice numbering en Stripe settings -> Billing -> pestaña Invoices en 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.

Saca más partido a tus datos de Stripe

Una vez integrado con Stripe, Adapty está listo para ofrecer información de inmediato. Para aprovechar al máximo tus datos de Stripe, puedes configurar integraciones adicionales de Adapty para reenviar eventos de Stripe y centralizar 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 soportados

Adapty admite los siguientes eventos de Stripe:

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