Diagrama de integración de una pasarela de pago: autorización, 3-D Secure, captura y webhooks

En la mayoría de los diagramas de arquitectura, un pago es una flecha de la tienda a "Stripe" o "Adyen". En producción es una cadena de participantes y dos líneas de tiempo: lo que pasa mientras el cliente espera en la página de pago y lo que llega minutos o días después por webhook. La mayoría de los bugs de pagos viven en el hueco entre las dos.

Esta guía dibuja un pago con tarjeta desde el punto de vista del equipo de ingeniería del comercio: los participantes, el camino feliz, por qué el resultado del navegador no es la fuente de verdad, qué pasa después de la autorización y un diagrama que muestra dónde cambian el dinero y el estado del pedido. Es neutral respecto al proveedor; Stripe y Adyen aparecen solo como ejemplos de cómo documentan los detalles los proveedores de servicios de pago.

Los participantes

El camino feliz

1. El cliente selecciona Pagar. El frontend pide a tu backend que inicie el pago de un pedido.
2. El backend crea un pago en el PSP con el importe, la moneda, el ID del pedido y una clave de idempotencia, y pasa al frontend el token de cliente del PSP.
3. El frontend recoge los datos de la tarjeta en los campos del PSP, normalmente iframes o un SDK, así que el número de tarjeta va del navegador directo al PSP y nunca toca tus servidores.
4. El emisor decide sobre 3-D Secure. EMVCo describe dos flujos: en el flujo sin fricción, el emisor aprueba según una evaluación de riesgo sin preguntar nada al cliente; en el flujo con desafío, el cliente confirma, por ejemplo con un código de un solo uso o con la app de su banco. En algunas regiones es así como se cumple la autenticación reforzada de clientes.
5. El PSP envía la autorización al emisor a través del adquirente y la red de tarjetas; el emisor aprueba y retiene los fondos.
6. El frontend muestra el resultado. Mostrar "Gracias" está bien, pero no es el momento de enviar el pedido.
7. El PSP envía un webhook que dice que el pago se autorizó. Tu backend lo verifica y actualiza el pedido.
8. El backend captura el pago cuando se envía el pedido, o de inmediato en el caso de bienes digitales.
9. El PSP liquida los pagos, por lotes y descontando comisiones, y un proceso de conciliación cuadra las liquidaciones con los pedidos.

Los campos de tarjeta importan para el cumplimiento normativo. Cuando una tienda online solo incrusta el formulario de pago de un PSP y no almacena, procesa ni transmite datos de tarjeta por sí misma, puede optar al SAQ A de PCI DSS en lugar del SAQ A-EP, mucho más largo. Con PCI DSS v4.0.1 eso también exige proteger la página frente a scripts maliciosos, como explica el PCI Security Standards Council. Confirma el cuestionario correcto con tu adquirente.

Por qué el navegador no es la fuente de verdad

El cliente puede cerrar la pestaña durante 3-D Secure, perder la conexión después de que el emisor haya aprobado o recargar la página en el peor momento. Si el estado de tus pedidos depende de que el navegador avise, algunos pedidos pagados se quedarán sin pagar y algunos fallidos parecerán pagados. La fuente de verdad son los webhooks del PSP, o su API. Trátalos como cualquier otro flujo de mensajes:

• Verifica la firma. Los PSP firman las peticiones de webhook; por ejemplo, Stripe en una cabecera Stripe-Signature y Adyen con firmas HMAC. Rechaza todo lo que no se verifique.
• Responde rápido y procesa después. La guía de webhooks de Stripe pide una respuesta 2xx antes de cualquier lógica compleja. Pon el evento verificado en una cola y responde.
• Cuenta con duplicados. Un endpoint puede recibir el mismo evento más de una vez. Registra los IDs de los eventos procesados y salta las repeticiones.
• No confíes en el orden. Stripe indica que no garantiza la entrega en el orden en que se generaron los eventos. Cuando llegue un evento que no encaje con el estado actual, consulta el pago en la API del PSP.
• Cuenta con reintentos. En modo live, Stripe reintenta las entregas fallidas durante hasta tres días, con backoff exponencial, así que un endpoint lento recibe el mismo evento otra vez más tarde.

La misma disciplina se aplica en el otro sentido. Envía una clave de idempotencia con cada petición que cree o modifique un pago y reutilízala cuando reintentes tras un timeout, para que un reintento no pueda cobrar dos veces. Las claves no duran para siempre: Stripe puede eliminarlas pasadas 24 horas y Adyen las conserva entre 7 y 14 días.

Después de la autorización: captura, reembolsos, contracargos y liquidaciones

