Integración de pasarelas de pago: qué hay que hacer bien
La integración de pagos parece sencilla en un tutorial y es implacable en producción, porque cada caso de fallo implica o bien una clienta que pagó y no recibió nada, o bien una clienta que recibió algo y no pagó.
Esta guía cubre cómo funciona el flujo, la decisión de diseño que evita casi todos los problemas y los casos que conviene probar a propósito antes de lanzar.
Cómo funciona realmente el flujo#
Sea cual sea el proveedor, la forma es la misma: su servidor crea una intención de cobro, la clienta se autentica con el proveedor de pago y el proveedor le comunica el resultado, dos veces y por dos vías distintas.
- Su servidor crea una intención de pago con importe, moneda y una referencia a su pedido.
- La clienta introduce los datos de la tarjeta en un campo o una página alojados, de forma que los datos nunca tocan su servidor.
- Puede requerirse autenticación reforzada, lo que añade un paso que la clienta debe completar.
- El proveedor devuelve a la clienta a su sitio con un resultado.
- Por separado, el proveedor envía un webhook de servidor a servidor con el resultado autoritativo.
- Su sistema actualiza el pedido a partir del webhook, no de la redirección.
- La preparación del envío se dispara solo después de confirmar el pago.
Los pasos 4 y 5 son todo el diseño. La redirección es una pista de lo que pasó; el webhook es el hecho.
Por qué los webhooks deben ser la fuente de verdad#
El navegador de la clienta es un narrador poco fiable. Puede cerrarse durante la redirección, perder la conexión o ser manipulado. Si el estado de su pedido depende de que la clienta vuelva a su página de éxito, tendrá pedidos pagados que nunca se registraron.
- Actualice el estado del pedido solo desde webhooks verificados; trate la redirección puramente como un mensaje para la persona.
- Verifique las firmas de los webhooks. Un endpoint sin autenticar que marca pedidos como pagados es exactamente tan malo como suena.
- Haga idempotente el tratamiento de webhooks: los proveedores reintentan y llegarán duplicados.
- Responda rápido y procese de forma asíncrona; los endpoints lentos se reintentan y acaban desactivándose.
- Registre cada carga útil de webhook. Las disputas de pago se resuelven con registros.
- Gestione eventos fuera de orden, porque pueden llegar así y llegarán.
Los casos de fallo que conviene probar#
Todos estos ocurren en producción. Pruébelos a propósito, con las tarjetas de prueba del proveedor, antes de lanzar.
| Caso | Qué debe ocurrir |
|---|---|
| La clienta cierra la pestaña tras pagar | El webhook completa igualmente el pedido; se envía el correo de confirmación |
| Tarjeta rechazada | Mensaje claro, cesta conservada, otro intento posible |
| Autenticación reforzada fallida | Pedido no confirmado; se le dice a la clienta qué hacer después |
| Webhook duplicado | Pedido actualizado una vez, no dos; sin segundo envío |
| El webhook llega antes que la redirección | La página de éxito refleja el pedido ya completado |
| Devolución parcial | Los totales del pedido y cualquier exportación contable siguen siendo coherentes |
| Stock agotado entre pago y envío | Proceso definido: devolución, pendiente o sustituto |
| Redondeo de moneda | El importe cobrado coincide exactamente con el total mostrado |
Alcance, cumplimiento y dinero#
Unas pocas decisiones determinan cuánta carga regulatoria asume y cuánto de la transacción se queda.
- Nunca almacene números de tarjeta. Use campos o páginas alojados para que los datos de tarjeta no lleguen a su servidor; así el alcance PCI se mantiene mínimo.
- Entienda la estructura de comisiones. Porcentaje más cuota fija, más conversión de divisa, más comisiones por devolución de cargo. El porcentaje anunciado no es el coste.
- Compruebe el calendario de liquidación. Los días hasta el abono afectan a la tesorería más que una pequeña diferencia de tarifa.
- Confirme que la vía de devolución funciona de principio a fin antes de lanzar, incluidas las parciales.
- Soporte los métodos locales que su mercado usa de verdad: la tarjeta no es el estándar en todas partes, y perder el método local dominante cuesta conversiones.
- Tenga un segundo proveedor preparado si los pagos son críticos. Las caídas ocurren y detienen los ingresos por completo.
Preguntas frecuentes
¿Caja alojada o formulario incrustado?
La caja alojada es más simple, mantiene el alcance PCI mínimo y la mantiene el proveedor: para casi todas las tiendas es la opción por defecto correcta. Los campos incrustados mantienen a la clienta en su dominio y dan más control sobre la experiencia, a cambio de más código y más responsabilidad. Ambos mantienen los datos de tarjeta fuera de su servidor, que es la parte que importa.
¿Qué pasa si mi endpoint de webhook se cae?
Los proveedores reintentan con espera creciente, normalmente durante horas o días, así que una caída corta se recupera sola. Una caída larga significa pedidos sin confirmar, así que monitorice el endpoint y avise ante fallos. Además construya un trabajo de conciliación que compare a diario las transacciones del proveedor con sus pedidos: recoge todo lo que se escapó a los reintentos.
¿Debo gestionar la autenticación reforzada de cliente?
Si vende a clientes en regiones que la exigen, sí, y los SDK modernos de los proveedores se encargan de casi todo el flujo. Lo que sí debe gestionar es el resultado: un pedido pendiente de autenticación no está pagado, y tratarlo como pagado significa enviar mercancía que nunca cobró.
¿Cómo pruebo pagos de forma segura?
Todo proveedor tiene un modo de prueba con tarjetas que provocan resultados concretos: rechazo, autenticación requerida, fraude. Recorra la lista completa, incluidos los casos incómodos de la tabla anterior. Después haga una transacción real pequeña en producción antes de lanzar y devuélvala, porque el modo de prueba no ejercita sus claves ni su URL de webhook reales.
integración pasarela de pagopagos ecommercewebhookscumplimiento pcidesarrollo de cajapagos online
