Todos los endpoints

URL base https://hub.stablezact.com. Anteponga /api/v1 a cada ruta. Consulte Versionado.

La mayoría de estos endpoints requieren autenticación. Unos pocos no, porque una página de checkout en el navegador del cliente tiene que poder acceder a ellos: /payments/public/{paymentId}, /payments/contract/{chainId}, /deposits/chains, /payments/cross-chain/sources, /currency/rates y /payments/health.

Nota

Esta es la lista completa de lo que existe. La mayoría tienen el detalle completo de solicitud y respuesta en la Referencia de la API; unos pocos todavía no, y se enumeran aquí para que no parezca que falta nada.

Pagos

Método	Ruta	Propósito
POST	/payments/create	crear un pago
GET	/payments/{paymentId}	leer un pago, incluido el progreso de la liquidación
GET	/payments/{paymentId}/status	si el cliente ha pagado
GET	/payments/status/{paymentId}	lo mismo, ruta alternativa
GET	/payments/public/{paymentId}	detalle limitado, seguro para una página de checkout
POST	/payments/process	enviar una transacción on-chain para su verificación
POST	/payments/fail	marcar un pago como fallido, cancelado o caducado
POST	/payments/verify-qr	verificar un pago iniciado por QR
GET	/payments/contract/{chainId}	dirección del contrato y ABI de una cadena
GET	/payments/merchant/list	sus pagos, paginados (clave de API y secreto)
GET	/payments/merchant/stats	totales de su cuenta (clave de API y secreto)
GET	/payments/health	estado del servicio

Reintentar de forma segura

La creación de pagos es idempotente. El servidor decide si una solicitud es una repetición usando el primero de estos elementos que encuentre:

1. una cabecera de solicitud Idempotency-Key, que es el mecanismo preferible
2. un orderId en el cuerpo
3. una huella del cuerpo completo de la solicitud

Así, un reintento idéntico se reconoce aunque no envíe ninguno de los dos, pero depender de eso es frágil: si cambia un solo campo, se convierte en un pago nuevo. Envíe una Idempotency-Key en todo lo que pueda reintentar.

Idempotency-Key: order-1234-attempt-1

Las claves están limitadas a su cuenta y al endpoint, y la ruta con versión y la ruta sin versión comparten clave, así que reintentar contra /api/payments/create después de /api/v1/payments/create no creará un segundo pago.

Direcciones de depósito

Un pago con dirección de depósito da al cliente una dirección única a la que enviar, y los fondos se reenvían a su wallet de liquidación.

Método	Ruta	Propósito
POST	/deposits/create	crear un pago con dirección de depósito
GET	/deposits/status/{paymentId}	estado del depósito
GET	/deposits/balance/{paymentId}	lo que ha llegado hasta ahora
GET	/deposits/chains	cadenas que admiten direcciones de depósito
POST	/deposits/refund-request/{paymentId}	facilitar una dirección para un reembolso

Entre cadenas

Para clientes que pagan desde una cadena distinta de la facturada.

Método	Ruta	Propósito
POST	/payments/cross-chain/create	crear un pago entre cadenas
GET	/payments/cross-chain/sources	cadenas desde las que puede pagar un cliente
GET	/payments/cross-chain/status/{paymentId}	progreso del bridge

Redes y tipos de cambio

Método	Ruta	Propósito
GET	/networks	todas las redes compatibles
GET	/networks/payable	redes que pueden aceptar pagos en este momento
GET	/networks/stablecoins	tokens compatibles
GET	/networks/payable/stablecoins	tokens en redes que pueden aceptar pagos
GET	/currency/rates	tipos de cambio usados para la conversión

Servicio

Método	Ruta	Propósito
GET	/api/health	si el servicio está activo, sin versión
GET	/api/versions	versiones compatibles, sin versión

Esos dos son la excepción a la regla de /api/v1. Comprobar si el servicio está activo, y preguntar qué versiones existen, no puede exigir conocer antes una versión. /api/v1/health devuelve 404 por diseño.