Wallet and Balance

Balance Check API

GET /v1/wallet

Returns the authenticated merchant's current wallet balance snapshot.

Use this endpoint before creating payouts when your system needs to confirm that enough payout-usable balance is available. The value to compare against a new payout is spendablePaise, not availablePaise.

This endpoint is merchant-scoped. It only returns the wallet for the business linked to the API key used to sign the request.

Signing

GET /v1/wallet does not use query parameters, so it can be signed with either legacy HMAC v1 headers or HMAC v2 headers. For this no-query balance check, HMAC v1 is the shortest integration path.

Quickstart: HMAC v1

Sign exactly this canonical string:

GET|/v1/wallet|<timestamp_ms>|

timestamp_ms must be a 13-digit Unix epoch timestamp in milliseconds. Sign only the path /v1/wallet, not the full URL https://api.bridg.money/v1/wallet. The final pipe is intentional because GET requests have an empty body.

Send the normal API URL with these headers:

GET https://api.bridg.money/v1/wallet
x-api-key: <public_key>
x-timestamp: <timestamp_ms>
x-signature: <hmac_sha256_hex_signature>

The canonical string is only the input to HMAC-SHA256. Do not send it as the request URL or request body.

HMAC v2 option

If your integration already uses HMAC v2, sign this canonical string with an empty-body SHA-256 hash:

GET|api.bridg.money|/v1/wallet|<api-key>|<timestamp>|<nonce>|e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Also send x-bridg-sig-version: 2 and a fresh x-nonce for every request. Do not reuse a v2 nonce.

See API Keys and IP Whitelist and Canonical Request Format.

Sample response

{
  "status": 200,
  "data": {
    "businessId": "123e4567-e89b-12d3-a456-426614174000",
    "businessCode": "BMB2026050600001",
    "businessName": "Example Merchant Private Limited",
    "availablePaise": "100000000",
    "reservePaise": "10000000",
    "spendablePaise": "89990000",
    "reservePercent": 10,
    "minBalancePaise": "10000",
    "walletProvisioned": true
  },
  "message": null,
  "meta": null
}

Field meanings

Field	Meaning
availablePaise	Raw wallet ledger balance in paise.
reservePaise	Rolling reserve hold-back in paise. This is computed from the configured reserve percentage.
spendablePaise	Payout-usable balance in paise after reserve and minimum-balance rules. Use this for payout checks.
reservePercent	Effective rolling reserve percentage for the merchant.
minBalancePaise	Minimum wallet balance that must remain after payouts.
walletProvisioned	true when the wallet ledger account exists. If false, the business is not ready for live wallet operations yet.

All money fields are returned in paise as strings. Divide by 100 to show INR amounts in your system.

Common failures

HTTP status	Meaning
401	Missing, expired, replayed, or invalid signed request headers.
403	API access is disabled for the business, usually pending KYC or operational review.
404	Business linked to the API key was not found.

If a balance-check request returns 401, check these first:

• The timestamp is Unix milliseconds, not seconds.
• The HMAC v1 string signs /v1/wallet, not the full URL.
• The request includes x-api-key, x-timestamp, and x-signature.
• HMAC v2 requests include x-bridg-sig-version: 2.
• HMAC v2 requests use a fresh x-nonce for every call.
• The signing key is the secret key shown when the API key was created or rotated.

Wallet Funding Details

GET /v1/wallet/bank-details

Returns the nodal bank account details a merchant can use when topping up the wallet. This endpoint uses the same signed authentication as the balance check.

Wallet Transactions

GET /v1/wallet/transactions

Returns wallet movement rows for the authenticated merchant, including running balances and a summary for the selected window.

This endpoint uses query parameters, so sign it with HMAC v2. Keep the URL as /v1/wallet/transactions; do not call /v2/wallet/transactions.

Query parameters

Name	Type	Default	Description
limit	number	50	Page size, clamped from 1 to 200.
offset	number	0	Zero-based offset.
search	string	none	Search wallet movement fields and metadata.
since	ISO datetime	none	Include wallet movements created at or after this time.
until	ISO datetime	none	Include wallet movements created before this time.

Wallet Activity Export

GET /v1/wallet/transactions/export

Exports wallet movement history for the authenticated merchant.

Query parameters

Name	Type	Default	Description
format	csv, xls, or pdf	csv	Export file format.
search	string	none	Search wallet movement fields and metadata.
since	ISO datetime	none	Include wallet movements created at or after this time.
until	ISO datetime	none	Include wallet movements created before this time.

Exports are capped at 50,000 rows. Narrow the date range or search when the export is too large.