Idempotència en pagaments: com evitar cobraments duplicats per reintents i webhooks repetits

En el comerç digital, les connexions de xarxa fallen de manera inevitable. Un client prem el botó de pagament al checkout, el navegador envia l'ordre i la passarel·la processa el càrrec amb èxit, però la connexió es talla un mil·lisegon abans que la resposta arribi al navegador. Davant la incertesa, l'usuari torna a fer clic o el backend reintenta la crida de manera automàtica. Si el sistema no compta amb mecanismes de protecció, aquesta segona crida crearà una segona transacció idèntica.

El problema es multiplica en la recepció de notificacions asíncrones. Els proveïdors de pagament utilitzen sistemes de reintents per garantir el lliurament d'esdeveniments. Si el servidor del comerç triga a respondre amb un codi HTTP d'èxit, la passarel·la tornarà a enviar la notificació minuts després. Dissenyar una integració robusta exigeix comprendre què és la idempotència i com aplicar-la tant a les peticions sortints com a la gestió d'esdeveniments entrants.

Què és la idempotència i per què és crítica en pagaments

En matemàtiques i ciències de la computació, una operació és idempotent si produeix el mateix resultat sense importar quantes vegades consecutives s'executi amb els mateixos paràmetres. En el context dels cobraments en línia, significa que enviar deu vegades la mateixa instrucció de cobrament ha de resultar en una única transacció econòmica i deu respostes idèntiques.

Sense idempotència, les fallades de comunicació generen fricció immediata. L'impacte no es limita al malestar del comprador: un cobrament duplicat sol desembocar en comissions bancàries imprevistes per al comerç, gestions manuals de suport i, amb freqüència, devolucions i contracàrrecs que perjudiquen la reputació del negoci davant les xarxes de targetes.

Claus d'idempotència en peticions sortints

Quan el servidor del comerç es comunica mitjançant una API amb la passarel·la de pagament per processar un cobrament, la tècnica habitual consisteix a enviar una capçalera HTTP específica amb un identificador únic, conegut habitualment com a clau d'idempotència (`Idempotency-Key`).

El flux de treball estàndard segueix aquests passos:

• Generació a l'origen: abans de llançar la petició de cobrament, el comerç genera un identificador únic (habitualment un UUID versió 4) vinculat a la intenció de compra o a l'identificador intern del cistell.
• Registre a la passarel·la: en rebre la petició, la passarel·la comprova si ja ha processat una sol·licitud amb aquesta mateixa clau en una finestra de temps predefinida (habitualment entre 24 i 48 hores).
• Resposta emmagatzemada si hi ha repetició: si la clau ja existeix i l'operació original ha conclòs, la passarel·la no executa un nou càrrec a la targeta. En lloc d'això, retorna la resposta exacta que va generar la primera vegada, mantenint el mateix estat i el mateix identificador de transacció.
• Control de concurrència: si la clau ja està registrada però l'operació prèvia continua en curs, la passarel·la retorna un error temporal o un bloqueig de concurrència per evitar condicions de carrera, indicant al client que s'esperi.

Aquest mecanisme trasllada la responsabilitat d'evitar duplicats a la capa de processament, garantint que els reintents automàtics de la infraestructura davant d'errors de xarxa o temps d'espera no generin càrrecs dobles.

Gestió de webhooks duplicats al servidor del comerç

La idempotència no opera en una sola direcció. Mentre que les peticions sortints protegeixen la creació del cobrament, el processament intern al backend del comerç requereix salvaguardes idèntiques en rebre notificacions d'esdeveniments mitjançant webhooks.

Un error habitual consisteix a assumir que cada webhook rebut representa un esdeveniment únic. A la pràctica, les xarxes distribuïdes apliquen semàntiques de lliurament com a mínim un cop (*at-least-once delivery*). Això significa que un esdeveniment es pot lliurar dues o tres vegades a causa de problemes de latència o reintents de l'emissor. Tal com passa en processar webhooks firmats i dades de targeta, el receptor ha de validar tant l'autenticitat com la unicitat del missatge.

Per assegurar la idempotència en rebre esdeveniments, convé aplicar aquest patró a la base de dades:

• Identificador d'esdeveniment com a clau única: cada esdeveniment emès per la passarel·la inclou un identificador únic immutable. El comerç ha de desar aquest identificador en una taula d'esdeveniments processats amb una restricció de clau primària o índex únic.
• Transaccions de base de dades: la inserció de l'identificador d'esdeveniment i l'actualització de la comanda (per exemple, marcar-la com a pagada i alliberar l'estoc) han de succeir dins de la mateixa transacció atòmica de base de dades.
• Ignorar duplicats sense retornar error: si la base de dades rebutja la inserció per duplicitat de clau, el servidor ha de descartar les accions comercials posteriors (evitant duplicar enviaments o crèdits en compte) i respondre a la passarel·la amb un codi HTTP 200 immediatament. Si es retornés un codi d'error, la passarel·la interpretaria una fallada en el lliurament i continuaria reintentant l'enviament.

Bloquejos optimistes i estats de la comanda

En entorns d'alta concurrència, pot passar que la resposta síncrona del checkout i el webhook asíncron arribin pràcticament al mateix temps al backend. Per evitar que tots dos processos executin de manera simultània el lliurament del producte o la generació de la factura, l'arquitectura de pagaments en línia ha d'incorporar màquines d'estats estrictes.

Si la comanda ja es troba en estat «processada» o «pagada», qualsevol procés posterior que intenti canviar l'estat a partir del mateix cobrament s'ha d'aturar de manera neta. L'ús de bloquejos optimistes (comprovant un número de versió del registre abans d'actualitzar) o bloquejos pessimistes a escala de base de dades impedeix que dos fils paral·lels executin la lògica de compliment alhora.

Bones pràctiques per a un disseny a prova de fallades

Garantir la coherència transaccional requereix constància a totes les capes del sistema. Convé fixar identificadors deterministes derivats de la comanda per evitar que una actualització accidental del navegador generi un nou UUID abans de contactar amb el backend. Així mateix, resulta essencial aïllar les operacions crítiques dins de cues de treball amb processament seqüencial per comanda.

La idempotència no és una optimització prescindible, sinó el fonament indispensable perquè la facturació i l'operativa de cobrament mantinguin la seva exactitud davant de les inevitables fallades de les xarxes informàtiques.