Stripe: Infraestructura de Pagos a Escala

Payment Intents

Los Payment Intents son el núcleo de la API de pagos de Stripe. Un PaymentIntent rastrea el ciclo de vida de un pago desde la creación hasta la completitud. Maneja autenticación (3D Secure), reintentos y flujos de pago multi-paso.

• Ciclo de vida: requires_payment_method -> requires_confirmation -> requires_action (3DS) -> processing -> succeeded/canceled
• Idempotencia: Usa claves de idempotencia en la creación para prevenir cobros duplicados. Crítico para lógica de reintento y redes inestables
• Captura posterior: Crea con capture_method: 'manual' para autorizar sin capturar. Captura dentro de 7 días. Usa para flujos de retención-luego-cobro (reservas, pre-ordenes)
• Metadata: Adjunta hasta 50 pares clave-valor (500 chars por valor). Usa para IDs internos (orderId, userId, bookingId) que vinculan objetos Stripe a tu base de datos
• Métodos de pago: Tarjetas, transferencias bancarias, billeteras (Apple Pay, Google Pay), SEPA, Boleto, OXXO. Cada uno tiene flujos de confirmación y liquidación diferentes

// Create a Payment Intent (server-side)
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const paymentIntent = await stripe.paymentIntents.create({
  amount: 2500,                    // $25.00 in cents
  currency: 'usd',
  customer: customerId,
  payment_method_types: ['card'],
  capture_method: 'automatic',     // or 'manual' for auth-only
  metadata: {
    bookingId: '789',
    userId: '42',
    gymId: 'gym_santiago_01'
  },
  receipt_email: '[email protected]',
  statement_descriptor: 'ACME FITNESS',      // Max 22 chars, shown on card statement
  statement_descriptor_suffix: 'CROSSFIT'    // Max 22 chars, appended
}, {
  idempotencyKey: `booking_789_${Date.now()}`  // Prevent duplicate charges
});

Stripe Checkout

Checkout es una página de pago alojada por Stripe. Maneja toda la UI de pago, autenticación 3D Secure y métodos de pago locales. Menos bugs de integración, mayores tasas de conversión y soporte automático para nuevos métodos de pago.

• Basado en sesiones: Crea una Checkout Session server-side, redirige al cliente a la página de Stripe. Retorno a tus URLs de éxito/cancelación
• Modos: payment (única vez), subscription (recurrente), setup (guardar tarjeta para después). Cada modo tiene configuración de sesión diferente
• Modo embebido: Monta Checkout dentro de tu página como iframe. Misma seguridad que hosted, pero coincide con tu diseño
• Tabla de precios: Display de precios sin código que crea Checkout Sessions automáticamente. Bueno para páginas de precios SaaS simples
• Campos custom: Agrega campos de formulario personalizados (texto, dropdown, numérico) para recolectar información adicional durante el checkout

Stripe Billing gestiona pagos recurrentes con facturación automática, prorrateo, pruebas gratuitas y dunning (recuperación de pagos fallidos). Maneja la complejidad del ciclo de vida de suscripciones que la mayoría de equipos subestiman.

• Productos y Precios: Productos son lo que vendes (ej: "Plan Mensual"). Precios definen cuánto (ej: $29/mes, $290/año). Un producto puede tener múltiples precios para diferentes intervalos y monedas
• Estados de suscripción: active, past_due (pago falló, reintentando), canceled, unpaid, trialing, incomplete (pago inicial pendiente). Maneja cada estado en tu app
• Pruebas gratuitas: Con trial_period_days o timestamp trial_end. Recolecta método de pago al inicio o al final del trial. Usa trial_settings para decidir comportamiento al terminar
• Prorrateo: Crédito/cargo automático al upgradar/downgradar a mitad de ciclo. proration_behavior: 'create_prorations' (default) crea ítems de factura por la diferencia
• Dunning: Smart Retries reintenta pagos fallidos en momentos óptimos automáticamente. Configura calendario de reintentos (hasta 4 reintentos en 3-4 semanas). Envía notificaciones por email a clientes
• Facturación medida: Reporta uso durante el período de facturación. Factura al final del período basado en uso real. Usa para llamadas API, almacenamiento, mensajes, etc.