• La autorización retiene; la captura mueve el dinero. Una autorización caduca si no la capturas. En pagos con tarjeta online, el plazo suele ser de alrededor de una semana, y Stripe lo detalla por marca de tarjeta y según quién inició el pago. Captura antes de que venza o se liberará la retención.
• Una captura todavía puede fallar. Adyen documenta casos raros en los que el esquema de tarjetas rechaza una captura después de que el PSP la aceptara, así que los estados de tus pedidos necesitan un camino para eso.
• Los reembolsos son operaciones nuevas sobre un pago capturado. Se completan de forma asíncrona y también llegan como webhooks.
• Los contracargos llegan del emisor, a veces semanas después, cuando el titular disputa un pago. Algunas redes empiezan con una consulta previa; respóndela o puede convertirse en un contracargo difícil de ganar.
• Las liquidaciones necesitan conciliación. Cuadra cada liquidación con los pagos, reembolsos, comisiones y contracargos que salda, usando los informes de liquidación del PSP.

El diagrama

Cómo leerlo:

• Las conexiones continuas son el checkout en sí: pagar (1), iniciar el pago (2), crear el pago (3), enviar los datos de tarjeta al PSP desde sus campos (4), y 3-D Secure y autorización entre el PSP y la red de tarjetas (5).
• Las conexiones discontinuas ocurren más tarde: el webhook (6), el evento verificado en una cola (7) y la API de pagos actualizando el pedido (8). El proceso nocturno de conciliación lee los informes de liquidación del PSP y los cuadra con los pedidos.
• El marco delimita los sistemas del comercio. No entra ningún dato de tarjeta en bruto; el número de tarjeta va de los campos del PSP directo al PSP.

Cómo dibujar un flujo de pago

• Numera los pasos. Los pagos son secuencias; los números hacen legible el orden sin necesidad de un diagrama de secuencia aparte.
• Separa lo síncrono de lo asíncrono. Línea continua para la petición de checkout, discontinua para webhooks, colas y procesos por lotes.
• Marca la frontera de los datos de tarjeta. Muestra qué componentes pueden ver números de tarjeta. Con campos alojados, ninguno de los tuyos debería verlos.
• Muestra dónde cambia el estado del pedido. Debería tener un solo dueño, alimentado por eventos verificados, no por el navegador.
• Nombra las operaciones de dinero. Autorizar, capturar, reembolsar y liquidar son eventos distintos con tiempos distintos; etiquétalos.
• Dibuja los casos de fallo que importan: un timeout al crear el pago (reintentar con la misma clave de idempotencia), un webhook duplicado (deduplicar), un desafío de 3-D Secure abandonado (hacer caducar el pedido), una autorización caducada (volver a autorizar o cancelar).

Para ver el mismo flujo como secuencia, consulta el caso de uso del diagrama de flujo de pagos. Para la parte de eventos, mira la guía del diagrama de arquitectura orientada a eventos, y para la revisión de seguridad, los diagramas de flujo de datos para el modelado de amenazas.

Constrúyelo en Archboard

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Añade una Persona del pack Modelo C4 para el cliente y dos nodos Sistema externo del pack Modelo C4: uno para el proveedor de servicios de pago y otro para el adquirente, la red de tarjetas y el emisor.
3. Añade un Marco del pack Básico para los sistemas del comercio y coloca dentro cuatro nodos Contenedor del pack Modelo C4: la app web de checkout, la API de pagos, el gestor de webhooks y el proceso de conciliación.
4. Añade dentro del marco un Postgres del pack Datos para pedidos y pagos, y una Cola del pack Datos para los eventos de pago.
5. Numera las conexiones en orden, pon en discontinuo las del webhook, la cola y la conciliación, y añade un bloque Markdown del pack Básico que explique los estilos de línea.

El ejemplo usa 11 nodos de diagrama, dentro del plan Free.

Preguntas frecuentes

¿Qué diferencia hay entre una pasarela de pago y un procesador de pagos? La pasarela es la interfaz con la que hablan tus sistemas: API, campos de tarjeta, webhooks. El procesador mueve la transacción por las redes de tarjetas. Muchos PSP ofrecen ambas cosas, junto con una relación de adquirencia.

¿Puedo marcar un pedido como pagado cuando el navegador dice que el pago salió bien? Muestra al cliente una confirmación, pero cambia el estado del pedido solo a partir de un webhook verificado o de una consulta a la API del PSP.

¿Por qué autorizar primero y capturar después? Para cobrar solo lo que se envía. La retención garantiza los fondos; la captura los mueve cuando cumples el pedido. Vigila la caducidad de la autorización.

¿Tengo que gestionar webhooks que llegan desordenados? Sí. Haz que el gestor sea idempotente, lleva el pedido como una máquina de estados que rechace transiciones imposibles y, en caso de duda, consulta el pago actual en el PSP.

¿Usar campos alojados me hace cumplir PCI? Reduce el alcance, pero no lo elimina. Sigues rellenando un cuestionario de autoevaluación y protegiendo la página de pago. Pregunta a tu adquirente cuál te corresponde.

Empieza gratis — un puesto, sin tarjeta de crédito.