Idempotencia en pagamentos: como evitar cobros duplicados por reintentos e webhooks repetidos

No comercio dixital, as conexións de rede fallan de maneira inevitable. Un cliente preme o botón de pagamento no checkout, o navegador envía a orde e a pasarela procesa o cargo con éxito, pero a conexión córtase un milisegundo antes de que a resposta chegue ao navegador. Ante a incerteza, o usuario volve facer clic ou o backend reintenta a chamada de forma automática. Se o sistema non conta con mecanismos de protección, esa segunda chamada creará unha segunda transacción idéntica.

O problema multiplícase na recepción de notificacións asíncronas. Os provedores de pagamento utilizan sistemas de reintentos para garantir a entrega de eventos. Se o servidor do comercio tarda en responder cun código HTTP de éxito, a pasarela volverá enviar a notificación minutos despois. Deseñar unha integración robusta esixe comprender que é a idempotencia e como aplicala tanto nas peticións saíntes como na xestión de eventos entrantes.

Que é a idempotencia e por que resulta crítica en pagamentos

En matemáticas e ciencias da computación, unha operación é idempotente se produce o mesmo resultado sen importar cantas veces consecutivas se execute cos mesmos parámetros. No contexto dos cobros en liña, significa que enviar dez veces a mesma instrución de cobro debe resultar nunha única transacción económica e dez respostas idénticas.

Sen idempotencia, os fallos de comunicación xeran fricción inmediata. O impacto non se limita ao malestar do comprador: un cobro duplicado adoita desembocar en comisións bancarias imprevistas para o comercio, xestións manuais de soporte e, con frecuencia, devolucións e contracargos que prexudican a reputación do negocio ante as redes de tarxetas.

Chaves de idempotencia en peticións saíntes

Cando o servidor do comercio se comunica mediante unha API coa pasarela de pagamento para procesar un cobro, a técnica habitual consiste en enviar unha cabeceira HTTP específica cun identificador único, coñecido habitualmente como chave de idempotencia (`Idempotency-Key`).

O fluxo de traballo estándar segue estes pasos:

• Xeración na orixe: antes de lanzar a petición de cobro, o comercio xera un identificador único (comunmente un UUID versión 4) vinculado á intención de compra ou ao identificador interno do carriño.
• Rexistro na pasarela: ao recibir a petición, a pasarela comproba se xa procesou unha solicitude con esa mesma chave nunha ventá de tempo predefinida (habitualmente entre 24 e 48 horas).
• Resposta almacenada se hai repetición: se a chave xa existe e a operación orixinal concluíu, a pasarela non executa un novo cargo na tarxeta. No seu lugar, devolve a resposta exacta que xerou a primeira vez, mantendo o mesmo estado e o mesmo identificador de transacción.
• Control de concorrencia: se a chave xa está rexistrada pero a operación previa segue en curso, a pasarela devolve un erro temporal ou un bloqueo de concorrencia para evitar condicións de carreira, indicando ao cliente que agarde.

Este mecanismo traslada a responsabilidade de evitar duplicados á capa de procesamento, garantindo que os reintentos automáticos da infraestrutura ante erros de rede ou tempos de espera non xeren cargos dobres.

Xestión de webhooks duplicados no servidor do comercio

A idempotencia non opera nunha soa dirección. Mentres que as peticións saíntes protexen a creación do cobro, o procesamento interno no backend do comercio require salvagardas idénticas ao recibir notificacións de eventos mediante webhooks.

Un erro habitual consiste en asumir que cada webhook recibido representa un evento único. Na práctica, as redes distribuídas aplican semánticas de entrega polo menos unha vez (*at-least-once delivery*). Isto significa que un evento pode entregarse dúas ou tres veces debido a problemas de latencia ou reintentos do emisor. Tal como ocorre ao procesar webhooks firmados e datos de tarxeta, o receptor debe validar tanto a autenticidade como a unicidade da mensaxe.

Para asegurar a idempotencia ao recibir eventos, convén aplicar este patrón na base de datos:

• Identificador de evento como chave única: cada evento emitido pola pasarela inclúe un identificador único inmutable. O comercio debe gardar este identificador nunha táboa de eventos procesados cunha restrición de chave primaria ou índice único.
• Transaccións de base de datos: a inserción do identificador de evento e a actualización do pedido (por exemplo, marcalo como pagado e liberar o stock) deben ocorrer dentro da mesma transacción atómica de base de datos.
• Ignorar duplicados sen devolver erro: se a base de datos rexeita a inserción por duplicidade de chave, o servidor debe descartar as accións comerciais posteriores (evitando duplicar envíos ou créditos en conta) e responder á pasarela cun código HTTP 200 inmediatamente. Se se devolvese un código de erro, a pasarela interpretaría un fallo na entrega e continuaría reintentando o envío.

Bloqueos optimistas e estados da orde

En contornas de alta concorrencia, pode ocorrer que a resposta síncrona do checkout e o webhook asíncrono cheguen practicamente ao mesmo tempo ao backend. Para evitar que ambos os procesos executen de forma simultánea a entrega do produto ou a xeración da factura, a arquitectura de pagamentos en liña debe incorporar máquinas de estados estritas.

Se o pedido xa se atopa en estado «procesado» ou «pagado», calquera proceso posterior que intente cambiar o estado a partir do mesmo cobro debe deterse de forma limpa. O uso de bloqueos optimistas (comprobando un número de versión do rexistro antes de actualizar) ou bloqueos pesimistas a nivel de base de datos impide que dous fíos paralelos executen a lóxica de cumprimento ao mesmo tempo.

Boas prácticas para un deseño a proba de fallos

Garantir a coherencia transaccional require constancia en todas as capas do sistema. Convén fixar identificadores deterministas derivados do pedido para evitar que un refresco accidental do navegador xere un novo UUID antes de contactar co backend. Así mesmo, resulta esencial illar as operacións críticas dentro de colas de traballo con procesamento secuencial por pedido.

A idempotencia non é unha optimización prescindible, senón o cimento indispensable para que a facturación e a operativa de cobro manteñan a súa exactitude ante os inevitables fallos das redes informáticas.