// Create a subscription with trial
const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: 'price_monthly_29' }],
  trial_period_days: 14,
  payment_settings: {
    payment_method_types: ['card'],
    save_default_payment_method: 'on_subscription'
  },
  metadata: { gymId: 'gym_santiago_01', planType: 'premium' },
  expand: ['latest_invoice.payment_intent']
});

// Upgrade subscription (with proration)
await stripe.subscriptions.update(subscriptionId, {
  items: [{
    id: subscription.items.data[0].id,
    price: 'price_annual_290'
  }],
  proration_behavior: 'create_prorations'
});

Los webhooks son la forma de Stripe de notificar a tu servidor sobre eventos (pago exitoso, suscripción cancelada, disputa creada). Son la fuente de verdad para el estado de pagos—nunca te bases solo en callbacks del lado cliente.

• Verificación de firma: Cada webhook tiene un header Stripe-Signature. Siempre verifica firmas para prevenir eventos falsificados. Usa el body raw del request (no JSON parseado)
• Eventos críticos: payment_intent.succeeded, payment_intent.payment_failed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed, charge.dispute.created
• Idempotencia: Stripe puede enviar el mismo evento múltiples veces. Almacena IDs de eventos procesados y salta duplicados. Tu handler de webhooks debe ser idempotente
• Responde rápido: Retorna 200 dentro de 20 segundos. Haz el procesamiento pesado asíncronamente (encola el evento, procesa en un worker). Stripe reintenta en 4xx/5xx por hasta 3 días
• Orden de eventos: Los eventos pueden llegar fuera de orden. Siempre consulta el estado actual desde la API de Stripe en vez de basarte solo en los datos del evento
• Endpoints de webhook: Crea endpoints separados para diferentes tipos de eventos. Usa el secreto del endpoint de webhook (no tu API key) para verificación de firma

// Express webhook handler with signature verification
import express from 'express';
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

