Skip to main content

Quickstart

HelaMesh lets you accept M-Pesa and USDT (TRON · BSC) via a single payment link. One link, multiple rails — the customer picks how to pay at checkout. Your backend gets one webhook regardless of which rail they used.

Five minutes from signup to first payment:

  1. Create an account — set up your wallet and get a test API key.
  2. Create a payment link via the API.
  3. Share the checkoutUrl with your customer.
  4. Receive a payment_link.confirmed webhook when payment confirms.
What you need before going live
  • Crypto rails (TRON / BSC): Complete the wallet setup wizard in the dashboard. Your xpubs are registered automatically.
  • M-Pesa rail: Connect your Safaricom Daraja credentials in the dashboard or via API. See M-Pesa setup.
curl
curl -X POST https://api.helamesh.com/v1/payment-links \
  -H "x-api-key: hm_test_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "usdtAmount": "25",
    "enabledRails": ["MPESA", "USDT_TRON", "USDT_BSC"],
    "description": "Order #1234",
    "merchantRef": "order_1234",
    "metadata": { "orderId": "1234" }
  }'

Response:

201 Created
{
  "id": "6a20334a21638503775afa39",
  "status": "PENDING",
  "environment": "test",
  "usdtAmount": "25",
  "mpesaAmount": 3355,
  "enabledRails": ["MPESA", "USDT_TRON", "USDT_BSC"],
  "tronAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "bscAddress": "0x4b0897b0513fdc7c541b6d9d7e929c4e5364d2db",
  "mpesaShortcode": "174379",
  "description": "Order #1234",
  "merchantRef": "order_1234",
  "metadata": { "orderId": "1234" },
  "expiresAt": "2026-06-04T12:00:00.000Z",
  "checkoutUrl": "https://pay.helamesh.com/p/6a20334a21638503775afa39"
}

Send checkoutUrl to your customer. They'll see all enabled rails and pick one.

Test keys give test links

hm_test_* keys create test links with a yellow TEST badge. Use the sandbox STK push button in the dashboard to simulate an M-Pesa payment, or send a real transaction to the test addresses for crypto. Swap in hm_live_* to go live — everything else stays identical.

Handle the webhook​

server.js
app.post('/webhooks/helamesh', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify signature (see Webhooks → Signing)
  const event = JSON.parse(req.body.toString());

  if (event.event === 'payment_link.confirmed') {
    console.log('Paid via:', event.confirmedRail); // MPESA | USDT_TRON | USDT_BSC
    console.log('Receipt:', event.externalId);     // M-Pesa code or tx hash
    // Fulfil order using event.merchantRef
  }

  res.status(200).send('ok');
});

Next steps​