Un webhook de pago duplicado debe producir una sola entrega prevista para la misma transacción verificada. Para PayRequest payment.succeeded, verifica primero la firma del cuerpo original y después usa data.id en una clave de procesamiento duradera. Repetir una notificación no debe crear otra entrega ni crédito de servicio.
Esta lista es un diseño y protocolo de aceptación para desarrolladores de sistemas propios de entrega. Un registro de base de datos no garantiza por sí solo una acción externa ejecutada exactamente una vez.
Verifica el contrato real
La documentación de webhooks de PayRequest describe HTTPS POST, X-PayRequest-Signature y HMAC-SHA256 sobre el cuerpo original. Valida con un secreto del servidor y comparación en tiempo constante. Comprueba formato y longitud: algunas funciones rechazan longitudes diferentes. Conserva los bytes antes de analizar JSON.
En payment.succeeded, data.id es el identificador de transacción. La carga publicada no documenta un event ID independiente en el nivel superior. No copies event.id de otro proveedor sin verificar. Mantén secretos fuera del navegador y evita registrar todos los datos del cliente innecesariamente.
Identifica el pago, no el enlace compartido
Una clave ilustrativa es integration-account / payment.succeeded / data.id. Incluye el ámbito de cuenta si el receptor atiende a varios comerciantes. Es un diseño propio, no un campo de PayRequest.
Un payment_link_id puede recibir varios pagos legítimos. Correo, importe y descripción tampoco bastan como claves únicas: un cliente puede comprar dos veces. La misma data.id es repetición; una nueva data.id en el mismo enlace es otro pago.
Vincula la transacción a un pedido o derecho real mediante una referencia controlada de la integración. El éxito no define por sí solo paquete, período o cantidad. Aísla referencias desconocidas para revisión.
Compara importe y moneda con el pedido previsto antes de autorizar la entrega. Los valores inesperados requieren revisión.
Guarda de forma duradera antes de confirmar
Usa una restricción única y una transacción atómica para guardar el pago aceptado y una tarea de entrega pendiente. Una outbox duradera separa recepción y trabajo lento. Confirma después de la aceptación duradera; una repetición conocida no genera otra tarea.
PayRequest acepta 2xx. Los documentos indican cinco intentos para webhooks de fianza, pero para pagos solo mencionan la política de cola existente sin número. No adoptes esos plazos como política de reintentos de pago ni de conservación para deduplicar.
La entrega externa puede completarse y el worker fallar antes de registrar el resultado. Usa la idempotencia admitida por el sistema destino o concilia el resultado externo antes de repetir. El registro local no garantiza ejecución única entre sistemas.
Ejecuta esta matriz original
Prueba un receptor aislado con datos ficticios firmados y sin entrega real. Usa un secreto de prueba; cambiar el cuerpo exige una firma nueva. Son pruebas propuestas, no realizadas en una cuenta de producción.
| Prueba | Entrada | Resultado requerido |
|---|---|---|
| Repetición | Misma transacción dos veces | Un pago y una tarea |
| Concurrencia | Dos copias válidas simultáneas | Restricción única evita dos tareas |
| Segunda compra | Mismo enlace, nueva transacción | Dos pagos y tareas |
| Manipulación | Cuerpo cambiado, firma anterior | Rechazo antes de entregar |
| Fallo del worker | Fallo tras guardar la tarea | Trabajo pendiente recuperable |
Prueba también referencias desconocidas y firmas con longitud incorrecta. Cuenta registros duraderos y efectos externos por separado. HTTP 200 confirma recepción, no entrega finalizada.
Concilia pago y efecto
Guarda transacción, ámbito de cuenta, estado, tarea y referencia del resultado externo. Investiga pagos con entrega pendiente por la misma ruta controlada, sin una segunda entrega manual fuera del registro.
Empieza con la documentación API de PayRequest. Conciliación de pagos aporta contexto financiero; pago y entrega son registros distintos.
Nota editorial: la IA ayudó con artículo y portada. Contrato revisado el 4 de octubre de 2026. Clave, matriz y arquitectura son recomendaciones originales, no una prueba de integración en producción ni garantía de entrega.
