Transacciones web de Stripe

Registra comisiones en las compras realizadas mediante Stripe Checkout y en las suscripciones de tu sitio web, no solo en las compras dentro de la app.

Cuando activas los Pagos Basados en Web con Stripe en tu configuración, puedes registrar transacciones web junto con tus compras móviles.

Qué puedes registrar

Una vez configurado, Insert Affiliate registra automáticamente:

  • Compras con Stripe Checkout (únicas y de suscripción)
  • Compras iniciales de suscripción
  • Renovaciones de suscripción

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, O
    • Crea una cuenta de Stripe nueva
    • 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)

¡Eso es todo! El registro de transacciones web ya está activo.

Implementación: pasar los códigos de afiliado

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

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: insertAffiliate || '',
    insertAffiliateCompanyId: insertAffiliateCompanyId || '',
  },
  // 2. Subscription metadata (persists with subscription)
  subscription_data: {
    metadata: {
      insertAffiliate: insertAffiliate || '',
      insertAffiliateCompanyId: insertAffiliateCompanyId || '',
    },
  },
  // 3. Payment Intent metadata (available on each payment)
  payment_intent_data: {
    metadata: {
      insertAffiliate: insertAffiliate || '',
      insertAffiliateCompanyId: insertAffiliateCompanyId || '',
    },
  },
});

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 obtener los valores necesarios

Debes obtener ambos valores del SDK de Insert Affiliate. Consulta la documentación del SDK de tu plataforma para ver los detalles concretos de implementación.

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

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',
  }),
});

Registrar partidas concretas

Por defecto, Insert Affiliate registra el importe total de la factura. Si tu factura contiene varias partidas pero solo quieres pagar comisión por algunas de ellas, puedes indicar qué ID de precio de Stripe deben generar comisión.

Añade el campo opcional insertAffiliateTrackedPrices a los metadatos de tu subscription_data como una lista de ID de precio de Stripe separados por comas:

subscription_data: {
  metadata: {
    insertAffiliate: insertAffiliate || '',
    insertAffiliateCompanyId: insertAffiliateCompanyId || '',
    insertAffiliateTrackedPrices: 'price_abc123,price_def456', // optional
  },
},

Cómo funciona

  • Solo las partidas que coinciden con los ID de precio indicados cuentan para el cálculo de la comisión
  • Las partidas que no están en la lista se excluyen del importe bruto
  • Si tienes configurada una comisión fija de plataforma (p. ej., los $0.30 de Stripe), se prorratea proporcionalmente entre las partidas registradas y las no registradas, de modo que solo se descuenta la parte correspondiente a las registradas; la comisión fija completa no se carga sobre un importe registrado pequeño

Cuándo usarlo

Es útil cuando una sola factura cubre varios productos o servicios, pero el afiliado solo debe recibir comisión por algunos de ellos, por ejemplo si una partida es una tarifa de alta y otra es una suscripción recurrente.

Si se omite insertAffiliateTrackedPrices, se registra la factura completa como de costumbre.

Probar tu configuración

Nota importante sobre las pruebas

Actualmente, Insert Affiliate solo funciona con una instancia de Stripe Connect en producción. Esto significa que:

  • No puedes usar el modo de prueba de Stripe ni sus números de tarjeta de prueba
  • Debes usar métodos de pago reales para las pruebas
  • Solución recomendada: crea un código promocional en tu Stripe Dashboard para que las transacciones de prueba sean gratuitas o de muy bajo coste (p. ej., $0.01)

Pasos para probar

  1. Activa los Pagos Basados en Web con Stripe en tu configuración
  2. Conecta tu cuenta de Stripe mediante Stripe Connect
  3. (Opcional pero recomendado) Crea un código promocional en tu Stripe Dashboard con un 100% de descuento o por un importe mínimo
  4. Haz una compra real con ambos campos obligatorios (insertAffiliate y insertAffiliateCompanyId) en los metadatos
  5. Aplica tu código promocional si creaste uno
  6. 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 y devuelva valores válidos para ambos campos

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

¿Necesitas ayuda?

Si tienes algún problema durante la configuración, contacta con el soporte y te ayudaremos a configurarlo.