Developer docs

Authentication

All merchant endpoints under /api/public/v1 require a Bearer API key. Never embed keys in browsers or mobile apps.

Header format

HTTP

Authorization: Bearer hpay_live_<hex>

Key prefixes

hpay_test_… — free sandbox keys from Settings → API sandbox (no Business plan; up to 3 active)
hpay_live_… — production keys from Merchant → API keys (Business plan)

Storage

Keys are stored as SHA-256 hashes. The raw secret is shown once at creation. Rotate by creating a new key and revoking the old one.

Rate limits

Default 60 requests/minute per key (configurable up to 600). Responses include X-RateLimit-Limit and X-RateLimit-Remaining. Exceeding the limit returns 429 with Retry-After.

Plan gate

Sandbox keys are free for every signed-in account. Live keys and webhook endpoint creation require the Business plan (or legacy Merchant Growth / Enterprise). Upgrade under Plan.

OAuth user tokens

Marketplace-style integrations that need wallet access use hpay_usr_… tokens from the Connect flow — not merchant API keys. That path is documented in the repo API_REFERENCE.md.