Developer hub

The Developer hub centralises everything a developer needs to extend Mercentia — API keys, webhooks, the app submissions queue, and links to the SDK + CLI docs. Find it under Settings → Developer in the sidebar.

Surfaces

API Keys — issue, rotate, and revoke keys. Each key carries a typed scope set drawn from @mercentia/shared/scopes.
Webhooks — register endpoints to receive event payloads (orders, products, customers, refunds). Every payload is signed with HMAC-SHA256 using your registered secret.
OpenAPI spec — link to the rendered OpenAPI document; the spec is the source of truth for the SDK.
SDK — install instructions for @mercentia/sdk (typed TypeScript client) and links to language-specific community ports.
CLI — mercentia command reference (see CLI docs).
App submissions — your apps queued for marketplace review (see App marketplace).

API keys

Keys are prefixed sf_live_ (production) or sf_test_ (test mode). The token is shown once at creation — Mercentia stores only a SHA-256 hash. Lost a key? Issue a new one and revoke the old.

Scopes follow a verb:resource shape:

read:catalog
read:orders
write:customers
admin:webhooks

Each gateway route declares the scopes it accepts. Calls with insufficient scope return 403 with a structured error specifying the missing scope.

Webhooks

Each webhook subscription stores:

The HTTPS endpoint URL.
A subscription secret (mint and copy on creation).
The list of event types to forward.

Signature header:

mercentia-signature: t=1717000000,v1=<hex-hmac-sha256>

Verify with the standard “compare against t.body” scheme. Webhooks retry on non-2xx for up to 24h with exponential backoff; after that they’re parked in the Webhooks → Failed deliveries view.

Test mode

A key prefixed sf_test_ reads from the same database but is filtered to test-mode rows (orders / customers / payments that were created against the Stripe test key). Use this to wire up integrations end-to-end before flipping to live.