What is Billium
A non-custodial crypto payment processor for developers.
Billium is a non-custodial crypto payment processor. It lets your application create payment invoices, monitor blockchain transactions in real time, and receive webhook notifications when payments arrive — without ever holding your users' funds.
How it works
Create an invoice — Your server calls POST /api/v1/merchants/merchant/{merchantId}/invoices with the expected amount, currency, and optional customer fields. Billium returns an invoice ID and a hosted checkout URL for the customer to pay.
Customer pays — The customer picks a cryptocurrency on the checkout page and sends the required amount to the assigned address. Billium monitors the address on-chain in real time.
Confirmations accumulate — Once the transaction is detected, Billium waits for the required number of block confirmations before marking it as confirmed.
Webhook delivered — Billium sends a signed webhook to your server for every status change — invoice.paid, invoice.underpaid, invoice.overpaid, invoice.cancelled, etc. — so you can fulfill the order and update your database.
Core concepts
Merchant
The account that owns invoices, wallets, API keys, and webhooks. Every resource in Billium is scoped to a merchant ID.
Invoice
The payment request. Holds the expected amount, the assigned crypto address, and the current status.
Payment
The on-chain transaction matched to an invoice. Tracks confirmations, received amount, and platform fee.
Webhook
An HTTP POST sent to your server on every invoice status change. Signed with HMAC-SHA256 so you can verify authenticity.
Wallet
Your configured payout address. Either a direct address (shared across invoices) or an xpub key (unique address per invoice).
A single user account can belong to multiple merchants, with a different role (OWNER / ADMIN / MEMBER / VIEWER) on each. Every API call is scoped to a specific merchantId, so pick the right one when you issue API keys or call the REST API. See Authentication for the role matrix.
Invoice lifecycle
An invoice starts in AWAITING_PAYMENT. When Billium's blockchain monitors see a matching transaction, it moves to PENDING_CONFIRMATION. From there it settles into one of the terminal states based on what actually arrived on-chain:
| From | To | When |
|---|---|---|
AWAITING_PAYMENT | PENDING_CONFIRMATION | Transaction detected on-chain |
AWAITING_PAYMENT | EXPIRED | Deadline passed without payment |
AWAITING_PAYMENT | CANCELLED | Merchant cancelled the invoice |
PENDING_CONFIRMATION | PAID | Confirmations reached, exact amount |
PENDING_CONFIRMATION | UNDERPAID | Confirmed, but less than expected |
PENDING_CONFIRMATION | OVERPAID | Confirmed, but more than expected |
PENDING_CONFIRMATION | EXPIRED | Never confirmed in time (48h stuck) |
Terminal states — PAID, UNDERPAID, OVERPAID, EXPIRED, CANCELLED — cannot transition further.
Next steps
Quickstart
Create your first invoice and handle your first webhook in under 5 minutes.
Concepts
Accounts, wallets, networks, payment matching, and fees — the mental model behind the API.
Authentication
Use your API key to call the REST API.
Node.js SDK
Install @billium/node to create invoices and verify webhooks.
Webhooks
Event catalog and HMAC-SHA256 signature verification.