Skip to content
BitMomo Developers
Test money only. BitMomo currently runs on test networks. Payments use testnet coins and no real money moves. Live keys are not available yet.

API keys and scopes

Every merchant API request is authenticated with an API key in the x-api-key header:

Terminal window
curl https://api.dev.bitmomo.app/api/v1/gateway/payments \
  -H "x-api-key: $BITMOMO_API_KEY"

A key belongs to one merchant account and one environment. The merchant and the environment always come from the key: you never send a merchant ID, and a request cannot reach another merchant’s data.

Key format

Section titled “Key format”
Prefix Environment
bm_test_ Test: testnet coins, no real money.
bm_live_ Live: not available yet.

A test key only sees test payments. When live payments open, a live key will only see live payments.

Scopes

Section titled “Scopes”

Each key carries one or more scopes. Every endpoint requires a specific scope; a key without it gets 403.

Scope Allows
payments:read Read payments, balances and payment links.
payments:write Create payments and payment links.
webhooks:read Read the webhook configuration.
webhooks:write Change the webhook configuration and rotate its secret.
payouts:write Request payouts of your available balance.

Scopes never imply each other. A checkout key with payments:write cannot change where your webhooks go or move money out. Give each part of your system only the scopes it needs:

  • Checkout server: payments:read and payments:write.
  • Webhook administration: webhooks:read and webhooks:write.
  • Treasury: payouts:write.

The API reference lists the required scope on every endpoint.

Creating and revoking keys

Section titled “Creating and revoking keys”

Create keys in the dashboard under Settings → API keys. Choose Read only (payments:read) or Read & write (payments:read and payments:write). The full key is shown once, when you create it. BitMomo stores only a hash, so a lost key cannot be recovered: create a new one and revoke the old one.

Revoke a key from the same page. Revocation takes effect on the next request.

Webhook-admin and payout keys are not offered in the dashboard yet. Configure webhooks in Settings → Webhooks instead (see Webhooks).

Keeping keys safe

Section titled “Keeping keys safe”
  • Use keys only from your server. Never ship them in browser code, mobile apps or public repositories.
  • Store them in a secret manager or environment variables, not in source code.
  • Use separate keys for separate services, so you can revoke one without stopping the others.
  • If a key may have leaked, revoke it immediately and create a replacement.