Events & Payloads

Event identity

X-Event-Id is the stable logical event ID and is also copied to X-Idempotency-Key. X-Delivery-Id identifies the endpoint-specific delivery. Retries and manual redelivery keep the logical event identity.

payment_session.paid

Hosted v2 sessions use this event. The payload includes sessionId, invoiceId, attemptId, externalId, projectId, mode, paymentMode, status, amountUsd, currency, amountPaid, amountExpected, txHash and chain. Verify the signature and authoritative session status, then match the saved order/project/mode/pricing contract. Test events must not fulfill Live orders. Child invoices do not authorize a second fulfillment. See the quick start.

invoice.paid

This event applies to existing standalone v1 invoices. Its JSON body contains the canonical settlement fields:

{
  "invoiceId": "7b9e8f31-3b0e-46ae-96f0-d3c47540db4b",
  "externalId": "ORDER-58391",
  "userId": "MERCHANT_USER_ID",
  "status": "PAID",
  "amountPaid": "149.990001",
  "amountExpected": "149.990001",
  "txHash": "BLOCKCHAIN_TRANSACTION_HASH",
  "chain": "TRON"
}

After signature verification, require status === "PAID", match the stored invoiceId and externalId, and fulfill idempotently.

treasury.credited

Signals that an account-level treasury deposit credited the BramaPay service balance. It is not a customer payment and must not fulfill an order.

{
  "treasuryDepositId": "10000000-0000-4000-8000-000000000001",
  "userId": "MERCHANT_USER_ID",
  "amount": "25.00",
  "assetId": "ASSET_ID",
  "txHash": "BLOCKCHAIN_TRANSACTION_HASH",
  "chain": "TRON"
}

integration.test and webhook.test

Validates endpoint connectivity and signature handling. It never represents a payment. Route logic by the signed X-Event-Type; reject any conflict between expected event handling and body data.

Synthetic session-paid example

Illustrative fixture only, never payment instructions. Conditional buyer pricing adds pricingVersion/feePayer/pricing and project payable fields. networkKey and test depend on payment context. Verify the signed event type and authenticated session before fulfillment.

{
  "sessionId": "00000000-0000-4000-8000-000000000001",
  "invoiceId": "00000000-0000-4000-8000-000000000002",
  "attemptId": "00000000-0000-4000-8000-000000000002",
  "externalId": "order-demo-1042",
  "userId": "EXAMPLE_MERCHANT_USER",
  "projectId": "EXAMPLE_PROJECT",
  "mode": "TEST",
  "paymentMode": "TEST",
  "networkKey": "EXAMPLE_NETWORK_KEY",
  "test": true,
  "status": "PAID",
  "amountUsd": "25",
  "currency": "USD",
  "ratePolicy": "STABLECOIN_PAR_1_V1",
  "asset": "USDT",
  "amountPaid": "25.000001",
  "amountExpected": "25.000001",
  "txHash": "EXAMPLE_NOT_A_TRANSACTION_HASH",
  "chain": "TRON"
}