app.post('/webhooks/stripe',
  express.raw({ type: 'application/json' }),  // MUST use raw body
  async (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;

    try {
      event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
    } catch (err) {
      console.error('Webhook signature verification failed:', err.message);
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Check for duplicate processing
    const processed = await redis.get(`stripe:event:${event.id}`);
    if (processed) return res.json({ received: true });

    // Queue for async processing (respond quickly)
    await webhookQueue.add(event.type, {
      eventId: event.id,
      type: event.type,
      data: event.data.object
    });

    // Mark as processed
    await redis.set(`stripe:event:${event.id}`, '1', 'EX', 604800);  // 7 days

    res.json({ received: true });
  }
);

// Worker processes webhook events
const worker = new Worker('stripe-webhooks', async (job) => {
  const { eventId, type, data } = job.data;

  switch (type) {
    case 'payment_intent.succeeded':
      await confirmBooking(data.metadata.bookingId);
      break;
    case 'payment_intent.payment_failed':
      await handleFailedPayment(data.metadata.bookingId, data.last_payment_error);
      break;
    case 'customer.subscription.deleted':
      await deactivateSubscription(data.metadata.gymId, data.customer);
      break;
    case 'charge.dispute.created':
      await handleDispute(data);
      await notifyTeam('dispute', data);
      break;
  }
});

Stripe Connect habilita pagos de marketplace y plataforma donde el dinero fluye entre múltiples partes. Tu plataforma cobra a clientes y distribuye fondos a cuentas conectadas (vendedores, proveedores de servicios, gimnasios).

• Tipos de cuenta: Standard (onboarding hosteado por Stripe, dashboard completo de Stripe), Express (onboarding hosteado, dashboard limitado), Custom (tú construyes todo). Express es recomendado para la mayoría de plataformas
• Tipos de cobro: Cobros directos (cliente paga cuenta conectada directamente), cobros de destino (plataforma cobra, transfiere a conectada), cobros y transferencias separados (más flexible)
• Comisiones de aplicación: Los ingresos de tu plataforma. Configura application_fee_amount en cobros. La comisión se deduce automáticamente y se retiene en tu cuenta de plataforma
• Onboarding: Crea Account Links para que cuentas conectadas completen verificación de identidad. Maneja webhooks account.updated para rastrear estado de verificación
• Requisitos: Las cuentas conectadas deben completar KYC (Know Your Customer). Stripe maneja verificación de ID, verificación de dirección y verificación de cuenta bancaria

// Destination charge: customer pays platform, funds go to connected account
const paymentIntent = await stripe.paymentIntents.create({
  amount: 5000,                         // $50.00
  currency: 'usd',
  customer: customerId,
  payment_method_types: ['card'],
  application_fee_amount: 750,          // Platform keeps $7.50 (15%)
  transfer_data: {
    destination: 'acct_connected_gym_01' // Connected account receives $42.50
  },
  metadata: { bookingId: '789', gymId: 'gym_santiago_01' }
});

// Create connected account (Express)
const account = await stripe.accounts.create({
  type: 'express',
  country: 'CL',                        // Chile
  email: '[email protected]',
  capabilities: {
    card_payments: { requested: true },
    transfers: { requested: true }
  },
  business_type: 'company',
  metadata: { gymId: 'gym_santiago_01' }
});

// Generate onboarding link
const accountLink = await stripe.accountLinks.create({
  account: account.id,
  refresh_url: 'https://app.example.com/connect/retry',
  return_url: 'https://app.example.com/connect/complete',
  type: 'account_onboarding'
});

• Payouts automáticos: Stripe paga automáticamente tu saldo en un calendario (diario, semanal, mensual). Default: 2 días rolling para la mayoría de países. Configurable por cuenta conectada
• Payouts manuales: Deshabilita payouts automáticos y dispara manualmente vía API. Usa cuando necesites controlar exactamente cuándo se les paga a las cuentas conectadas
• Transferencias: Mueve fondos de plataforma a cuentas conectadas. Pueden vincularse a un cobro específico (para reporting preciso) o ser independientes
• Reversiones: Revierte una transferencia desde una cuenta conectada. Usa para reembolsos, disputas o correcciones. Limitado por el saldo disponible de la cuenta conectada
• Velocidad de payout: Estándar (2-7 días hábiles según país), Instantáneo (disponible en US, UK, EU—cargo adicional). Chile: típicamente T+7 para payouts estándar
• Transacciones de balance: Rastrea cada movimiento en tu balance de Stripe. Cobros, reembolsos, comisiones, transferencias, payouts. Usa para conciliación con tu sistema contable

// Manual transfer to connected account
const transfer = await stripe.transfers.create({
  amount: 4250,                          // $42.50
  currency: 'usd',
  destination: 'acct_connected_gym_01',
  source_transaction: chargeId,          // Link to original charge
  metadata: { bookingId: '789', period: '2026-03' }
});

// Trigger manual payout for connected account
const payout = await stripe.payouts.create({
  amount: 100000,                        // $1000.00
  currency: 'usd'
}, {
  stripeAccount: 'acct_connected_gym_01'
});

Operar en múltiples países requiere manejar diferentes monedas, regulaciones fiscales y métodos de pago. Stripe provee herramientas para soporte multi-moneda, pero la capa de aplicación debe diseñarse cuidadosamente.

• Moneda de presentación: Cobra a clientes en su moneda local. Clientes chilenos pagan en CLP, mexicanos en MXN. Reduce abandono de carrito y elimina comisiones por transacción extranjera para clientes
• Moneda de liquidación: Stripe convierte y te paga en la moneda de liquidación de tu plataforma. Tipo de cambio aplica al momento del cobro. Rastrea con balance_transaction.exchange_rate
• Monedas sin decimales: JPY, KRW, CLP usan montos enteros directamente (sin centavos). $10,000 CLP = amount: 10000. Otras monedas usan la unidad más pequeña (USD $25.00 = amount: 2500)
• Stripe Tax: Cálculo automático de impuestos para 40+ países. Maneja IVA, GST, sales tax. Registra tax IDs por país. Crea facturas fiscales apropiadas
• Métodos de pago locales: Habilita Boleto (Brasil), OXXO (México), transferencias bancarias, etc. vía PaymentIntent o Checkout. Aumenta conversión en Latinoamérica significativamente
• Facturación: Facturas multi-idioma con formato de moneda correcto. Stripe genera facturas PDF con ítems fiscales correctos. Configurable por locale del cliente
• Cumplimiento Chile SII: El Servicio de Impuestos Internos de Chile requiere facturación electrónica (DTE). Stripe Tax calcula IVA (19%), pero necesitas un proveedor certificado de DTE (ej: Bsale, Nubox) para emitir boletas y facturas electrónicas que cumplan con regulaciones SII. Mapea facturas de Stripe a documentos DTE
• Cumplimiento México SAT: El SAT de México requiere CFDI (Comprobante Fiscal Digital por Internet) para cada transacción. Usa un PAC (Proveedor Autorizado de Certificación) para timbrar facturas. Stripe Tax maneja IVA (16%), pero la generación de CFDI debe hacerse por separado. Incluye RFC (ID fiscal) en todas las facturas

// Multi-currency charge with tax
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  customer: customerId,
  line_items: [{
    price_data: {
      currency: 'clp',                    // Chilean Peso (zero-decimal)
      product_data: { name: 'CrossFit Class Pack - 10 sessions' },
      unit_amount: 45000                   // CLP $45,000
    },
    quantity: 1
  }],
  automatic_tax: { enabled: true },        // Stripe Tax handles IVA (19% in Chile)
  payment_method_types: ['card'],
  success_url: 'https://app.example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://app.example.com/cancel',
  metadata: { country: 'CL', gymId: 'gym_santiago_01' }
});

