Accept MBITE Payments - MoonBite Merchants

Accept MoonBite Payments

Non-custodial invoicing: customers pay your own address, wallet to wallet. The server only observes the chain.

Self-Custody

Payments land directly on an address you control. MoonBite never holds coins, keys, or balances on your behalf.

No Platform Fee

There is no merchant fee. The only cost is the ordinary network transaction fee the payer attaches to their transaction.

Chain-Verified

An invoice is marked paid only when a new inbound payment of at least the invoiced amount is observed on chain above the balance snapshot taken when the invoice was raised.

Token-Gated

Registering returns a manage token once. Only that token can raise invoices against your address or read your ledger.

How It Works

Get a receive address from your own MoonBite wallet. Use a dedicated address for invoicing and do not spend from it while invoices are open.
Register once with POST /api/merchants. The response includes manage_token exactly once. Store it like a password; it is never shown again.
Create an invoice with POST /api/merchant/invoice, sending your merchant id and the token in the X-Merchant-Token header.
Show the customer the returned pay_uri or the QR at /api/merchant/invoice/<id>/qr.svg. They pay from their wallet.
Confirm payment by polling GET /api/merchant/invoice/<id> until status is paid, or sweep all open invoices with POST /api/merchant/invoices/poll.

Invoices expire after one hour if unpaid. While network hashrate is low, wait for a comfortable number of confirmations before releasing high-value goods.

1. Register a Merchant

POST /api/merchants
Content-Type: application/json

{
  "name": "Your Shop",
  "category": "goods",
  "mbite_address": "<your MoonBite receive address>",
  "url": "https://example.com",
  "blurb": "What you sell"
}

201 Created
{
  "status": "success",
  "merchant": {
    "id": "<merchant_id>",
    "name": "Your Shop",
    "mbite_address": "<your MoonBite receive address>",
    "manage_token": "<shown once, store it securely>"
  }
}

Categories: goods, services, food, digital, donation, other. The token is not recoverable; if it is lost, register again.

2. Create an Invoice

POST /api/merchant/invoice
Content-Type: application/json
X-Merchant-Token: <manage_token>

{
  "merchant_id": "<merchant_id>",
  "amount": "12.5",
  "memo": "Order 1042"
}

201 Created
{
  "status": "success",
  "invoice": {
    "id": "<invoice_id>",
    "address": "<your MoonBite receive address>",
    "amount": "12.5",
    "status": "pending",
    "seconds_left": 3600,
    "pay_uri": "moonbite:<address>?amount=12.5&label=Order%201042"
  }
}

The invoice is always raised against your registered address. Requests without a valid token, or naming any other address, are refused. Rate limit: 30 per minute per client.

3. Check Payment

GET /api/merchant/invoice/<invoice_id>

200 OK
{
  "status": "success",
  "invoice": {
    "id": "<invoice_id>",
    "status": "paid",
    "paid_units": 1250000000,
    "paid_at": 1760000000
  }
}

GET /api/merchant/invoice/<invoice_id>/qr.svg
image/svg+xml encoding the pay_uri

Status is one of pending, paid, expired. Anyone holding the invoice id may poll it, so share ids only with the paying customer. Each poll may trigger a chain scan; polls are rate-limited and share a global scan budget, so a 503 with Retry-After means try again shortly.

4. Ledger and Sweep (authenticated)

GET /api/merchant/invoices?merchant_id=<merchant_id>
X-Merchant-Token: <manage_token>

POST /api/merchant/invoices/poll
Content-Type: application/json
X-Merchant-Token: <manage_token>

{ "merchant_id": "<merchant_id>" }

200 OK
{ "status": "success", "checked": 3, "paid": ["..."], "expired": [], "addresses_scanned": 1 }

Send the token only in the header, never in the URL. Both calls return only your own merchant's invoices.