---
title: "Integración inicial con Stripe"
description: "Integra Stripe con Adapty para gestionar pagos de suscripciones sin problemas."
---

Adapty admite flujos de suscripción web2app rastreando pagos y suscripciones web realizados a través de [Stripe](https://stripe.com/).

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.

:::important
Esta integración se centra en rastrear y sincronizar compras web de Stripe. Si necesitas redirigir a los usuarios desde la app a un checkout web, consulta [Paywalls web](web-paywall).
:::

## 1\. Conectar Stripe a Adapty \{#1-connect-stripe-to-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:

:::note
Los pasos a continuación son los mismos para los modos de Producción y Test de Stripe, pero deberás usar diferentes API keys para cada uno.
:::

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](https://marketplace.stripe.com/apps/adapty) 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.

      <img src="/assets/shared/img/stripe1.png"/>

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.

      <img src="/assets/shared/img/stripe2.png"/>

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.

      <img src="/assets/shared/img/stripe4.png"/>

4. Copia la clave generada del pop-up y ve a [App Settings → Stripe](https://app.adapty.io/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.

      <img src="/assets/shared/img/Stripe3.png"/>

¡Listo! A continuación, crea tus productos en Stripe y agrégalos a Adapty.

<Details>

<summary>Flujo de instalación obsoleto</summary>

1. Ve a [Developers → API Keys](https://dashboard.stripe.com/apikeys) en Stripe:

  <img src="/assets/shared/img/6549602-CleanShot_2023-12-06_at_17.29.122x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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](https://app.adapty.io/settings/stripe) en Adapty. Pega la clave aquí:

  <img src="/assets/shared/img/2989508-CleanShot_2023-12-07_at_14.59.122x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

3. A continuación, copia la Webhook URL de la parte inferior de la misma página en Adapty. Ve a [**Developers** → **Webhooks**](https://dashboard.stripe.com/webhooks) en Stripe y haz clic en el botón **Add endpoint**:

  <img src="/assets/shared/img/e7149f5-CleanShot_2023-12-07_at_17.31.392x.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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

  <img src="/assets/shared/img/cbc5404-CleanShot_2023-12-07_at_17.36.232x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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:

  <img src="/assets/shared/img/0460cbb-CleanShot_2023-12-07_at_17.52.582x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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

  <img src="/assets/shared/img/055db20-CleanShot_2023-12-07_at_14.56.212x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

</Details>

## 2\. Crear productos en Stripe \{#2-create-products-on-stripe\}

:::note
Si estás configurando esto en modo test, asegúrate de que Stripe también esté en modo Test antes de continuar con este paso.
:::

Ve al [Catálogo de productos](https://dashboard.stripe.com/products?active=true) 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.

  <img src="/assets/shared/img/b202e2e-CleanShot_2023-12-06_at_15.06.262x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

:::warning
Por el momento, Adapty solo admite precios de tipo **Flat rate** ($9,99/mes) o **Package pricing** ($9,99/10 unidades), ya que se comportan de forma similar a los stores de apps. Las opciones **Tiered pricing**, **Usage-based fee** y **Customer chooses price** no están soportadas.
:::

## 3\. Añadir productos de Stripe a Adapty \{#3-add-stripe-products-to-adapty\}

:::warning

¡Los productos son obligatorios! Asegúrate de crear tus productos de Stripe en el Adapty Dashboard. Adapty solo rastrea eventos para transacciones vinculadas a estos productos, así que no omitas este paso; de lo contrario, no se crearán eventos de transacción.

:::

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:

  <img src="/assets/shared/img/stripe-add-product.webp"
  style={{
    border: 'none', /* border width and color */
    width: '500px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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](https://dashboard.stripe.com/products?active=true) de Stripe, una vez que abres cualquier producto:

  <img src="/assets/shared/img/14a72d7-CleanShot_2023-12-06_at_17.32.512x.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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 \{#4-enrich-purchases-made-on-the-web-with-your-user-id\}

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](https://docs.stripe.com/api/subscriptions/object#subscription_object-metadata) (`sub_...`) o del objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-metadata) (`ses_...`) con la clave `customer_user_id`, así:

```json showLineNumbers title="Stripe Metadata contents"
{'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.

:::warning
El ID de usuario es obligatorio

De lo contrario, no tenemos forma de identificar a este usuario y otorgarle el nivel de acceso en el móvil.

Si no proporcionas `customer_user_id` en el `metadata`, tendrás la opción de hacer que Adapty busque `customer_user_id` en otros lugares: bien en el campo `email` del objeto Customer de Stripe, o bien en el `client_reference_id` de la Session de Stripe.

Más información sobre cómo configurar el comportamiento de creación de perfiles [más abajo](stripe#profile-creation-behavior).
:::

:::note
El Customer en Stripe también es obligatorio

Si usas Checkout Sessions, [asegúrate de que estás creando un Customer de Stripe](https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-customer_creation) estableciendo `customer_creation` en `always`.
:::

## 5\. Dar acceso a los usuarios en el móvil \{#5-provide-access-to-users-on-the-mobile\}

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 <InlineTooltip tooltip="Identificar usuarios">[iOS](identifying-users), [Android](android-identifying-users), [React Native](react-native-identifying-users), [Flutter](flutter-identifying-users) y [Unity](unity-identifying-users)</InlineTooltip> para más información).

## 6\. Probar tu integración \{#6-test-your-integration\}

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.

:::info
¡Eso es todo!

Tus usuarios ya pueden completar compras en la web y acceder a las funciones de pago en tu app. Además, puedes ver toda la analítica de suscripciones en un único lugar.
:::

## Comportamiento de creación de perfiles \{#profile-creation-behavior\}

Adapty necesita vincular una compra a un [perfil de cliente](profiles-crm) 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](stripe#4-enrich-purchases-made-on-the-web-with-your-user-id)
2. El campo `email` del objeto Customer de Stripe (consulta la [documentación de Stripe](https://docs.stripe.com/api/customers/object#customer_object-email))
3. El campo `client_reference_id` del objeto Session de Stripe (consulta la [documentación de Stripe](https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-client_reference_id))

Puedes configurar qué ID quieres usar en [App Settings → Stripe](https://app.adapty.io/settings/stripe).

:::warning
**Nota:** si una transacción concreta de Stripe no contiene el ID especificado, no se creará ningún perfil. Esa transacción permanecerá anónima hasta que sea recogida por algún perfil (por ejemplo, si usas [validación S2S](api-adapty/operations/validateStripePurchase) más adelante y nos informas manualmente sobre esa transacción).

Aparecerá en Analytics, pero no en las secciones que dependen del conteo de perfiles (LTV, Cohortes, Conversiones, etc.) y no podrás verla en el Event feed.
:::

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 \{#current-limitations\}

### Actualizaciones, degradaciones y prorrateo \{#upgrading-downgrading-and-proration\}

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 \{#cancellations\}

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 \{#billing-issues-and-grace-period\}

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 \{#refunds\}

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

### Unicidad del ID de transacción \{#transaction-id-uniqueness\}

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 \{#why-this-matters\}

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 \{#how-to-ensure-uniqueness\}

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 \{#option-1-account-level-numbering-with-environment-prefixes\}

Configura prefijos por separado para cada entorno:

1. En el Stripe Dashboard, cambia al modo Test.
2. Ve a [Settings → Billing → Invoices](https://dashboard.stripe.com/settings/account/?support_details=true).
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 \{#option-2-customer-level-numbering\}

Establece **Invoice numbering** en [**Stripe settings** -> **Billing** -> pestaña **Invoices**](https://dashboard.stripe.com/settings/account/?support_details=true) 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 \{#get-more-from-your-stripe-data\}
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.

:::tip
Para mejorar la analítica, puedes incluir un `variation_id` en tus metadatos de Stripe para atribuir compras a instancias específicas de paywall. Esto es especialmente útil cuando implementas paywalls web propios y quieres rastrear qué paywall concreto llevó a la conversión.

Ten en cuenta que `variation_id` solo se lee de los metadatos en los objetos Stripe Subscription (`sub_...`) y Checkout Session (`ses_...`):

```json showLineNumbers title="Stripe Metadata with variation_id"
{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}
```
:::

Integraciones que puedes usar para reenviar y analizar tus eventos de Stripe:
- [Amplitude](amplitude/)
- [Webhook](webhook)
- [Firebase](firebase-and-google-analytics)
- [Mixpanel](mixpanel)
- [Posthog](posthog)

### Eventos de Stripe soportados \{#supported-stripe-events\}
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