PCI DSS (Payment Card Industry Data Security Standard) es obligatorio para cualquier negocio que maneje pagos con tarjeta. Stripe minimiza tu carga de cumplimiento manejando datos de tarjeta en sus servidores.

• SAQ A: Nivel de cumplimiento PCI más simple. Se logra usando Stripe Checkout, Stripe Elements o Payment Links. Los datos de tarjeta nunca tocan tus servidores. La mayoría de integraciones Stripe califican
• Stripe Elements: Componentes UI pre-construidos (input de tarjeta, IBAN, etc.) que recolectan datos sensibles directamente a Stripe. Tu servidor recibe un token PaymentMethod, nunca el número de tarjeta
• Nunca registres datos de tarjeta: No registres números de tarjeta completos, CVV o fechas de expiración. Stripe provee last4, brand y exp_month/exp_year para fines de visualización
• HTTPS en todas partes: Todas las páginas que incluyan Stripe.js deben servirse sobre HTTPS. Usa headers HSTS. Sin contenido mixto
• Tokenización: Los datos de tarjeta se reemplazan con un token (PaymentMethod o SetupIntent) que solo puede usarse con tu cuenta Stripe. Los tokens son inútiles si son interceptados
• Seguridad de API keys: Nunca expones tu clave secreta (sk_*) del lado cliente. Solo la clave publicable (pk_*) va en el navegador. Rota claves periódicamente. Usa claves restringidas para permisos específicos

Stripe provee un modo de prueba completo con números de tarjeta de prueba, test clocks para flujos basados en tiempo y testing de webhooks. Cada funcionalidad funciona en modo prueba sin dinero real.

• Tarjetas de prueba: 4242 4242 4242 4242 (exitosa), 4000 0000 0000 0002 (rechazada), 4000 0025 0000 3155 (requiere 3DS). Lista completa en docs de Stripe
• Test clocks: Simula el paso del tiempo para testing de suscripciones. Crea un test clock, adjunta clientes, avanza el tiempo para disparar ciclos de facturación, fin de trials, flujos de dunning
• Testing de webhooks: Usa Stripe CLI (stripe listen --forward-to localhost:3000/webhooks/stripe) para reenviar eventos de prueba localmente. O dispara eventos específicos con stripe trigger payment_intent.succeeded
• Claves de modo prueba: Todos los recursos de modo prueba son separados de los live. Los cobros en modo prueba nunca procesan pagos reales. Cambia entre modos usando pk_test_*/sk_test_* vs pk_live_*/sk_live_*
• Tests de integración: Golpea la API de prueba de Stripe en tu pipeline CI/CD. Testea el flujo completo: crear cliente, agregar método de pago, crear cobro, verificar webhook, verificar estado de base de datos
• Simulación de errores: Dispara códigos de error específicos con valores de token especiales. Proba cómo tu app maneja rechazos, errores de red, rate limits y fallos de autenticación

