Authentication

Primary integration: POST /v2/payment-sessions and GET /v2/payment-sessions/:id use the project secret key, which fixes project and Test/Live context. See API v2. Public checkout uses X-Checkout-Token, never the project secret. Management API is a separate first-party JWT surface. Rotate exposed credentials; old uncompromised webhook secrets may still be needed for existing delivery snapshots.

BramaPay has two merchant authentication surfaces.

Integration API key

Use the secret project key for server-to-server invoice operations:

X-Api-Key: YOUR_API_KEY

Authorization: Bearer sk_live_... is also accepted. The integration uses sk_live_... or sk_test_... secret keys for its project and mode. The key selects its project. Store it in a server-side secret manager; never expose it in browser code, mobile apps, source control, URLs, or logs.

Dashboard JWT

Project, wallet, key, webhook, billing, treasury, and referral management endpoints use the authenticated Dashboard session: Bearer access token plus an HttpOnly refresh cookie. Project-scoped dashboard requests also send X-Project-Id.

These JWT endpoints support the first-party merchant Dashboard. A standalone commerce backend should normally use the documented /v2/payment-sessions or existing /v1/invoices contract rather than reproducing Dashboard session management.