RevenueCat Stripe Billing

Registra comisiones en suscripciones web gestionadas por la integración de Stripe Billing de RevenueCat, que combina la gestión de suscripciones de RevenueCat con el procesamiento de pagos de Stripe.

Cuando activas el seguimiento de RevenueCat Stripe Billing, puedes atribuir suscripciones web a afiliados mientras RevenueCat gestiona el ciclo de vida de las suscripciones.

Qué puedes registrar

Una vez configurado, Insert Affiliate registra automáticamente:

  • Suscripciones web de RevenueCat procesadas a través de Stripe
  • Compras iniciales de suscripción
  • Renovaciones de suscripción
  • Todas las transacciones gestionadas por la facturación web de RevenueCat

Requisitos previos

Antes de configurar el seguimiento de Insert Affiliate, debes tener:

  • RevenueCat Web SDK instalado y configurado
  • RevenueCat Stripe Billing configurado y conectado a tu cuenta de Stripe
  • Tu propia página de checkout alojada donde pueda ejecutarse el SDK de Insert Affiliate
  • Una cuenta de Stripe lista para conectarse mediante Stripe Connect

Importante: Insert Affiliate requiere que tu checkout esté alojado en tu propio dominio. El SDK debe ejecutarse en tu página para capturar la atribución del afiliado antes de las compras.

Configuración del webhook de RevenueCat

Importante: Al configurar tu webhook de RevenueCat para enviar eventos a Insert Affiliate, debes enviar solo eventos de App Store y Google Play Store, no eventos de Stripe ni de Web Billing.

Como Insert Affiliate recibe los eventos de Stripe directamente a través de Stripe Connect (configurado en el Paso 2 más abajo), enviar eventos del webhook de RevenueCat para transacciones de Stripe/Web Billing provocaría un registro duplicado de transacciones.

Para configurar tu webhook de RevenueCat:

  1. Ve a tu panel de RevenueCat → Project Settings → Integrations → Webhooks
  2. Al configurar el webhook de Insert Affiliate, configúralo para enviar solo eventos de:
    • App Store (iOS)
    • Google Play Store (Android)
  3. No incluyas eventos de Stripe ni de Web Billing en este webhook

Esto garantiza una atribución limpia: las transacciones móviles se registran mediante los webhooks de RevenueCat, mientras que las transacciones web se registran mediante Stripe Connect.

Guía de configuración

Paso 1: Activar los pagos web

  1. Ve a Configuración → Transacciones Basadas en Web en la pestaña Pagos y Cobros
  2. Cambia Método de Transacciones Basadas en Web de "Desactivado" a "Pagos Basados en Web con Stripe"
  3. Haz clic en "Save Settings"
Sección Transacciones Basadas en Web en la configuración del panel de Insert Affiliate con el desplegable del método de transacción web resaltado

Haz clic para ver a tamaño completo

Paso 2: Configurar Stripe Connect

Antes de poder registrar transacciones web, debes conectar tu cuenta de Stripe:

  1. Ve a Configuración → Stripe Connect en la pestaña Pagos y Cobros
  2. Haz clic en "Conectar con Stripe"
  3. Completa el proceso de incorporación de Stripe:
    • Inicia sesión en tu cuenta de Stripe existente (la misma que está conectada a RevenueCat)
    • Proporciona la información comercial requerida
    • Envía los documentos de verificación (si se solicitan)
  4. Se te redirigirá de vuelta a Insert Affiliate al terminar

Indicadores de estado:

  • Active: Tu cuenta de Stripe está totalmente conectada y lista
  • Restricted: Se necesita información adicional, haz clic en "Continuar incorporación"
  • Pending: Documentos en revisión (normalmente de 1 a 2 días hábiles)

✅ Una vez conectada tu cuenta de Stripe, Insert Affiliate recibirá automáticamente todos los eventos de Stripe de tus transacciones de RevenueCat.

Implementación: pasar los códigos de afiliado

Paso 1: Instalar el SDK de Insert Affiliate

Añade el SDK de Insert Affiliate a tu página de checkout web:

npm install insert-affiliate-js-sdk

Paso 2: Inicializar el SDK

Inicializa el SDK en tu página de checkout antes de que los usuarios completen sus compras:

import { InsertAffiliate } from 'insert-affiliate-js-sdk';

// Initialize SDK with your company code
await InsertAffiliate.initialize('your_company_code');

Paso 3: Pasar los datos del afiliado a Stripe Checkout

Al crear una sesión de Stripe Checkout, incluye ambos campos obligatorios en las tres ubicaciones de metadatos para garantizar un registro correcto:

// Get the current affiliate identifier and company ID
const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
const companyId = await InsertAffiliate.returnCompanyId();

