Flujo de integración

Una integración típica tiene tres piezas en tu lado: una llamada para crear el cliente, una pantalla que muestra su QR y una ruta que recibe webhooks. Lo demás es opcional.

1. 1

   Recibe tus credenciales

   Al dar de alta tu empresa, la plataforma te entrega una clave de API (sk_test_…) y un secreto de webhooks (whsec_…). En el alta se fijan tu tesorería, tu billetera de comisiones y, si la tienes, tu billetera de administración. Ver Sin custodia.

2. 2

   Revisa tu configuración

   Con Ver cuenta compruebas la red, tus billeteras, las comisiones y quién paga el gas. Ajusta tu comisión, el mínimo y el webhook con Actualizar cuenta.

3. 3

   Monta la ruta de webhooks

   Verifica la firma, guarda el id del evento y responde 200. Pruébala con Enviar webhook de prueba. Ver Webhooks.

4. 4

   Crea un cliente por usuario

   Llama a Crear cliente con tu identificador como external_id cuando el usuario quiera pagar por primera vez (o al registrarse). Repetir la llamada devuelve el mismo cliente, así que no necesitas comprobar antes si existe.

5. 5

   Muestra dónde pagar

   Redirige a pay_url, o dibuja tu propia pantalla con address y qr_url. Indica siempre la red: Arbitrum. Ver Página de pago.

6. 6

   Si necesitas un monto exacto, cotiza

   Los depósitos son de monto libre. Si quieres que a tu tesorería llegue una cifra concreta, pide una cotización y muestra al usuario cuánto debe enviar.

7. 7

   Acredita al confirmar

   Cuando llegue deposit.confirmed, suma data.deposit.amount al saldo del usuario identificado por data.deposit.customer.external_id. Decide si acreditas el monto depositado o el neto (breakdown.net), según quién asuma las comisiones en tu negocio.

8. 8

   Concilia al liquidar

   Con deposit.settled tienes el reparto definitivo y la transacción (sweep_tx_hash) que llevó el dinero a tu tesorería. Para cuadrar períodos usa Listar depósitos y Ver resumen.

9. 9

   Recupera lo que se pierda

   Si tu servidor estuvo caído, los webhooks se reintentan durante unos 3 días. Además, Listar eventos con after=<último seq> devuelve todo lo ocurrido, en orden.

Lo que ocurre en cada depósito#

1curl -X POST https://api.pasarela.hi-g.io/v1/customers \2  -H "x-api-key: sk_test_4f9c…" \3  -H "content-type: application/json" \4  -d '{"external_id": "TARJETA-000123"}'

Antes de salir a producción#

• La firma de los webhooks se verifica sobre el cuerpo sin tocar y se rechazan avisos de más de 5 minutos.
• Un mismo evento o un mismo depósito no acredita dos veces.
• Solo deposit.confirmed acredita saldo.
• Tu código lee los decimales de la API en vez de darlos por fijos (el USDC de pruebas tiene 8).
• La clave de API está solo en el servidor, en una variable de entorno o un gestor de secretos.
• La pantalla de pago dice claramente la red (Arbitrum) y los tokens aceptados.
• Tu empresa tiene su propia billetera de administración. Ver Sin custodia.