Stripe

Stripe es el procesador de pagos; AppBO es donde viven la relación con el cliente y la automatización. Del lado de Stripe están los clientes, los métodos de pago, las intenciones de pago, las suscripciones, las facturas, los reembolsos y las disputas, más toda la maquinaria de riesgo y cumplimiento que implica guardar datos de tarjetas. Del lado de AppBO están el contacto, el pedido u oportunidad, el pipeline y los flujos de trabajo que necesitan saber si el dinero de verdad llegó.

Los conectas para que un pago sea un evento en la historia del cliente y no un número en un panel aparte. Con la conexión, un cobro exitoso puede mover la oportunidad, dar acceso, arrancar la secuencia de entrega y detener los recordatorios de cobro. Una renovación fallida puede disparar una secuencia de cobranza que usa las mismas plantillas de email y SMS que todo lo demás. Un reembolso puede ponerle una etiqueta al contacto y sacarlo de la campaña de venta adicional (upsell). Sin la conexión, alguien revisa dos sistemas y concilia a mano.

Stripe suele ser la opción por defecto para pagos con tarjeta en AppBO porque la conexión cubre la superficie más amplia: pagos únicos, suscripciones, facturas y la experiencia de checkout en las páginas de funnel y de pedido, y porque su catálogo de webhooks es lo bastante detallado para dirigir la automatización con precisión. El trabajo de integrarlo bien tiene menos que ver con conectarlo, que es rápido, y más con decidir qué eventos de Stripe son la verdad y asegurarse de que los registros de la plataforma los sigan en lugar de desviarse.

1. Primero ten lista la cuenta de Stripe: datos del negocio verificados, una cuenta bancaria para los pagos asociada y el descriptor del estado de cuenta configurado con algo que los clientes reconozcan en el resumen de su tarjeta. Una cuenta sin verificar acepta pagos y retiene los depósitos.
2. Decide qué sistema es dueño del catálogo de productos. Los productos y precios definidos en Stripe y los productos definidos en la configuración de pagos de la propia plataforma pueden funcionar, pero tienes que elegir uno como fuente de verdad o tus reportes nunca van a cuadrar.
3. En la subcuenta de AppBO que corresponda, abre la configuración de pagos e inicia la conexión con Stripe. Completa el flujo de autorización de Stripe iniciando sesión en la cuenta de Stripe que debe recibir los fondos.
4. Revisa qué cuenta de Stripe conectaste. Si administras varias, confirma que el identificador de cuenta que aparece después de la conexión sea el correcto antes de aceptar un solo pago real.
5. Define el modo de la conexión a propósito. Conecta primero en modo de prueba y déjala ahí hasta que todo el flujo esté comprobado; pasar a modo real es un paso consciente, no algo que se hace de pasada.
6. Configura la experiencia de pago: qué monedas, si se pide la dirección de facturación, si se guardan los métodos de pago para usos futuros y qué billeteras o métodos alternativos activar. Activa solo lo que puedas sostener en la operación.
7. Crea los registros de productos o precios en el sistema que elegiste como dueño del catálogo y asócialos al paso del funnel, formulario de pedido o plantilla de factura que los va a vender.
8. Confirma el camino de los webhooks desde Stripe. La plataforma registra lo que necesita durante la conexión; si también necesitas eventos en tu propio sistema, registra un endpoint separado en Stripe en lugar de interceptar el de la plataforma, y verifica su firma con el secreto de firma que Stripe emite para ese endpoint.
9. Arma la automatización sobre eventos de pago y no sobre el comportamiento de la página. Dispara el flujo de trabajo de entrega con la señal de pago exitoso, no cuando el visitante llega a una página de agradecimiento. Un visitante puede llegar a esa página sin pagar, y un pago puede salir bien sin que llegue a ella.
10. Arma también los caminos de falla: un flujo de pago fallido, un flujo de suscripción con pago vencido y un flujo de reembolso que revierta el acceso que haya dado el camino de éxito.
11. Decide cómo se relacionan el contacto y el cliente de Stripe, normalmente por email, y guarda el identificador de cliente de Stripe en un campo personalizado de AppBO para que las búsquedas posteriores sean exactas y no aproximadas.
12. Haz una transacción completa en modo de prueba con las tarjetas de prueba de Stripe: una tarjeta exitosa, una rechazada y una que requiere autenticación adicional. Confirma que cada una produzca el registro y el flujo que esperabas.
13. Prueba el ciclo de vida de la suscripción en modo de prueba avanzando una suscripción por una renovación y una falla, y confirma que se dispare el flujo de cobranza y que ocurra el cambio de acceso.
14. Pasa a modo real y haz un pago real pequeño con una tarjeta real, de punta a punta. Confirma que el cobro aparezca en Stripe, que el registro aparezca en la plataforma, que el flujo haya corrido y que los fondos figuren como depósito pendiente. Después reembólsalo y confirma el camino de reversión.
15. Configura monitoreo para lo que falla sin avisar: fallas de entrega de webhooks en el panel de Stripe, pagos registrados en Stripe sin un registro correspondiente en la plataforma y suscripciones con pago vencido sin una cobranza activa.

