Pasarela
Entrar

Crear retiro

POSThttps://api.pasarela.hi-g.io/v1/payouts

Paga a un usuario desde tu caja de retiros. Si se acepta (201), el saldo queda reservado y el retiro sale en segundos; el resultado llega con los webhooks payout.completed o payout.failed. Es idempotente: repetir la misma petición con el mismo external_id devuelve el mismo retiro (200, created: false) y nunca paga dos veces.

Ver el ejemplo y probar ↓

Descuenta las fichas antes de llamar

Resta el saldo del usuario en tu sistema y luego crea el retiro con un external_id propio (por ejemplo, el id de la operación en tu base de datos). Si la llamada falla por red, repítela con el mismo external_id. Si llega payout.failed, devuelve las fichas.

  • En lugar de external_id puedes enviar la cabecera Idempotency-Key. Uno de los dos es obligatorio.
  • Mismo external_id con otro token, monto o destino: 409 idempotency_conflict.
  • Si tu empresa tiene solo billeteras Hig (activo por defecto), to tiene que ser la billetera de un usuario de la app Hig. Si no lo es: 422 not_hig_wallet, y el usuario debe descargar Hig y darte su dirección. Para avisarle antes, usa Comprobar billetera.
  • Se rechazan como destino la dirección cero, tu dirección de fondeo, los contratos de la pasarela y cualquier dirección de depósito de la pasarela (el dinero volvería a entrar como depósito). Las billeteras inteligentes (Safe y similares) se aceptan.
  • Las comprobaciones de saldo, límites y mínimo se hacen al crear y otra vez en el contrato al pagar. Si algo cambió entre medias (por ejemplo, apagaste tus límites), el retiro termina en failed sin mover dinero.

Parámetros del cuerpo

tokenstringobligatorio

Símbolo del token: USDT o USDC. No distingue mayúsculas.

amountstringobligatorio

Lo que pide el usuario (sus fichas, a 1 USD cada una) como texto decimal: "500", "12.50". No puede tener más decimales que el token.

tostringobligatorio

Billetera del usuario en Arbitrum (0x + 40 caracteres hexadecimales). La elige el usuario: una transferencia en blockchain no se puede deshacer.

external_idstring

Tu identificador del retiro, único por empresa. Máximo 200 caracteres. Obligatorio si no envías la cabecera Idempotency-Key.

customer_idstring

Tu identificador del usuario, para buscar y conciliar. Texto libre, máximo 200 caracteres. Se devuelve como customer_ref.

metadataobjectPor defecto: {}

Datos libres que se guardan con el retiro y vuelven en la API y los webhooks.

Cabeceras

x-api-keystringobligatorio

Clave de API de la empresa. Se crea y se revoca desde el panel.

Respuestas

Comprobar billetera