Pagos en cripto con API REST: guía para producción

Una API REST de pagos en cripto permite que tu backend cree una factura, lleve al comprador a una experiencia de pago y entregue el pedido después de la confirmación en la cadena. Una integración de producción no depende de un payload de ejemplo. Se apoya en cuatro contratos que perduran: peticiones autenticadas, un identificador externo de pedido estable, webhooks verificados y un cambio de estado del pedido que sigue siendo correcto cuando la entrega se repite.

Paymos expone la misma superficie de Merchant API en Sandbox y en producción, con credenciales separadas. La API crea, consulta y cancela facturas y retiros, lee saldos, simula los resultados admitidos en Sandbox y crea facturas públicas del Low-Code SDK.

¿Qué gestiona la Merchant API?

La parte Payment cubre la creación, la consulta y la cancelación de facturas. Deja que tu backend conecte su propio identificador de pedido con una factura de Paymos y elija después la integración que verá el cliente: la página de pago alojada, un iframe integrado, el Low-Code SDK u otra interfaz construida alrededor del flujo de pedidos del comercio.

La parte Payout crea, consulta y cancela retiros, mientras que las operaciones de saldo exponen los saldos disponibles por activo. Estas capacidades usan credenciales distintas de las de Payment. Sandbox también puede simular los resultados admitidos de pagos y retiros. Mantén cada capacidad detrás del alcance de credencial más pequeño que necesite el servicio, en lugar de compartir un mismo secreto entre el cobro, las finanzas y el código del navegador.

¿Cómo se autentican las peticiones a la API?

La autenticación de la Merchant API de Paymos usa HMAC-SHA256. No es autenticación por token Bearer. HMAC ata una petición a un secreto compartido sin enviar ese secreto como credencial, pero la integración sigue teniendo que protegerlo en reposo y durante el despliegue.

Firma las peticiones solo en un servidor de confianza. No expongas un secreto de la Merchant API en JavaScript, en un paquete móvil, en un repositorio público ni en registros de analítica. Las credenciales Payment y Payout están separadas, así que un servicio de cobro que solo crea facturas no debería tener una credencial Payout. Rota las credenciales con un proceso de despliegue controlado y evita que el despliegue anterior siga usando un secreto retirado.

¿Cómo se separan los entornos y las credenciales?

Sandbox y producción usan credenciales separadas con la misma superficie de API. Eso hace que Sandbox sirva para validar el comportamiento de la integración sin enviar activos reales, pero no convierte los entornos en intercambiables.

Guarda los secretos de cada entorno con nombres distintos, mantén su configuración base separada e incluye el entorno en los registros de operación. Un servicio de Sandbox nunca debería recibir credenciales de producción. Cuando la integración pase a pagos reales, cambia la configuración del entorno en lugar de reescribir la lógica de negocio. La misma regla vale para los secretos de webhook: quien recibe el evento tiene que saber qué entorno lo produjo antes de cambiar un pedido.

¿Cómo se crean facturas seguras frente a los reintentos?

Genera un external_order_id en tu sistema de pedidos y mantenlo estable durante toda la vida de ese pedido. Paymos usa ese valor, que envía quien llama, para crear la factura. Reutilizar el mismo identificador externo de pedido devuelve la factura existente en lugar de crear otra, y no hay una cabecera Idempotency-Key aparte para esta operación.

Guarda la relación entre el pedido y su factura de Paymos. Si la conexión se corta antes de que llegue la respuesta, reintenta con el mismo external_order_id. No generes nunca un valor nuevo solo porque cambió el intento HTTP. El identificador representa el pedido del negocio, no la petición de red.

¿Qué vía de cobro va después de crear la factura?

La página de pago alojada aporta una página adaptable, pago por QR y enlaces directos a las billeteras admitidas. Se puede usar como redirección o integrada en un iframe. El Low-Code SDK admite importes fijos, un callback de importe en JavaScript, un origen de importe en el DOM y un flujo con botón propio, en modo iframe o con redirección.

Los enlaces de cobro encajan con facturas que se comparten directamente con el comprador. Los plugins oficiales de CMS cubren WooCommerce, WHMCS, OpenCart, PrestaShop, Magento 2, Shopware 6, CS-Cart y Easy Digital Downloads. El producto Host-to-Host es la vía adecuada cuando el backend del comercio tiene que ser el dueño de la creación del pedido, de los cambios de estado y de la entrega, y aun así quiere usar una experiencia de cobro admitida por Paymos.

