@hanix.io/business

SDK oficial de Node.js para la Hanix Business API: crear y consultar órdenes de pago con autenticación HMAC-SHA256.

Instalación

npm install @hanix.io/business

pnpm add @hanix.io/business

Requisitos

• Node.js 22.12 o superior
• merchantId: UUID del comercio (cabecera business-merchant-id)
• apiKey: secreto HMAC del comercio (no se envía en la red; solo firma las solicitudes). Obtén ambos en el panel Hanix o en GET /merchants/me con tu sesión merchant.

El SDK apunta por defecto a https://api.hanix.io/api/v1.

Inicio rápido

import { HanixBusinessClient } from '@hanix.io/business';

const client = new HanixBusinessClient({
  merchantId: process.env.HANIX_MERCHANT_ID!,
  apiKey: process.env.HANIX_API_KEY!,
});

const order = await client.createPaymentOrder({
  merchant_reference: 'pedido-1001',
  amount_in_cents: 15000,
  currency_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  country_id: 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy',
  description: 'Suscripción mensual',
  customer_email: '[email protected]',
});

console.log(order.payment_url);

API del cliente

new HanixBusinessClient(options)

| Opción | Obligatorio | Descripción | |--------|-------------|-------------| | merchantId | Sí | UUID del comercio | | apiKey | Sí | Clave API (secreto HMAC) | | timeoutMs | No | Tiempo máximo por solicitud (default: 30000) | | fetch | No | Implementación de fetch (tests o entornos custom) | | userAgent | No | Cabecera User-Agent (default: @hanix.io/business) |

createPaymentOrder(input)

Crea una orden de pago (POST /business/payment-orders).

Campos obligatorios: merchant_reference, amount_in_cents, currency_id, country_id.

Opcionales: description, customer_email, success_url, cancel_url, expires_at, metadata.

Devuelve una PaymentOrder con payment_url, public_token, status, etc.

listPaymentOrders(params?)

Lista órdenes del comercio (GET /business/payment-orders).

Filtros opcionales: status, merchant_reference, currency_id, country_id, created_from, created_to, expires_from, expires_to, page, limit, sort (created_at_asc | created_at_desc).

getPaymentOrder(paymentOrderId)

Obtiene una orden por id (GET /business/payment-orders/:id).

listPaymentOrderAttempts(paymentOrderId, params?)

Lista intentos de pago de una orden (GET /business/payment-orders/:id/attempts).

Filtros opcionales: status (initiated, processing, succeeded, failed, expired, abandoned), page, limit, sort.

listMerchantPspMethods()

Lista métodos PSP del comercio agrupados por PSP (GET /business/merchant-payment-settings/psp-methods).

Devuelve un array de MerchantPspGroup con pspId, pspName, methods (cada uno con pspMethodId, countryId, currencyId, códigos ISO, isActive) y credentials descifradas por PSP, o null.

Autenticación

Cada solicitud lleva estas cabeceras (generadas por el SDK):

| Cabecera | Descripción | |----------|-------------| | business-merchant-id | UUID del comercio | | business-timestamp | Unix en segundos | | business-signature | HMAC-SHA256(apiKey, timestamp + rawBody) en hexadecimal |

En GET, el cuerpo firmado es la cadena vacía. En POST, el cuerpo JSON se serializa con claves ordenadas para que la firma coincida con los bytes enviados.

Errores

import {
  HanixBusinessError,
  HanixBusinessNetworkError,
  HanixBusinessConfigError,
} from '@hanix.io/business';

try {
  await client.getPaymentOrder('...');
} catch (error) {
  if (error instanceof HanixBusinessError) {
    // 4xx / 5xx de la API (error.status, error.message, error.body)
  } else if (error instanceof HanixBusinessNetworkError) {
    // Timeout o fallo de red (error.cause)
  } else if (error instanceof HanixBusinessConfigError) {
    // merchantId o apiKey inválidos al crear el cliente
  }
}

| Clase | Cuándo | |-------|--------| | HanixBusinessError | Respuesta HTTP no exitosa de Hanix | | HanixBusinessNetworkError | Timeout, red o fetch no disponible | | HanixBusinessConfigError | Opciones inválidas del cliente |

Buenas prácticas

• Guarda apiKey en variables de entorno o un gestor de secretos; no la subas al repositorio.
• La apiKey nunca viaja en cabeceras ni en el cuerpo; solo se usa para firmar.
• Usa merchant_reference único por orden para evitar conflictos (409).

Utilidades exportadas

Para integraciones avanzadas o pruebas manuales:

• HANIX_BUSINESS_API_BASE_URL — URL base de la API
• stableStringify, signBusinessPayload, buildBusinessAuthHeaders, verifyBusinessPayload
• Constantes de cabeceras: BUSINESS_MERCHANT_ID_HEADER, BUSINESS_TIMESTAMP_HEADER, BUSINESS_SIGNATURE_HEADER