Create Invoice

POST/api/v1/invoicesCore

Create an invoice in status OPEN. amount is a string of minor units in the fiat currency you name; no chain or token is chosen yet — that happens at checkout. The response carries the CUID id you sign into every later call and a human referenceId of the form INV-YYMMDD-NNNL.

Authentication

Signature Pattern

HMAC-SHA256(apiSecret, "{t}\nPOST\n/api/v1/invoices\n{idempotencyKey}\n{sha256(body)}")

Header	Value	Description
`X-API-Key`	a3f9c1e84b7d2065f1a4c8e93b6d0271	Merchant point API key, a hex string issued with its secret when the point is created. Identifies the point whose invoices you can reach.
`X-Signature`	t=1787735662,v1=8c1f0b7d4a29e63f5b0c8d17a4e92f6b3d05c7a81e4f9b26d3c07a5e18b4f962	Request signature, format t={unix_seconds},v1={hex_hmac_sha256}. Timestamp tolerance is 300s.
`Content-Type`	application/json	Always application/json. The signature is taken over the raw body bytes, so send exactly what you signed.
`Idempotency-Key`	9f2b1c44-7a0e-4d63-9f18-2c5b7ea31d04	Required on POST/DELETE. Unique per logical operation; replays return the first response for 24h.

Request Parameters

Name	Type	Required	Description
`orderId`	string	Required	Your own order identifier, max 255 chars. Indexed with merchantId for lookups on your side.
`amount`	string	Required	Amount in the minor unit of currency (USD cents), sent as a string and stored as BigInt.
`currency`	string	Required	Fiat denomination code, max 10 chars, e.g. USD. This is not the crypto the buyer pays in.
`description`	string	Optional	Free text carried on the invoice, max 500 chars. Defaults to an empty string.
`customerEmail`	string	Optional	Buyer email, validated as an address. Returned as null when omitted.
`customerName`	string	Optional	Buyer display name, max 255 chars. Returned as null when omitted.
`customerMetadata`	object	Optional	Arbitrary JSON about the buyer. Stored as-is and echoed back unchanged; defaults to {}.
`metadata`	object	Optional	Arbitrary JSON of your own. Stored as-is and echoed back unchanged; defaults to {}.
`returnUrl`	string	Optional	Absolute URL the buyer lands on after a successful payment. Must parse as a URL.
`cancelUrl`	string	Optional	Absolute URL the buyer lands on after abandoning the invoice. Must parse as a URL.
`expiresInMinutes`	integer	Optional	Invoice lifetime, 15 to 1440 minutes. Defaults to 60 and sets expiresAt to now plus that window.

Request Example

JSONRequest Body

{
  "orderId": "order-8814",
  "amount": "12500",
  "currency": "USD",
  "description": "Pro plan, annual billing",
  "customerEmail": "buyer@example.com",
  "customerName": "Ada Lovelace",
  "customerMetadata": {
    "userId": 4471
  },
  "metadata": {
    "internalRef": "sub_2026_08_pro"
  },
  "returnUrl": "https://merchant.example.com/checkout/success",
  "cancelUrl": "https://merchant.example.com/checkout/cancel",
  "expiresInMinutes": 60
}

Response Parameters

Field	Type	Example
`id`	string	"clyv3n8x40001qh7m2k9d5b1t"
`referenceId`	string	"INV-260826-041C"
`orderId`	string	"order-8814"
`description`	string	"Pro plan, annual billing"
`amount`	string	"12500"
`currency`	string	"USD"
`status`	string	"OPEN"
`customerEmail`	string	"buyer@example.com"
`customerName`	string	"Ada Lovelace"
`customerMetadata`	object	{…}
`customerMetadata.userId`	integer	4471
`metadata`	object	{…}
`metadata.internalRef`	string	"sub_2026_08_pro"
`returnUrl`	string	"https://merchant.example.com/checkout/su…
`cancelUrl`	string	"https://merchant.example.com/checkout/ca…
`expiresAt`	string	"2026-08-26T10:14:22.481Z"
`viewedAt`	null	null
`paidAt`	null	null
`cancelledAt`	null	null
`createdAt`	string	"2026-08-26T09:14:22.481Z"

Response Example

JSONResponse

{
  "success": true,
  "data": {
    "id": "clyv3n8x40001qh7m2k9d5b1t",
    "referenceId": "INV-260826-041C",
    "orderId": "order-8814",
    "description": "Pro plan, annual billing",
    "amount": "12500",
    "currency": "USD",
    "status": "OPEN",
    "customerEmail": "buyer@example.com",
    "customerName": "Ada Lovelace",
    "customerMetadata": {
      "userId": 4471
    },
    "metadata": {
      "internalRef": "sub_2026_08_pro"
    },
    "returnUrl": "https://merchant.example.com/checkout/success",
    "cancelUrl": "https://merchant.example.com/checkout/cancel",
    "expiresAt": "2026-08-26T10:14:22.481Z",
    "viewedAt": null,
    "paidAt": null,
    "cancelledAt": null,
    "createdAt": "2026-08-26T09:14:22.481Z"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Error shape

JSONError

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMockapi2.havala.io

POSThttps://api2.havala.io

Get Invoice→