Ir al contenido

Documentación

Documentación de la API

Cobra en cripto con la API REST de Paymos: facturas, retiros y webhooks firmados. Incluye inicio rápido, autenticación HMAC, formato de errores y Sandbox.

API

Autenticación
Autentica cada petición de la Merchant API con HMAC-SHA256: cabeceras obligatorias, cadena canónica, marcas de tiempo y protección contra reenvíos.
Claves de API
Crea claves de API Payment o Payout, entiende sus alcances y prefijos, rota las credenciales sin riesgo y separa el acceso de prueba del real.
URL base
Usa la misma URL base de la Merchant API de Paymos para las peticiones de prueba y las reales: el entorno lo elige el prefijo de la clave.
Monedas admitidas
Comprueba cuáles de las 13 redes blockchain admiten USDT, USDC, USD1, DAI y XAUT, respaldado por oro, antes de activar activos en un proyecto.
Manejo de errores
Maneja los errores de la Merchant API de forma uniforme: formato de respuesta, grupos de estados HTTP, códigos legibles por máquina, límites y reintentos.
Códigos de error
Gestiona los fallos de la Merchant API con códigos estables legibles por máquina, detalle de validación por campo y vías de recuperación documentadas.

General

GET
Hora del servidor
GET /v1/time devuelve la hora del servidor de Paymos en segundos Unix, sin clave de API ni firma. Mide una vez la desviación de tu reloj y aplícala al firmar.

Facturas

POST
Crear factura
Crea una factura para aceptar un pago en cripto. Dos flujos: cripto directo (token y red fijados) y fiat (el cliente elige el token en la página de pago).
GET
Listar facturas
Lista facturas con filtros estrictos de estado y fecha, avanza con paginación por cursor y concilia los resultados sin páginas duplicadas.
POST
Confirmar el pago
Confirma el token y la red de una factura denominada en fiat o en cripto desde tu propia página de pago y muestra la dirección de depósito que devuelve.
GET
Obtener factura
Recupera una factura por su ID, revisa su estado de pago y confirmación, y concílialo con tu propia referencia externa de pedido.
POST
Cancelar factura
Cancela una factura abierta antes de que el cliente fije un activo, entiende la transición de estado permitida y procesa la respuesta de cancelación.
POST
Simular el pago de una factura
Lleva una factura de Sandbox a un desenlace de pago y prueba el mismo ciclo de vida y los mismos webhooks que una transferencia confirmada en cadena.

Retiros

POST
Crear retiro
Crea un retiro desde un saldo en tokens hacia una billetera de la lista blanca, elige la red de salida, firma la petición y sigue su estado.
GET
Listar retiros
Lista retiros con filtros estrictos y paginación por cursor hacia delante, revisa las redes de destino y concilia el historial de transferencias con fiabilidad.
GET
Obtener retiro
Recupera un retiro por su ID, revisa su estado actual y la referencia de la transacción, y concilia su finalización con el webhook firmado.
POST
Cancelar retiro
Cancela un retiro pendiente antes de que empiece la firma de la transacción, entiende qué estados permiten la cancelación y procesa la respuesta actualizada.
POST
Simular la finalización de un retiro
Completa un retiro pendiente de Sandbox sin difundir ninguna transacción y verifica de extremo a extremo los webhooks de salida de fondos.

Saldo

GET
Obtener saldos
Consulta los saldos de token disponibles, léelos por activo en lugar de por red de origen y usa el resultado antes de crear un retiro.

Canales de pago

POST
Crear canal de pago
Crea una identidad de cobro reutilizable para un cliente, con tu propio identificador externo y una dirección permanente en cada red admitida.
GET
Listar canales de pago
Recorre tus canales de pago de más nuevo a más antiguo con paginación por cursor y filtra por proyecto, estado o tu propio identificador externo.
GET
Obtener canal de pago
Lee un canal de pago con sus direcciones permanentes por red, los tokens que cada red acepta ahora mismo y tus porcentajes de comisión vigentes.
POST
Bloquear canal de pago
Deja de atribuir depósitos nuevos a un canal de pago sin borrarlo, sin liberar sus direcciones y sin tocar los pagos que ya habías recibido.
POST
Desbloquear canal de pago
Reanuda la atribución de depósitos a un canal de pago: el servidor resuelve el estado de vuelta según el canal tenga ya una dirección o ninguna.
GET
Sondear los depósitos del canal
Sondea los depósitos confirmados de tus canales en orden de publicación, con un cursor que siempre avanza y no se salta ni repite ningún pago liquidado.
GET
Obtener depósito del canal
Lee un depósito de canal de pago en cualquier estado, con su comisión congelada, sus importes bruto, comisión y neto, y sus pruebas en cadena.
POST
Simular un depósito en el canal
Lleva un depósito de canal en Sandbox hasta la etapa que elijas y recibe los mismos webhooks que produce un pago real confirmado en cadena.

Webhooks

Webhooks
Conecta Paymos con tu backend mediante endpoints de webhook firmados y aislados por entorno, con un flujo de entrega completo.
Eventos de webhook
Gestiona los 16 tipos de evento de webhook de Paymos con el estado del recurso explícito y una semántica clara de estado final.
Contenido de los webhooks
Lee el sobre versionado del webhook y la instantánea completa de la factura, el retiro o el depósito del canal que viaja en data.
Verificar firmas
Verifica X-Webhook-Signature con HMAC-SHA256, compara las firmas de forma segura, aplica las reglas de marca temporal y admite la rotación del secreto.
Entrega y reintentos
Diseña para 11 intentos de entrega repartidos en unas 16 horas, deduplica eventos repetidos, revisa los fallos y reenvía tras la recuperación.
Probar webhooks
Recorre la ruta real de factura de Sandbox y entrega de webhook desde la consola interactiva de la documentación.

Plugins

Plugin de WooCommerce
Instala el plugin oficial de Paymos para WooCommerce, conecta las credenciales del proyecto, prueba el pago y actualiza pedidos por webhook firmado.
Plugin de WHMCS
Añade pagos en stablecoins a las facturas de WHMCS, conecta Paymos sin escribir ninguna clave, prueba el webhook y conserva tus reglas de aprovisionamiento.
Plugin de OpenCart
Instala la extensión oficial de Paymos para OpenCart, conecta la tienda sin copiar secretos y valida los cambios de estado de pago en modo de prueba.
Plugin de Easy Digital Downloads
Conecta Paymos con Easy Digital Downloads, prueba un pedido en stablecoins, verifica los avisos firmados y entrega los archivos solo tras la confirmación.
Plugin de CS-Cart
Instala el complemento oficial de Paymos para CS-Cart y Multi-Vendor, conecta un proyecto, verifica los cambios de estado firmados y prueba un pedido.
Plugin de Magento 2
Instala el módulo de Paymos para Magento 2 o Adobe Commerce, conecta las credenciales de prueba y reales y verifica el flujo de estados del pedido a la factura.
Plugin de Shopware 6
Instala el plugin de Paymos para Shopware 6, actívalo por canal de ventas, valida las actualizaciones de transacción firmadas y cambia de modo sin reinstalar.
Plugin de PrestaShop
Añade Paymos a PrestaShop 8 o 9, conecta la tienda con un solo clic, verifica el callback firmado y prueba la transición del pedido a «Pago aceptado».