Get Invoice

GET/api/v1/invoices/{id}Core

Fetch one invoice by CUID, scoped to the merchant point behind your API key. This is the only invoice route that includes the payments relation: every payment ever opened against the invoice, newest attempts included, each with its leased deposit address.

Authentication

Signature Pattern

HMAC-SHA256(apiSecret, "{t}\nGET\n/api/v1/invoices/{id}\n{sha256(\"\")}")

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.

Request Parameters

Name	Type	Required	Description
`id`	string	Required	Path parameter — invoice CUID returned by create. Not the referenceId.

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	"PAYMENT_PENDING"
`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`	string	"2026-08-26T09:16:04.220Z"
`paidAt`	null	null
`cancelledAt`	null	null
`createdAt`	string	"2026-08-26T09:14:22.481Z"
`payments`	array	[…]
`payments[].id`	string	"clyv4p1c70003qh7m8w2r6z9f"
`payments[].referenceId`	string	"PAY-260826-118A"
`payments[].status`	string	"PENDING"
`payments[].blockchain`	string	"ethereum"
`payments[].currency`	string	"USDT"
`payments[].amount`	string	"12500"
`payments[].receivedAmount`	string	"0"
`payments[].address`	string	"0x7Ae2d4C1f83B90e5A6c7D218Ff43b9C0E15d8a72"
`payments[].createdAt`	string	"2026-08-26T09:14:26.902Z"

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": "PAYMENT_PENDING",
    "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": "2026-08-26T09:16:04.220Z",
    "paidAt": null,
    "cancelledAt": null,
    "createdAt": "2026-08-26T09:14:22.481Z",
    "payments": [
      {
        "id": "clyv4p1c70003qh7m8w2r6z9f",
        "referenceId": "PAY-260826-118A",
        "status": "PENDING",
        "blockchain": "ethereum",
        "currency": "USDT",
        "amount": "12500",
        "receivedAmount": "0",
        "address": "0x7Ae2d4C1f83B90e5A6c7D218Ff43b9C0E15d8a72",
        "createdAt": "2026-08-26T09:14:26.902Z"
      }
    ]
  },
  "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

GEThttps://api2.havala.io

← Create Invoice Get Invoice Status→