Cómo confirmar un pago en stablecoins en tu servidor
Para confirmar un pago en stablecoins, deja que tu servidor actúe según el webhook firmado de Cosmos Pay, no según la página que ve tu cliente. Cuando la red confirma un pago, Cosmos Pay envía PAYMENT_INTENT_SUCCEEDED a tu endpoint, firmado con el secreto de ese endpoint. Verifica la firma, responde con un estado 2xx y entrega el pedido una sola vez por evento.
Por qué tu servidor y no el navegador
Un checkout que dice Pagado es solo lo que muestra el navegador de tu cliente. La pestaña se puede cerrar antes de volver a tu sitio, y cualquiera puede abrir tu página de éxito a mano. Lo que hace definitivo un pago es la confirmación de la red.
Cosmos Pay vigila la red por ti y le avisa a tu servidor cuando un pago se confirma. Tu servidor es el lugar para marcar el pedido como pagado y entregarlo.
Qué envía Cosmos Pay
- Un POST HTTPS al endpoint que registras, con un evento JSON: id (empieza con evt_), type, createdAt y data. Para un pago, data es el pago con su estado, monto, activo, red y transacción.
- El encabezado X-Cosmos-Signature: t=<tiempo unix>,v1=<firma>. La firma es el HMAC-SHA256 de t, un punto y el cuerpo sin procesar, con el secreto del endpoint como clave, en hexadecimal.
- Los tipos de evento que elijas, como PAYMENT_INTENT_SUCCEEDED, PAYMENT_INTENT_FAILED o ZK_PAYMENT_SUCCEEDED. Compáralos tal como están escritos, en mayúsculas y con guiones bajos.
- Los encabezados X-Cosmos-Event, X-Cosmos-Event-Id y X-Cosmos-Delivery, que indican el evento y la entrega.
Configura un webhook, paso a paso
Agrega un endpoint
En el dashboard, abre Webhooks y agrega la dirección HTTPS de una ruta de tu servidor. Elige los eventos que quieres recibir; PAYMENT_INTENT_SUCCEEDED viene seleccionado. La dirección debe ser pública: se rechazan las direcciones privadas y locales.
Guarda el secreto
El dashboard muestra el secreto del endpoint (empieza con whsec_) una sola vez. Guárdalo en el entorno de tu servidor, nunca en una página web.
Verifica cada solicitud
Lee el cuerpo sin procesar antes de cualquier parser JSON y comprueba X-Cosmos-Signature con él. Con el SDK de TypeScript, Webhooks.constructEvent verifica la firma, rechaza por defecto una de más de cinco minutos y devuelve el evento.
Responde rápido y después trabaja
Responde con un estado 2xx en cuanto la firma sea válida, y haz después el trabajo lento, como los correos o las actualizaciones de stock.
Procesa cada evento una vez
Guarda el id de cada evento que procesas y omite los que ya viste: un reintento o un reenvío vuelve a enviar el mismo evento.
Envía una prueba
Usa Enviar prueba en el endpoint para recibir un evento ping, luego haz un pago de prueba en Sandbox y mira su entrega en la lista del endpoint.
Cuando tu servidor no responde
Solo una respuesta 2xx cuenta como entregada, y las redirecciones no se siguen. Cosmos Pay reintenta una entrega fallida hasta tres veces con una pausa cada vez mayor, y luego otra vez en rondas posteriores, y el evento conserva su id en cada intento.
En el dashboard, cada endpoint lista sus entregas, con un filtro para las fallidas, y puedes volver a enviar cualquiera de ellas. Cosmos Pay guarda el cuerpo de una entrega durante 30 días, así que reenvíala dentro de ese plazo.
O verifica un pago tú mismo
También puedes consultar un pago concreto: obtenlo por su id para leer su estado, o envía el hash de su transacción (en Solana, la firma de la transacción) a POST /v1/payment-intents/:id/validate. Úsalo como respaldo, por ejemplo cuando tu cliente vuelve antes de que llegue el webhook; el webhook sigue siendo la señal principal.
El dashboard muestra payment_intent.succeeded. ¿Qué nombre lleva el evento?
El tipo del evento es PAYMENT_INTENT_SUCCEEDED, en mayúsculas y con guiones bajos. El dashboard solo lo muestra en una forma más corta.
¿Qué pasa cuando roto el secreto?
El secreto nuevo funciona de inmediato y el anterior deja de funcionar de inmediato, así que actualiza tu servidor justo después de rotarlo.
¿Qué pasa si mi servidor estaba caído?
Cosmos Pay reintenta las entregas fallidas, y puedes volver a enviar cualquier entrega desde el dashboard durante 30 días.
¿Puedo tener varios endpoints?
Sí. Cada endpoint tiene su propia dirección, sus propios eventos y su propio secreto, y cada evento va a cada endpoint suscrito a él.