¿Cómo se verifican las firmas de los webhooks?

Cada webhook de Paymos usa la cabecera X-Webhook-Signature con el formato t={timestamp},v1={hmac_hex}. Vuelve a calcular la firma HMAC-SHA256 con el secreto de webhook configurado y compárala con una comprobación de igualdad en tiempo constante. La autenticación tiene que ocurrir antes de que el evento cambie una factura, un pedido, un nivel de existencias o un derecho de acceso.

La rotación del secreto de webhook incluye un periodo de gracia en el que se aceptan las firmas del secreto actual y del anterior. Configura al receptor para esa transición y retira el secreto anterior cuando termine el periodo. No sustituyas la verificación de firma por una lista de IP permitidas: el origen de red y la autenticidad del mensaje resuelven problemas distintos.

¿Qué debe hacer el receptor ante un fallo de entrega?

Un ciclo de entrega de webhooks incluye 11 intentos. Las esperas entre reintentos crecen de un minuto a ocho horas, y el ciclo completo dura unas 16 horas. Los eventos fallidos o no entregables se pueden reenviar a mano una vez que el sistema receptor se recupera.

Construye la actualización local del pedido de forma que un mismo pago no pueda disparar la entrega dos veces. Guarda una referencia de negocio duradera antes de dar acceso, enviar mercancía o abonar una cuenta. Un aviso repetido debe encontrar el resultado existente y detenerse. El reenvío manual tiene que seguir el mismo camino que la entrega automática, para que nadie salte por accidente la regla de seguridad ante repeticiones.

¿Cómo se organizan las pruebas en Sandbox?

Sandbox puede simular los resultados admitidos de pagos y retiros con la misma superficie de API que usas en producción. Úsalo para probar pagos correctos, pagos fallidos, resultados de retiro, verificación de firmas, creación repetida de facturas, recuperación de la entrega y conciliación, todo sin mover activos reales.

Ata los datos de prueba a valores estables de external_order_id, para que una prueba repetida describa el mismo pedido de negocio. Ejercita el reenvío manual de webhooks y confirma que la entrega sigue ocurriendo una sola vez. Antes de cambiar de entorno, comprueba que el servicio lee las credenciales de producción solo del almacén de secretos de producción y que no queda configurada ninguna URL de callback de pruebas.

¿Cuándo debe el comercio entregar el pedido?

Entrega cuando el pago cumpla la política de confirmación aplicable y la firma del webhook se verifique. Los requisitos de confirmación de Paymos dependen de la red y del importe del pago. Los pagos pequeños pueden exigir menos confirmaciones, mientras que los grandes pueden exigir un umbral de finalidad más alto. Por eso un tiempo fijo de liquidación no forma parte del contrato de integración. La guía de confirmaciones explica el modelo de riesgo que hay debajo.

Aplica la tolerancia de pago insuficiente del proyecto antes de entregar. Un proyecto nuevo nace con un 0,1 %, el rango llega hasta el 2 % y el 0 % es coincidencia estricta. Un pago dentro de la tolerancia configurada se cierra por el importe realmente recibido; la parte que falta no se añade. Por debajo del umbral, una factura de un solo pago queda como pago insuficiente, mientras que una factura de varios pagos puede seguir abierta.

¿Qué entra en el endurecimiento para producción?

Mantén separadas las credenciales Payment, Payout, de Sandbox y de producción. Verifica cada webhook con HMAC-SHA256 y una comparación en tiempo constante, prepárate para el periodo de gracia con el secreto actual y el anterior y haz que la entrega sea segura ante repeticiones. Vigila el ciclo de 11 intentos y documenta el procedimiento de reenvío manual.

Usa un destino de webhook público. Paymos bloquea las direcciones de loopback, privadas, link-local, de CGNAT y ULA de IPv6, y no sigue redirecciones HTTP automáticas. Por último, concilia el estado de la factura en Paymos con tu sistema de pedidos. La integración está lista cuando ni un tiempo de espera agotado, ni una petición de creación repetida, ni un webhook con retraso, ni un reenvío manual, ni un pago insuficiente pueden producir un resultado incorrecto en el pedido.