Sub-accounts and billing

Integrate Hellio without buying credit yourself. Create one sub-account per client so each buys and spends their own SMS credit inside your application, registers its own Sender IDs, and tops up by Paystack, all over the API.

How it fits together

One parent account, many self-funded clients.

1. You authenticate with your own API token (all scopes).
2. You create a sub-account per client in isolated balance mode, so it funds and spends from its own wallet.
3. You issue that sub-account its own API token and use it for that client's traffic.
4. The sub-account registers a Sender ID (with its business certificate) and polls the approval status.
5. The sub-account tops up its wallet with Paystack; the wallet is auto-credited on payment.
6. The sub-account sends promotional SMS with its approved Sender ID, billed to its own wallet.

When a sub-account's wallet falls below the low-credit threshold, Hellio emails it automatically (platform-funded), so you don't have to build balance monitoring.

1. Create a sub-account

Isolated mode = the client buys their own credit.

Requires the sub-accounts scope. Use balance_mode: "isolated" so the sub-account has its own wallet. (Use "shared" with an allocation if you'd rather fund clients from your own wallet.)

curl -X POST https://api.helliomessaging.com/v1/sub-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Ltd",
    "email": "ops@acme.example",
    "password": "a-strong-password",
    "balance_mode": "isolated"
  }'

The response includes the sub-account id. Sub-accounts you create are pre-verified, so they're usable immediately.

Shared mode: fund a client from your own wallet

Prefer to fund clients yourself instead of having them buy their own credit? Use balance_mode: "shared" and pass an allocation (GHS) to move from your wallet into the new sub-account's wallet on creation. The allocation cannot exceed your available balance.

curl -X POST https://api.helliomessaging.com/v1/sub-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Ltd",
    "email": "ops@acme.example",
    "password": "a-strong-password",
    "balance_mode": "shared",
    "allocation": 50
  }'

2. Issue the sub-account an API token

So each client authenticates independently. The token is returned once, store it securely.

curl -X POST https://api.helliomessaging.com/v1/sub-accounts/SUB_ACCOUNT_ID/tokens \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme production" }'

Use the returned token as the bearer token for that client's requests below.

3. Register a Sender ID

With the required business certificate.

Requires the sender-ids scope. Send as multipart/form-data with the certificate file (pdf, jpg or png). Scam wording is rejected; a protected-brand match is accepted but flagged. Approval is manual and usually completes within 24 hours.

curl -X POST https://api.helliomessaging.com/v1/sender-ids \
  -H "Authorization: Bearer SUB_ACCOUNT_TOKEN" \
  -F "sender_id=ACME" \
  -F "certificate=@/path/to/business-cert.pdf"

Poll the status until it is approved:

curl https://api.helliomessaging.com/v1/sender-ids \
  -H "Authorization: Bearer SUB_ACCOUNT_TOKEN"

Each Sender ID has a status of pending, approved or rejected (with a reason when rejected).

4. Top up by Paystack

Return a checkout URL; the wallet auto-credits.

Requires the payments scope. Start a top-up and open the returned authorization_url in the client's browser. This works for any account, not just sub-accounts: a direct customer tops up its own wallet the same way, using its own token.

curl -X POST https://api.helliomessaging.com/v1/payments \
  -H "Authorization: Bearer SUB_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100 }'

{
  "data": {
    "reference": "ps_abcdef0123456789",
    "authorization_url": "https://checkout.paystack.com/abcdef",
    "amount": "100",
    "status": "pending"
  }
}

When the payment succeeds, the sub-account's wallet is credited automatically, Hellio handles the Paystack confirmation for you, so there is nothing to configure on your side. Poll GET /payments/{reference} to see when a payment moves to success.

curl https://api.helliomessaging.com/v1/payments/PAYMENT_REFERENCE \
  -H "Authorization: Bearer SUB_ACCOUNT_TOKEN"

5. Send messages

Once the Sender ID is approved and the wallet is funded, the sub-account sends with its own token and Sender ID, billed to its own wallet. See the API reference for POST /sms/send.

Low-balance alerts

Hellio emails a sub-account automatically when its wallet drops below the low-credit threshold, and again once it recovers. These notices are platform-funded, so a client with no credit left still receives them. No integration required.

Scopes