// Test clock for subscription lifecycle testing
const testClock = await stripe.testHelpers.testClocks.create({
  frozen_time: Math.floor(Date.now() / 1000),
  name: 'Subscription lifecycle test'
});

// Create customer attached to test clock
const customer = await stripe.customers.create({
  email: '[email protected]',
  test_clock: testClock.id
});

// Create subscription with 14-day trial
const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_monthly_29' }],
  trial_period_days: 14
});

// Advance time to end of trial (triggers first payment)
await stripe.testHelpers.testClocks.advance(testClock.id, {
  frozen_time: Math.floor(Date.now() / 1000) + (14 * 86400)
});

// Advance another month (triggers renewal)
await stripe.testHelpers.testClocks.advance(testClock.id, {
  frozen_time: Math.floor(Date.now() / 1000) + (44 * 86400)
});

Stripe Radar usa machine learning entrenado con datos de millones de negocios a nivel mundial para detectar y bloquear pagos fraudulentos. Evalúa cada transacción con un nivel de riesgo y aplica reglas configurables.

• Puntuación de riesgo: Cada pago recibe un puntaje de riesgo (0–99) y un nivel (normal, elevated, highest). Radar bloquea pagos con riesgo máximo por defecto. Puedes personalizar umbrales según tu negocio
• Reglas de Radar: Crea reglas personalizadas usando el lenguaje de reglas de Stripe. Bloquea o revisa pagos basados en metadata, monto, país, tipo de tarjeta, velocidad y más. Ejemplo: :risk_score: > 65 AND :amount_in_usd: > 500
• 3D Secure dinámico: Radar puede solicitar autenticación 3DS solo cuando el riesgo es elevado, reduciendo fricción para pagos de bajo riesgo. Usa request_three_d_secure: 'automatic'
• Listas de permitidos y bloqueados: Mantén listas de emails, huellas de tarjeta, direcciones IP y países confiables o bloqueados. Sobreescribe decisiones del ML para clientes conocidos o actores maliciosos conocidos
• Radar para equipos de fraude: Tier premium con colas de revisión manual, reglas custom con regex y analítica avanzada. Agrega revisión humana para casos límite que la automatización no puede resolver con confianza
• Alerta temprana de fraude: Recibe webhooks radar.early_fraud_warning.created cuando las redes de tarjetas reportan actividad sospechosa. Reembolsa proactivamente antes de que se presente una disputa formal para evitar cargos por contracargo

// PaymentIntent with Radar risk evaluation
const paymentIntent = await stripe.paymentIntents.create({
  amount: 15000,
  currency: 'usd',
  customer: customerId,
  payment_method_types: ['card'],
  payment_method_options: {
    card: {
      request_three_d_secure: 'automatic'  // Radar decides when to trigger 3DS
    }
  },
  metadata: { orderId: '456', riskContext: 'new_customer' }
});

// After charge, inspect Radar outcome
const charge = await stripe.charges.retrieve(chargeId);
console.log(charge.outcome.risk_level);   // 'normal', 'elevated', 'highest'
console.log(charge.outcome.risk_score);   // 0-99
console.log(charge.outcome.type);         // 'authorized', 'blocked', 'manual_review'

El Portal de Cliente de Stripe es una página hosteada por Stripe donde los clientes pueden gestionar sus suscripciones, métodos de pago y datos de facturación sin que tú construyas ninguna UI. Reduce tickets de soporte y tiempo de desarrollo significativamente.

• Autoservicio: Los clientes pueden actualizar métodos de pago, ver historial de facturas, descargar facturas PDF y gestionar suscripciones (upgrade, downgrade, cancelar) desde una sola página
• Configuración: Controla qué pueden hacer los clientes vía la configuración del Portal en tu Dashboard de Stripe. Permiti o restringi cancelación, cambio de plan, actualización de método de pago. Configura políticas de cancelación (inmediata vs fin de período)
• Acceso basado en sesión: Crea una sesión de portal server-side con el ID del cliente. Redirige al cliente a la URL de la sesión. Las sesiones expiran después de uso, garantizando seguridad
• Branding: Personaliza colores, logo e info del negocio en la configuración del portal. El portal coincide con tu marca siendo completamente hosteado por Stripe
• Webhooks: Las acciones del portal disparan webhooks estándar (customer.subscription.updated, payment_method.attached). Tus handlers de webhook existentes procesan cambios del portal automáticamente