// Create Stripe checkout session with metadata
const session = await stripe.checkout.sessions.create({
  line_items: [
    {
      price: 'price_1234',
      quantity: 1,
    },
  ],
  mode: 'subscription',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  // 1. Session metadata (available in checkout.session.completed event)
  metadata: {
    insertAffiliate: affiliateId || '',
    insertAffiliateCompanyId: companyId || '',
  },
  // 2. Subscription metadata (persists with subscription)
  subscription_data: {
    metadata: {
      insertAffiliate: affiliateId || '',
      insertAffiliateCompanyId: companyId || '',
    },
  },
  // 3. Payment Intent metadata (available on each payment)
  payment_intent_data: {
    metadata: {
      insertAffiliate: affiliateId || '',
      insertAffiliateCompanyId: companyId || '',
    },
  },
});

Campos de metadatos obligatorios

Los dos campos siguientes son obligatorios para una atribución correcta de afiliados:

  • insertAffiliate: el código corto (identificador) del afiliado
  • insertAffiliateCompanyId: el ID de tu empresa en Insert Affiliate

Estos campos deben pasarse en las tres ubicaciones de metadatos (sesión, suscripción y payment intent) para garantizar que Insert Affiliate pueda registrar y atribuir los pagos correctamente.

Cómo funciona en conjunto

  1. RevenueCat gestiona el ciclo de vida de la suscripción (pruebas, renovaciones, cancelaciones)
  2. Stripe procesa los pagos reales
  3. Insert Affiliate registra la atribución de afiliados a través de los metadatos de Stripe
  4. Tu checkout alojado ejecuta el SDK de Insert Affiliate para capturar la atribución

Como conectaste tu cuenta de Stripe mediante Stripe Connect (Paso 2), Insert Affiliate recibe automáticamente todos los eventos de Stripe, incluidos los de las suscripciones de RevenueCat, y lee los campos de metadatos para acreditar a los afiliados.

Cómo obtener los valores necesarios

Debes obtener ambos valores del SDK de Insert Affiliate. El SDK gestiona automáticamente la detección de deep links y la atribución de afiliados.

Obtener el identificador del afiliado

El identificador del afiliado puede provenir de varias fuentes:

  • Deep linking: cuando un usuario hace clic en un enlace de afiliado, captura el identificador a través de tu plataforma de deep linking
  • Código corto: los usuarios pueden introducir o aplicar manualmente un código corto de afiliado
  • Parámetros de URL: el SDK los detecta automáticamente

Ver la documentación del JS SDK →

Obtener el ID de empresa

También se requiere el ID de tu empresa en Insert Affiliate.

Ver la documentación del JS SDK →

Pasar los valores a tu backend

Envía ambos valores a tu backend al crear sesiones de checkout:

const response = await fetch('/create-checkout-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_1234',
    insertAffiliate: affiliateId,
    insertAffiliateCompanyId: companyId,
    successUrl: window.location.origin + '/success',
    cancelUrl: window.location.origin + '/cancel',
  }),
});

Probar tu configuración

  1. Activa los Pagos Basados en Web con Stripe en tu configuración
  2. Conecta tu cuenta de Stripe mediante Stripe Connect (pestaña Pagos y Cobros)
  3. Inicializa el SDK de Insert Affiliate en tu página de checkout
  4. Haz una compra de prueba con ambos campos obligatorios (insertAffiliate y insertAffiliateCompanyId) en los metadatos
  5. Revisa tu panel de transacciones para confirmar que aparece la transacción

Solución de problemas

Las transacciones no aparecen

Revisa estos problemas comunes:

  • Estado de Stripe Connect: verifica que tu cuenta de Stripe aparece como "Active" en la configuración (pestaña Pagos y Cobros)
  • Pagos web activados: confirma que "Pagos Basados en Web con Stripe" está seleccionado en la configuración
  • Campos de metadatos obligatorios: confirma que estás pasando ambos insertAffiliate e insertAffiliateCompanyId en las tres ubicaciones de metadatos (session, subscription_data, payment_intent_data)
  • Inicialización del SDK: asegúrate de que el SDK de Insert Affiliate esté correctamente inicializado en tu página de checkout y devuelva valores válidos
  • Conexión de RevenueCat con Stripe: verifica que RevenueCat esté correctamente conectado a la misma cuenta de Stripe que conectaste mediante Stripe Connect
  • Checkout alojado: confirma que el SDK de Insert Affiliate se está ejecutando en tu propia página de checkout alojada (no en una página alojada por terceros)

El SDK no detecta al afiliado

  • Configuración de deep links: verifica que tu plataforma de deep linking esté configurada correctamente
  • Parámetros de URL: comprueba que los enlaces de afiliado incluyan el parámetro insertAffiliate correcto
  • Momento de inicialización del SDK: asegúrate de que el SDK se inicialice antes de que los usuarios lleguen a tu página de checkout

Qué pasa después

Una vez configurado:

  1. Las compras con metadatos de afiliado crean automáticamente registros de comisión
  2. Consulta todas las transacciones en tu panel
  3. Configura las tasas de comisión por afiliado
  4. Configura los métodos de pago para pagar a tus afiliados
  5. RevenueCat sigue gestionando las suscripciones mientras Insert Affiliate registra la atribución