POST /v1/invoices

Create a new invoice. Returns the full invoice object including the hosted checkout payment address.

Test mode is a flag on the key

The invoice's environment is inherited from the key you authenticate with. Send an hm_test_* key → test invoice (fast-forwardable via the sandbox, TEST badge on checkout). Send an hm_live_* key → live invoice (real on-chain payment required). You never need to pass an environment field; HelaMesh infers it from the key. See Test vs live for the full rules.

Headers

x-api-key: hm_test_…   # or hm_live_…
content-type: application/json

Body

Field	Type	Required	Notes
amount	number	yes	Decimal USDT, up to 18 decimal places depending on chain
network	string	no	"TRON" (default) or "BSC". If BSC, client must have bscAddress set.
metadata	object	no	Free-form JSON, returned in webhook

Example

node.js

const res = await fetch('https://api.helamesh.com/v1/invoices', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HELAMESH_API_KEY,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    amount: 25.00,
    network: 'BSC', // optional, defaults to TRON
    metadata: { orderId: '1234', customer: 'alice@example.com' },
  }),
});

const invoice = await res.json();
console.log('Pay here:', `https://pay.helamesh.com/pay/${invoice.id}`);

Response

200 OK

{
  "id": "65f8a1b2c3d4e5f6a7b8c9d0",
  "amount": "25.000000",
  "token": "USDT",
  "network": "BSC",
  "status": "PENDING",
  "paymentAddress": "0x4b0897b0513fdc7c541b6d9d7e929c4e5364d2db",
  "expiresAt": "2026-04-10T18:30:00.000Z",
  "txHash": null,
  "confirmations": 0,
  "metadata": { "orderId": "1234", "customer": "alice@example.com" },
  "simulated": false,
  "environment": "test",
  "publishableKey": "pk_test_…"
}

Response fields

Field	Type	Notes
id	string	HelaMesh invoice ID — store this on your order
amount	string	Normalised decimal string (always 6 fractional digits for TRON, 18 for BSC)
token	string	Always "USDT" in v1
network	string	"TRON" or "BSC" — the chain this invoice will be paid on
status	string	State machine position: PENDING / DETECTED / CONFIRMING / CONFIRMED / COMPLETED / EXPIRED
paymentAddress	string	Where the customer sends USDT. Format matches the network (TRON base58, BSC hex).
expiresAt	ISO8601	Invoice TTL — defaults to 30 minutes from creation
txHash	string|null	Populates once the payment lands on chain
confirmations	number	Advances as the payment accumulates confirmations
metadata	object|null	Whatever you passed in body.metadata, echoed back
simulated	boolean	true if this invoice was fast-forwarded by the sandbox. Never true for live invoices.
environment	string	"test" or "live" — matches the key you authenticated with
publishableKey	string	The owning client's pk, so browser code can mount the embed without a second fetch

Multi-chain support

When you omit network, HelaMesh defaults to TRON for backward compatibility. To accept BEP20 USDT on BNB Smart Chain, either pass "network": "BSC" explicitly, or use the chain picker to let your customer choose.