// Create a Customer Portal session
const portalSession = await stripe.billingPortal.sessions.create({
  customer: customerId,
  return_url: 'https://app.example.com/account',
});

// Redirect customer to: portalSession.url

// Configure portal (done once, or via Dashboard)
const config = await stripe.billingPortal.configurations.create({
  business_profile: {
    headline: 'Manage your subscription'
  },
  features: {
    subscription_cancel: { enabled: true, mode: 'at_period_end' },
    subscription_update: {
      enabled: true,
      default_allowed_updates: ['price', 'quantity'],
      proration_behavior: 'create_prorations',
      products: [{ product: 'prod_gym_membership', prices: ['price_monthly', 'price_annual'] }]
    },
    payment_method_update: { enabled: true },
    invoice_history: { enabled: true }
  }
});

Stripe soporta docenas de métodos de pago globalmente. Cada uno tiene flujos de autorización, tiempos de liquidación y disponibilidad geográfica diferentes. Ofrecer los métodos correctos por región mejora dramáticamente las tasas de conversión.

// PaymentIntent with multiple payment methods
const paymentIntent = await stripe.paymentIntents.create({
  amount: 3000,
  currency: 'eur',
  customer: customerId,
  payment_method_types: ['card', 'sepa_debit', 'ideal'],
  metadata: { orderId: '123' }
});

// SEPA mandate for recurring payments
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2900,
  currency: 'eur',
  customer: customerId,
  payment_method_types: ['sepa_debit'],
  payment_method_options: {
    sepa_debit: { mandate_options: { } }
  },
  mandate_data: {
    customer_acceptance: {
      type: 'online',
      online: {
        ip_address: req.ip,
        user_agent: req.headers['user-agent']
      }
    }
  }
});

Las disputas (contracargos) ocurren cuando un tarjetahabiente impugna un cobro ante su banco. Cada disputa cuesta una comisión no reembolsable ($15 USD) sin importar el resultado. La prevención es mucho más barata que pelear disputas.

• Ciclo de vida de disputa: charge.dispute.created (fondos retirados) → tú presentas evidencia → el banco revisa (60–90 días) → charge.dispute.closed (ganada o perdida). Responde dentro del plazo de evidencia o la disputa se pierde automáticamente
• Presentación de evidencia: Provee evidencia convincente vía API o Dashboard: confirmación de entrega, contratos firmados, logs de comunicación con el cliente, logs de IP, datos de uso. Adapta la evidencia al código de razón de disputa (fraudulenta, producto no recibido, duplicado, etc.)
• Prevención con Radar: Bloquea pagos de alto riesgo antes de que se conviertan en disputas. Habilita 3DS para riesgo elevado para transferir la responsabilidad al emisor de la tarjeta. Usa alertas tempranas de fraude de Radar para reembolsar proactivamente cobros sospechosos
• Descriptores claros: Configura valores reconocibles de statement_descriptor. Cobros no reconocidos son la causa principal de disputas por "fraude amistoso". Incluye nombre del negocio y tipo de servicio
• Políticas de reembolso: Haz que las políticas de cancelación y reembolso sean claramente visibles. Reembolsos proactivos antes de disputas ahorran los $15 de comisión y protegen tu tasa de disputas. Mantén tu tasa de disputas por debajo del 0.75% para evitar programas de monitoreo
• Monitoreo de tasa de disputas: Las redes de tarjetas (Visa, Mastercard) colocan negocios en programas de monitoreo si las tasas de disputa superan umbrales. Visa consolidó VDMP y VFMP en VAMP (Visa Acquirer Monitoring Program), un único ratio combinado de fraude más disputas cuyo umbral excesivo para comercios se endureció a 1.5% el 1 de abril de 2026. Mastercard: 1.0% activa ECP. Disputas excesivas pueden llevar a terminación de cuenta

