Havala API Documentation

import { createHash, createHmac, randomUUID } from "node:crypto";

// Serialise once: the signature covers these exact bytes.
const body = JSON.stringify({
  orderId: "order-8814",
  amount: "12500",   // minor units of currency — 12500 is USD 125.00
  currency: "USD",   // you price in fiat; the buyer picks the crypto at checkout
  returnUrl: "https://merchant.example.com/checkout/success",
});

// Canonical string: {t}\nPOST\n{path}\n{idempotencyKey}\n{sha256(body)}
// The idempotency line belongs to write methods; a GET signs four lines, not five.
const t = Math.floor(Date.now() / 1000);
const idempotencyKey = randomUUID();
const bodyHash = createHash("sha256").update(body).digest("hex");

const v1 = createHmac("sha256", process.env.HAVALA_API_SECRET)
  .update([t, "POST", "/api/v1/invoices", idempotencyKey, bodyHash].join("\n"))
  .digest("hex");

const response = await fetch("https://api2.havala.io/api/v1/invoices", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.HAVALA_API_KEY,
    "X-Signature": `t=${t},v1=${v1}`,
    "Idempotency-Key": idempotencyKey,
  },
  body,
});

// Every gateway response is wrapped: { success, data, timestamp, requestId }.
const { data: invoice } = await response.json();
// => { id: "clyv3n8x40001qh7m2k9d5b1t", referenceId: "INV-260826-041C", status: "OPEN", … }