Integración inicial con Stripe

Adapty admite flujos de suscripción web2app mediante el seguimiento de pagos y suscripciones realizados a través de Stripe.

Esta integración cubre compras iniciadas desde 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 la analítica.

Es útil en los siguientes escenarios:

• Proporcionar acceso automático a funciones de pago para usuarios que compraron en la web pero luego instalaron la app e iniciaron sesión en su cuenta
• Tener toda la analítica de suscripciones en un único Adapty Dashboard (incluyendo cohortes, predicciones y el resto de herramientas de analítica)

Aunque las compras web son cada vez más populares para las apps, el App Store de Apple permite un sistema diferente al de las compras in-app para productos digitales únicamente 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 vetada.

Los pasos a continuación describen 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
   • 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 depende de los webhooks de Stripe para proporcionar y actualizar los niveles de acceso de los usuarios como única fuente de información. 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 confiar y que Adapty pueda reconocer a partir de los webhooks. Podría ser el correo electrónico del usuario, su número de teléfono o cualquier otro ID del sistema de autorización que estés utilizando.

Determina qué ID deseas 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 Stripe Subscription (sub_...) o del objeto Checkout Session (ses_...) como customer_user_id, así:

{'customer_user_id': "YOUR_USER_ID"}

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

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. Predeterminado y recomendado: el customer_user_id que proporcionaste en los metadatos en el paso 4 anterior
2. email en el objeto Customer de Stripe (consulta la documentación de Stripe)
3. client_reference_id en el objeto Session de Stripe (consulta la documentación de Stripe)

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

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 a través de Stripe Checkout o Payment Links

Adapty realiza el seguimiento de compras únicas (no de suscripción) realizadas a través de Stripe Checkout (mode=payment) o Payment Links solo si Stripe genera una factura para la compra. De forma predeterminada, Stripe no crea una factura para compras únicas de Checkout. En este caso, payment_intent.succeeded llega sin datos de factura, lo cual no es suficiente para que Adapty registre la transacción.

Para realizar el seguimiento de compras únicas de Checkout en Adapty, activa la creación de facturas cuando crees la sesión. Stripe generará entonces una factura y emitirá los eventos invoice.created e invoice.updated relacionados, que Adapty procesa para registrar la transacción.

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
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded