Quick Start

This guide covers the complete production integration. All API calls belong on your server; never expose a secret key in browser code.

Before you start

Item	Where to get it	Why it is required
Project	Dashboard → project selector	Isolates wallets, API keys, webhooks, and return URLs for one store
Payment wallet	Dashboard → Wallets	Receives customer funds directly
Secret API key	Dashboard → Developers → API Keys	Authenticates your server and selects the project
Return URLs	Dashboard → Settings	Returns the customer to your store after checkout
Webhook endpoint	Dashboard → Developers → Webhooks	Delivers signed payment events to your backend

Current production scope

Use USDT on TRON. Shasta testing requires a separate isolated BramaPay environment; never send valuable assets to a testnet address.

1. Finish project setup

Create a project

Create one project for the store or integration boundary you want to isolate.

Add a merchant wallet

Register a TRON address you control. Existing invoices retain their original destination if the default wallet later changes.

Create a secret API key

Copy the sk_live_... value when it is shown. BramaPay does not show it again.

Configure return URLs and webhook

Add exact allowed HTTPS domains, set success and cancel URLs, then add an active public HTTPS webhook endpoint. Save its signing secret and key ID.

The dashboard readiness checklist becomes complete when the project has both return URLs, an active webhook, a suitable wallet, an API key, and an active account.

2. Create an invoice

Call POST https://api.bramapay.com/v1/invoices from your backend. Persist one idempotency key per logical create attempt and reuse it when retrying the same request.

curl --request POST 'https://api.bramapay.com/v1/invoices' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Idempotency-Key: order-58391-attempt-1' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "149.99",
    "asset": "USDT",
    "network": "TRON",
    "externalId": "ORDER-58391"
  }'

Request fields

Field	Type	Required	Description
`amount`	decimal string	Yes	Positive token amount; no exponent, sign, or surrounding whitespace
`asset`	string	Yes	`USDT` for the current production flow
`network`	string	Yes	`TRON` for the current production flow
`externalId`	string	Yes	Your durable order/payment-attempt identifier, 1–200 characters

The API key selects the project. projectId, walletId, assetId, and return URL overrides are rejected on this endpoint.

Response

{
  "invoiceId": "7b9e8f31-3b0e-46ae-96f0-d3c47540db4b",
  "externalId": "ORDER-58391",
  "status": "PENDING",
  "checkoutUrl": "https://dashboard.bramapay.com/en/pay/7b9e8f31-3b0e-46ae-96f0-d3c47540db4b",
  "expiresAt": "2026-09-28T05:30:00.000Z"
}

Store invoiceId, externalId, and the idempotency key with your order. Open or redirect the customer to checkoutUrl.

Checkout shows the destination address and a separately copyable exact amount. The customer must send the displayed amount in one transaction on the displayed network. The QR code contains the address only.

4. Verify and fulfill

Your webhook handler must read the raw UTF-8 body, verify the webhook v2 signature, reject stale timestamps, and deduplicate X-Event-Id. For invoice.paid, require status === "PAID" and match both invoiceId and externalId to your stored order before fulfilling once.

You can also verify the current state from your server:

curl 'https://api.bramapay.com/v1/invoices/INVOICE_ID' \
  --header 'X-Api-Key: YOUR_API_KEY'

Never fulfill from a redirect

The success URL is browser navigation, not payment proof. A user can visit it directly, and it can arrive before a webhook. Fulfill only after a verified invoice.paid event and/or an authenticated invoice lookup returns PAID.

Production checklist

Store the API key and webhook secret in a server-side secret manager.
Reuse the same Idempotency-Key only for the exact same create request.
Keep amounts as decimal strings end to end.
Persist and display externalId so operators can match BramaPay invoices to store orders.
Return a fast 2xx from the webhook after durable processing.
Make fulfillment idempotent because webhook delivery is at least once.