Integración API
Recibir y depurar callbacks
Observa las notificaciones de la plataforma y comprueba después la firma, las respuestas y los duplicados en tu propio servicio.
Guía paso a paso
Sigue los pasos en tu propio panel. Haz clic en una imagen para ampliarla.
Abre el receptor de callbacks e introduce Merchant UID y API Key. Copia el notifyUrl de depuración en los pedidos que quieras observar, o selecciona Usar dirección de depuración en la herramienta de pedidos.
Paso 1 · Haz clic para ampliar Inicia la recepción para actualizar cada cuatro segundos y ver hasta los 20 registros más recientes enviados a esa dirección. Actualizar ahora consulta de inmediato. Detener solo pausa la consulta de la página; no cancela pedidos ni desactiva el receptor del servidor. No aparecen pedidos que usen otro notifyUrl.
Los cobros envían completed después de procesarse correctamente. Los pagos salientes envían su estado final confirmed o failed. Crear un pedido, esperar un pago o confirmar en blockchain todavía no genera un callback de éxito. Compara pedidos, moneda, monto, hash, firma y entrega. La verificación del receptor de depuración no demuestra que tu sistema haya procesado el cobro.
Para tu servicio, utiliza el ejemplo completo Node.js o PHP del receptor. Despliégalo en una URL HTTPS pública y conserva rawBody. Con la API Key del pedido original, calcula HMAC-SHA256(timestamp + "." + nonce + "." + rawBody) y compáralo con x-callback-signature. No reformatees el JSON ni uses x-signature en lugar de la firma del callback.
Después de verificar la firma, comprueba comercio, relación del pedido, red, moneda, monto y estado final. Usa transacciones y restricciones únicas de base de datos para actualizar una sola vez. Devuelve HTTP 2xx solo tras procesar correctamente o guardar de forma fiable en una cola. Rechaza firmas inválidas y no declares éxito si falla tu servicio.
Prueba con una clave ficticia local: un callback válido pasa, un body alterado falla, los duplicados actualizan una sola vez y el proceso puede recuperarse de una interrupción. Luego configura tu notifyUrl y revisa registros, respuestas y pedidos. Un timeout o una respuesta distinta de 2xx permite hasta tres intentos: el segundo un minuto después del primer fallo y el tercero cinco minutos después del siguiente. No hay reintentos ilimitados.
Si falta un callback, revisa el estado final, notifyUrl, UID, acceso HTTPS, firma del cuerpo original y respuesta HTTP. El receptor de depuración no sustituye las pruebas de tu propio servicio. No registres la clave completa.