# Havala API Documentation

> Havala is a multi-chain crypto payment gateway. A merchant creates a fiat-denominated invoice; the buyer picks a cryptocurrency on a hosted checkout page; Havala leases a one-time deposit address, watches the chain, and marks the payment COMPLETED once the required confirmations land. Settlement runs on Ethereum, Polygon, BSC, Arbitrum, Optimism, Base, Avalanche, Bitcoin, TRON, Solana and TON. The merchant API is HMAC-SHA256 signed per request; payment events arrive as signed webhooks.

Every documentation page is available as raw markdown by appending `.md` to its URL. The full corpus is at https://docs.havala.io/llms-full.txt. An MCP server is available at https://docs.havala.io/api/mcp (streamable HTTP).

Scope: two public API surfaces. `/api/v1/…` is the merchant gateway your server calls, HMAC-SHA256 signed per request. `/checkout/api/v1/…` is the unauthenticated API behind the buyer's hosted payment page, where possession of the invoice id is the capability.

This site documents those two surfaces and nothing else. The merchant dashboard talks to its own separate API, which is an internal frontend contract rather than an integration one and is not documented here. Account setup with no gateway endpoint — creating a merchant point, setting or changing its webhook URL, rotating a signing secret, choosing which chains and currencies to accept — is done in the merchant dashboard UI. Those capabilities exist; they are simply not something you call over HTTP.

Amounts are two different things and mixing them up is the usual first bug: an invoice `amount` is a string of minor units in its fiat `currency` (USD cents), while a payment's `expectedAmount` / `receivedAmount` are decimal strings in the cryptocurrency's own unit. Ids are CUIDs; invoices and payments also carry a short human `referenceId`.

## Guides

- [Getting Started](https://docs.havala.io/guides/getting-started.md): Create a merchant account, take your merchant point credentials, and make your first signed request.
- [Authentication & Request Signing](https://docs.havala.io/guides/authentication.md): How the Havala HMAC-SHA256 canonical string is built and signed, with working code in six languages.
- [Accepting Crypto Payments](https://docs.havala.io/guides/accepting-payments.md): The full invoice lifecycle: create an invoice, hand the buyer a checkout, watch it confirm on-chain, settle.
- [Webhooks](https://docs.havala.io/guides/webhook-setup.md): Receive payment events, verify the signature, survive retries, and stay idempotent under duplicate delivery.
- [Chains, Currencies & Confirmations](https://docs.havala.io/guides/supported-chains.md): Which networks and assets Havala settles, how many confirmations each needs, and how amounts are represented.
- [The Hosted Checkout Page](https://docs.havala.io/guides/hosted-checkout.md): How the buyer-facing payment page works, what the public checkout API exposes, and when to build your own.
- [Testing on Testnets](https://docs.havala.io/guides/testing-sandbox.md): Run the whole flow on testnet: test-mode invoices, faucet funds, and scripting an end-to-end payment.
- [Going Live](https://docs.havala.io/guides/going-live.md): Account verification, production credentials, webhook hardening, and the pre-launch checklist.
- [MCP Server & AI Tools](https://docs.havala.io/guides/mcp.md): Point Claude, Cursor or ChatGPT at the Havala docs MCP server, and build against llms.txt.

## API Reference

- [All endpoints](https://docs.havala.io/api-reference.md)
- [Invoices](https://docs.havala.io/api-reference/invoices.md): The core of a Havala integration. Create a fiat-denominated invoice, check it out onto a chain and token, and follow it through to PAID. Signed with your merchant point credentials.
  - [Create Invoice](https://docs.havala.io/api-reference/invoices/create-invoice.md): `POST /api/v1/invoices`
  - [Get Invoice](https://docs.havala.io/api-reference/invoices/read-invoice.md): `GET /api/v1/invoices/{id}`
  - [Get Invoice Status](https://docs.havala.io/api-reference/invoices/invoice-status.md): `GET /api/v1/invoices/{id}/status`
  - [Checkout Invoice](https://docs.havala.io/api-reference/invoices/invoice-checkout.md): `POST /api/v1/invoices/{id}/checkout`
  - [Cancel Invoice](https://docs.havala.io/api-reference/invoices/cancel-invoice.md): `DELETE /api/v1/invoices/{id}`
- [Payments](https://docs.havala.io/api-reference/payments.md): The on-chain half of an invoice: the leased deposit address, the amount actually received, confirmation progress and the transaction hash. Filterable by status and blockchain.
  - [List Payments](https://docs.havala.io/api-reference/payments/gateway-list-payments.md): `GET /api/v1/payments`
  - [Get Payment](https://docs.havala.io/api-reference/payments/gateway-get-payment.md): `GET /api/v1/payments/{id}`
  - [Get Payment Status](https://docs.havala.io/api-reference/payments/gateway-payment-status.md): `GET /api/v1/payments/{id}/status`
- [Checkout](https://docs.havala.io/api-reference/checkout.md): The unauthenticated API behind the hosted payment page. Fetch an invoice as the buyer sees it, choose a chain and currency, and poll the resulting payment. No signature — the invoice id is the bearer.
  - [Get Public Invoice](https://docs.havala.io/api-reference/checkout/checkout-get-invoice.md): `GET /checkout/api/v1/invoices/{id}`
  - [Poll Invoice Status](https://docs.havala.io/api-reference/checkout/checkout-invoice-status.md): `GET /checkout/api/v1/invoices/{id}/status`
  - [Create Payment For Invoice](https://docs.havala.io/api-reference/checkout/checkout-create-payment.md): `POST /checkout/api/v1/invoices/{id}/checkout`
  - [Poll Payment Status](https://docs.havala.io/api-reference/checkout/checkout-payment-status.md): `GET /checkout/api/v1/payments/{id}/status`
  - [Confirm Havala Wallet Payment](https://docs.havala.io/api-reference/checkout/checkout-confirm-payment.md): `POST /checkout/api/v1/payments/{id}/confirm`

## Client recipes

Paste-in signing clients rather than packages — Havala publishes no client library.

- [Node.js](https://docs.havala.io/sdks/nodejs.md): No dependencies — node:crypto and fetch are built in on Node 18+
- [Python](https://docs.havala.io/sdks/python.md): pip install requests   # hmac and hashlib are standard library
- [PHP](https://docs.havala.io/sdks/php.md): No dependencies — hash_hmac and cURL ship with PHP 8
- [Go](https://docs.havala.io/sdks/go.md): No dependencies — crypto/hmac and net/http are standard library
- [Java](https://docs.havala.io/sdks/java.md): No dependencies — javax.crypto.Mac and java.net.http on JDK 17+
- [.NET](https://docs.havala.io/sdks/dotnet.md): No dependencies — System.Security.Cryptography on .NET 8+