// Submit dispute evidence via API
await stripe.disputes.update(disputeId, {
  evidence: {
    customer_name: 'Maria Garcia',
    customer_email_address: '[email protected]',
    product_description: 'CrossFit monthly membership - January 2026',
    service_date: '2026-01-01',
    access_activity_log: 'Customer checked in 12 times in January 2026: Jan 3, 5, 7, 10...',
    customer_signature: 'file_upload_id_contract',       // Upload via File API
    receipt: 'file_upload_id_receipt',
    uncategorized_text: 'Customer signed 12-month contract on 2025-12-15. ' +
      'Cancellation policy requires 30-day notice. No cancellation was requested.'
  },
  submit: true  // Submit immediately (cannot be modified after)
});

// Handle dispute webhook
case 'charge.dispute.created':
  const dispute = data;
  await notifyTeam('dispute_alert', {
    amount: dispute.amount,
    reason: dispute.reason,        // 'fraudulent', 'product_not_received', etc.
    chargeId: dispute.charge,
    deadline: dispute.evidence_details.due_by
  });
  // Auto-gather evidence from your database
  await prepareDisputeEvidence(dispute);
  break;

En producción, diseñé e implementé la infraestructura completa de pagos usando Stripe, soportando gimnasios en Chile y México con facturación multi-moneda, suscripciones y pagos estilo marketplace.

• Stripe + MercadoPago: Arquitectura de proveedor de pagos dual. Stripe para pagos con tarjeta y suscripciones, MercadoPago para métodos de pago locales en Latinoamérica (transferencias bancarias, pagos en efectivo en OXXO/Servipag). API interna unificada que abstrae el proveedor
• Impuestos multi-país: Manejé cálculo de IVA para Chile (19%) y México (16%). Usé Stripe Tax para cálculo automático en pagos Stripe y lógica fiscal custom para MercadoPago. Integré con Chile SII para DTE (boletas/facturas electrónicas) y México SAT para timbrado CFDI vía PAC. Facturación fiscalmente conforme en ambos países
• Gestión de suscripciones: Suscripciones de membresía de gimnasio con facturación mensual y anual. Manejo de upgrades/downgrades con prorrateo, períodos de prueba para nuevos miembros y dunning automatizado para pagos fallidos
• Confiabilidad de webhooks: Todos los webhooks de Stripe encolados a través de BullMQ para procesamiento confiable. Claves de idempotencia almacenadas en Redis para prevenir procesamiento duplicado. Endpoints de webhook separados para pagos, suscripciones y disputas
• Conciliación: Conciliación diaria automatizada entre transacciones de balance de Stripe, movimientos de MercadoPago y registros internos de base de datos. Detección y resolución automática de discrepancias con alertas Slack para casos que requieren revisión manual

Stripe Agent Toolkit

SDKs oficiales de Python y TypeScript que permiten a agentes AI interactuar con Stripe mediante lenguaje natural. Se integra con OpenAI, LangChain, CrewAI y Vercel AI SDK. Los agentes pueden crear productos, establecer precios, generar enlaces de pago y gestionar suscripciones con instrucciones en español o inglés. Ideal para construir flujos de comercio impulsados por AI donde el agente maneja toda la configuración de pagos.

Cuentas Financieras con Stablecoins

Stripe ahora soporta mantener saldos en stablecoins en cuentas financieras. Los negocios pueden recibir fondos vía rieles cripto y fiat, con conversión automática entre stablecoins y monedas tradicionales. Disponible en 100+ países. Habilita nuevos casos de uso para pagos transfronterizos y gestión de tesorería con volatilidad FX reducida.

Precios Adaptativos

Localiza precios automáticamente en 150+ mercados basado en paridad de poder adquisitivo, condiciones del mercado local y moneda. Funciona con Stripe Elements, Checkout y Hosted Invoice Page. Sin comisiones adicionales más allá del pricing estándar de Stripe. Reemplaza el trabajo manual de mantener tablas de precios multi-moneda por región.

Stripe Orchestration

