POST /v1/payment-links

Create a payment link. Returns a shareable URL and a unique address per enabled crypto rail. The customer opens the link, picks how they want to pay (M-Pesa, TRON, BSC), and pays — your webhook fires on confirmation.

Environment is inherited from your API key

Pass an hm_test_* key → test link (sandbox STK push, simulated on-chain). Pass an hm_live_* key → live link (real M-Pesa charges, real on-chain). Never pass an environment field — HelaMesh infers it from the key.

Headers

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

Body

Field	Type	Required	Notes
usdtAmount	string	yes*	Decimal USDT amount, e.g. "25.00". Required if not M-Pesa only.
mpesaAmount	number	no	KES amount. If omitted and MPESA rail is enabled, HelaMesh converts from usdtAmount using the live rate.
enabledRails	string[]	yes	One or more of "MPESA", "USDT_TRON", "USDT_BSC"
description	string	no	Shown to the customer on the checkout page
merchantRef	string	no	Your own reference ID — returned in webhooks
metadata	object	no	Free-form JSON, returned in webhooks unchanged
expiresInMinutes	number	no	Link TTL. Defaults to 1440 (24 hours).

Example

node.js

const res = await fetch('https://api.helamesh.com/v1/payment-links', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HELAMESH_API_KEY,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    usdtAmount: '100',
    enabledRails: ['MPESA', 'USDT_TRON', 'USDT_BSC'],
    description: 'Order #1042 — Web design deposit',
    merchantRef: 'order_1042',
    metadata: { customerId: 'cus_abc123' },
  }),
});

const link = await res.json();
// Send link.checkoutUrl to your customer
console.log('Pay here:', link.checkoutUrl);

Response

201 Created

{
  "id": "6a20334a21638503775afa39",
  "status": "PENDING",
  "environment": "test",
  "usdtAmount": "100",
  "mpesaAmount": 13421,
  "enabledRails": ["MPESA", "USDT_TRON", "USDT_BSC"],
  "tronAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "bscAddress": "0x4b0897b0513fdc7c541b6d9d7e929c4e5364d2db",
  "mpesaShortcode": "174379",
  "description": "Order #1042 — Web design deposit",
  "merchantRef": "order_1042",
  "metadata": { "customerId": "cus_abc123" },
  "expiresAt": "2026-06-04T12:00:00.000Z",
  "createdAt": "2026-06-03T12:00:00.000Z",
  "checkoutUrl": "https://pay.helamesh.com/p/6a20334a21638503775afa39"
}

Response fields

Field	Type	Notes
id	string	Payment link ID — store this on your order
status	string	PENDING | PROCESSING | CONFIRMED | EXPIRED | CANCELLED
environment	string	"test" or "live"
usdtAmount	string	Normalised USDT decimal string
mpesaAmount	number | null	KES amount shown to customer. Null if M-Pesa rail not enabled.
enabledRails	string[]	Rails available on this link
tronAddress	string | null	Unique TRC20 receiving address for this link. Null if USDT_TRON not enabled.
bscAddress	string | null	Unique BEP20 receiving address for this link. Null if USDT_BSC not enabled.
mpesaShortcode	string | null	Connected M-Pesa paybill number. Null if MPESA not enabled.
description	string | null	Description shown on checkout
merchantRef	string | null	Your reference, echoed in webhooks
metadata	object | null	Your metadata, echoed in webhooks
expiresAt	ISO8601	When the link expires
checkoutUrl	string	The URL to send your customer

GET /v1/payment-links/:id

Fetch a single payment link by ID. Requires your secret API key.

curl https://api.helamesh.com/v1/payment-links/6a20334a21638503775afa39 \
  -H "x-api-key: hm_test_..."

Response shape is identical to the create response above, plus confirmedRail, confirmedAt, externalId, and payer fields which populate on confirmation:

Field	Type	Notes
confirmedRail	string | null	Which rail the customer paid with: "MPESA", "USDT_TRON", or "USDT_BSC"
confirmedAt	ISO8601 | null	When payment was confirmed
externalId	string | null	M-Pesa receipt code or on-chain tx hash
payer	string | null	M-Pesa phone number or on-chain sender address

GET /v1/payment-links

List all payment links for your store. Requires your secret API key.

curl "https://api.helamesh.com/v1/payment-links?status=PENDING&limit=20" \
  -H "x-api-key: hm_test_..."

Query params

Param	Default	Notes
status	—	Filter by status
limit	20	Max results per page (1–100)
page	1	Page number