De la plataforma a Stripe

• Intenciones de pago creadas cuando un cliente envía un formulario de pedido, un paso de checkout del funnel o el pago de una factura.
• Registros de clientes, normalmente identificados por email, con el nombre y los datos de facturación que se hayan recolectado.
• Creación y cambios de suscripciones cuando los inicia la plataforma, con referencia a un precio.
• Detalles de la factura y del monto de un pago solicitado, más metadatos que identifican al contacto y la página de origen.
• Solicitudes de reembolso iniciadas desde la plataforma, cuando esa acción está disponible.

De Stripe a la plataforma

• Eventos de resultado del pago: exitoso, fallido, requiere acción, cancelado.
• Eventos del ciclo de vida de la suscripción: creada, renovada, pago fallido, pago vencido, cancelada.
• Eventos de facturas: creada, pagada, pago fallido, anulada.
• Avisos de reembolsos y disputas.
• El registro de la transacción que llena las vistas de pagos y pedidos de la plataforma, y los valores según los cuales se ramifican los flujos.

Lo que no se mueve

• Los números de tarjeta. Los datos de la tarjeta los capturan los propios elementos de Stripe y nunca llegan a la plataforma, que es justamente lo que deja la carga de cumplimiento en Stripe.
• Las herramientas de riesgo, Radar y evidencia de disputas de Stripe. Las decisiones sobre fraude se quedan en Stripe.
• El detalle de depósitos y saldos. Conciliar lo que llegó al banco es una tarea de Stripe y de contabilidad, no de la plataforma.
• Las transacciones históricas de antes de la conexión. Nada se completa hacia atrás de forma automática.
• La determinación y la declaración de impuestos, más allá de la configuración fiscal que tenga cada lado.

Escenario: un cliente compra una membresía mensual en un paso de checkout de un funnel y la primera renovación falla.

1. El cliente completa el paso de checkout. La plataforma crea en Stripe una intención de pago por el precio de la membresía y el elemento de pago de Stripe recolecta la tarjeta en el navegador.
2. La tarjeta requiere autenticación adicional. Stripe presenta la verificación en la misma página, el cliente la completa y la intención de pago sale exitosa.
3. Stripe crea el cliente y la suscripción, y emite eventos de pago y de suscripción.
4. La plataforma registra la transacción en el contacto y escribe el identificador de cliente de Stripe en el campo personalizado reservado para eso.
5. Se dispara un flujo de trabajo de AppBO activado por el pago exitoso: le pone al contacto la etiqueta miembro-activo, mueve la oportunidad a Ganada, envía el recibo y el email de bienvenida, y da acceso al área de miembros.
6. Un mes después, Stripe intenta la renovación. La tarjeta venció y el cobro falla. Stripe emite un evento de pago de factura fallido y marca la suscripción con pago vencido.
7. Un flujo disparado por esa falla quita la etiqueta miembro-activo, aplica miembro-pago-vencido y arranca una secuencia de cobranza de tres pasos: un email de inmediato, un SMS a los dos días y una tarea de llamada para el ejecutivo de cuenta a los cinco. Cada uno lleva un enlace a la página para actualizar el método de pago.
8. Mientras tanto, el propio calendario de reintentos de Stripe vuelve a intentar el cobro, de forma independiente de los mensajes de cobranza.
9. El tercer día, el cliente actualiza su tarjeta. Stripe reintenta, el cobro sale bien y se emite un evento de pago exitoso.
10. Un flujo con ese evento quita miembro-pago-vencido, vuelve a poner miembro-activo, cancela los pasos de cobranza que quedaban y la tarea de llamada, y restablece el acceso al área de miembros.
11. Un mes después, el cliente disputa un cobro. Stripe emite un evento de disputa; un flujo le pone una etiqueta al contacto, lo saca de la campaña de venta adicional y crea una tarea para que finanzas presente la evidencia en Stripe, que es donde de verdad se maneja la disputa.