Gestiona múltiples procesadores de pago desde el dashboard y API de Stripe. Enruta transacciones a diferentes procesadores basado en reglas (geografía, monto, tipo de tarjeta) manteniendo un solo punto de integración. Útil para empresas que necesitan redundancia de procesadores o tienen contratos legacy con procesadores junto a Stripe.

API de Entitlements

Define y controla el acceso a funcionalidades basado en los planes de precios del cliente. Mapea features del producto a tiers de suscripción y consulta entitlements en runtime para controlar acceso. Reemplaza lógica custom de feature-flags vinculada al estado de suscripción. La API retorna qué features tiene acceso un cliente basado en sus suscripciones activas y compras únicas.

API V2 y Meter Events

La API V2 introduce meter events de alto throughput soportando hasta 10,000 eventos por segundo para facturación basada en uso. Reporta datos granulares de uso (llamadas API, minutos de cómputo, bytes de almacenamiento) en tiempo real. Los eventos se agregan en períodos de facturación automáticamente. Diseñado para plataformas SaaS con modelos de pricing medido de alto volumen.

Agentic Commerce Suite y MCP

Stripe lanzó el Agentic Commerce Suite, una solución completa para vender a través de agentes AI. Hace que los productos sean descubribles para agentes, simplifica el checkout y acepta pagos agénticos mediante una sola integración. El Stripe Agent Toolkit (v0.9.0) ahora incluye un servidor MCP (Model Context Protocol), habilitando a agentes AI para interactuar con la API de Stripe y buscar en su base de conocimiento. El toolkit soporta OpenAI Agents SDK, Vercel AI SDK, LangChain y CrewAI en Python y TypeScript.

Shared Payment Tokens y x402

En marzo de 2026, Stripe expandió los Shared Payment Tokens (SPTs) para soportar Mastercard Agent Pay y Visa Intelligent Commerce para pagos agénticos liderados por la red, además de opciones compra-ahora-paga-después (Affirm y Klarna). Por separado, Stripe lanzó pagos x402 en Base, habilitando a agentes AI para hacer micropagos instantáneos en USDC para APIs, datos y servicios digitales. En Stripe Sessions 2026 (29 de abril), Stripe anunció la Agentic Commerce Suite, y a junio de 2026 los comercios pueden aceptar pagos iniciados por agentes tanto en fiat (tarjetas, Klarna, Affirm) como en stablecoins a través de SPTs. Esto abre la puerta para que desarrolladores cobren a agentes por servicios usando pagos máquina-a-máquina basados en stablecoins.

Tarjeta Machine Payments Protocol (MPP)

Stripe y Tempo lanzaron la tarjeta Machine Payments Protocol (MPP), un estándar abierto para pagos agente-a-servicio. La tarjeta MPP da a los agentes AI una identidad de pago dedicada -- los agentes pueden comprar autónomamente APIs, recursos de cómputo y servicios digitales usando la API estándar de PaymentIntents. A diferencia de x402 (basado en stablecoins), MPP opera en redes de tarjetas existentes, haciéndolo compatible con cualquier comercio integrado con Stripe. Las organizaciones configuran límites de gasto, reglas de aprobación y pistas de auditoría por agente, manteniendo supervisión humana sobre el gasto autónomo. La versión actual de la API es 2026-06-24.dahlia, que agrega configuración del anchor de ciclo de facturación para Checkout Sessions en modo suscripción, disputas de cumplimiento de Mastercard, pagos recurrentes con Satispay y soporte cripto para la red Sui; la versión previa 2026-05-27.dahlia agregó prebilling en suscripciones, timing de payouts configurable para Connect y nuevos métodos de pago (Scalapay, Bizum, Twint recurrente). Stripe es ahora el primer y único proveedor que soporta tanto tokens de red agénticos como tokens compra-ahora-paga-después en comercio agéntico a través de un solo primitivo. La API Accounts v2 es GA para nuevos usuarios de Connect, mejorando la conversión de onboarding al compartir KYC entre identidades de cliente y cuenta conectada. En Stripe Sessions 2026 (29-30 de abril, San Francisco), Stripe anunció la expansión del Agentic Commerce Suite, incluyendo la billetera Link para agentes y micropagos con Tempo, con retailers como Coach, Revolve y URBN y plataformas como Squarespace, Wix y Etsy adoptándolo.