Límites de uso

Stripe aplica límites de uso a su API, y los modos real y de prueba tienen presupuestos separados. Una operación masiva (migrar suscripciones, completar clientes hacia atrás) necesita ritmo y esperas entre reintentos; consulta los límites que Stripe publica actualmente en lugar de suponerlos. Del lado de la plataforma, cada evento de pago que dispara un flujo de trabajo consume presupuesto de ejecución, así que una tienda con mucho volumen debe mantener ligeros sus flujos de pago.

Reintentos e idempotencia

Stripe admite claves de idempotencia en las solicitudes, y sus webhooks se entregan al menos una vez con reintentos automáticos durante un período largo. Los dos hechos importan. Cualquier manejador que escribas tiene que eliminar duplicados por el identificador del evento de Stripe, porque el mismo evento va a llegar más de una vez. Los flujos disparados por eventos de pago necesitan la misma disciplina: un flujo de entrega que puede correr dos veces va a despachar dos veces. El calendario inteligente de reintentos de Stripe para los cobros de suscripciones fallidos corre de forma independiente de tus mensajes de cobranza, así que coordina los dos o a los clientes les van a pedir que paguen cuando ya pagaron.

Trampas del mapeo de campos

En Stripe, los montos están en la unidad más pequeña de la moneda. Un desajuste aquí es el error de mapeo más caro en pagos, así que verifícalo con una transacción real en lugar de razonarlo. La relación entre contacto y cliente normalmente es por email, y se rompe cuando el cliente paga con una dirección distinta a la de su registro de contacto; guarda el identificador de cliente de Stripe para que las búsquedas posteriores sean exactas. Los metadatos son la forma de llevar tus propios identificadores a través de Stripe, y vale la pena llenarlos desde el principio porque no puedes agregarlos después a cobros pasados.

Creación de duplicados

Aparecen clientes duplicados en Stripe cuando la misma persona paga dos veces con el email escrito con otras mayúsculas o con otra dirección, y aparecen contactos duplicados cuando llega un pago para un email que ya existe escrito de otra forma. Normaliza el email antes de relacionar registros y concilia por el identificador de cliente guardado.

Prueba frente a producción

Los dos modos de Stripe tienen claves separadas, datos separados y endpoints de webhook separados, y aquí es donde más a menudo se rompen las integraciones el día del lanzamiento. Una conexión que se queda en modo de prueba no cobra dinero real y parece funcionar perfecto; una conexión real probada con una tarjeta real cobra dinero real. Confirma el modo de forma explícita antes y después de salir en vivo, y conserva el flujo en modo de prueba disponible para pruebas de regresión.

Vencimiento de la autenticación y de la conexión

La conexión entre la plataforma y Stripe se puede romper porque alguien desconecta la app en cualquiera de los dos sistemas, porque se restringe una cuenta de Stripe o por la rotación de una API key. El síntoma es que los pagos fallan en el checkout o que los eventos dejan de llegar, así que configura alertas para las dos cosas. Vigila también las diferencias de versión de la API de Stripe: los datos de un webhook se generan en una versión, y un manejador escrito para una estructura más vieja puede interpretar mal una más nueva.

Lo que suele romperse

• La entrega depende de la página de agradecimiento y no del evento de pago, así que visitantes que no pagaron obtienen acceso y clientes que pagaron y cerraron la pestaña no.
• Una conexión que se queda en modo de prueba después del lanzamiento.
• Eventos de webhook que fallan sin avisar y que solo se ven en el registro de entregas de Stripe.
• Errores con la unidad más pequeña de la moneda que producen cobros desfasados por un factor de cien.
• Sin camino para reembolsos ni disputas, así que el acceso dado con el pago nunca se revoca.
• Secuencias de cobranza que corren en paralelo con los reintentos propios de Stripe y se contradicen.
• Cambios de suscripción hechos directamente en Stripe sin que la plataforma se entere, lo que deja etiquetas y accesos desactualizados.