BridgPay Merchant API

BridgPay's merchant APIs use HMAC-SHA256 authentication to ensure request authenticity, payload integrity, replay-attack prevention, and response integrity.

API path vs signing version

All public merchant API endpoints currently use /v1/... paths.

v1 in the URL is the API path version. HMAC v1 and HMAC v2 are request signing versions used on those /v1/... paths.

There are no /v2/... merchant endpoints. For example, a list request should call:

GET /v1/payouts?limit=50&offset=0

and, because it has query parameters, it should be signed with HMAC v2 headers including x-bridg-sig-version: 2.

Endpoints and portals

Environment	Merchant portal	API base URL
Production	https://merchant.bridg.money	https://api.bridg.money
Testing/UAT	https://merchant-beta.bridg.money	https://api-beta.bridg.money

Public API surface

Method	Path	Purpose
POST	/v1/beneficiaries	Create a beneficiary
GET	/v1/beneficiaries	List/search beneficiaries
PATCH	/v1/beneficiaries/:beneficiaryId	Update a beneficiary
POST	/v1/beneficiaries/:beneficiaryId/reactivate	Reactivate an archived beneficiary
DELETE	/v1/beneficiaries/:beneficiaryId	Archive a beneficiary
GET	/v1/wallet	Check payout-usable wallet balance
GET	/v1/wallet/transactions	List wallet movements
POST	/v1/payouts	Initiate a payout
GET	/v1/payouts	List payouts
GET	/v1/payouts/:payoutTransactionId	Fetch a payout's current state
GET	/v1/payouts/:payoutTransactionId/status-events	Fetch the payout status timeline

List/search endpoints use query parameters and should be signed with HMAC v2. The URL still remains /v1/...; only the signing headers change. See API Keys and IP Whitelist.

Quick start

1. Complete merchant onboarding and ensure API access is enabled.
2. Generate an API key + signing key under Settings -> API Keys in the merchant portal. The signing key is shown once — store it in your secret manager immediately.
3. Configure production source IPs under Settings -> IP Whitelist.
4. Compute the HMAC signature over the canonical request string for every call. Use HMAC v2 for new integrations and for every request with query parameters. See Generate Signature.
5. Send the required auth headers on every signed request: x-api-key, x-timestamp, x-signature. See Authentication Headers. For v2, also send x-bridg-sig-version: 2 and x-nonce.
6. Check payout-usable wallet balance with GET /v1/wallet when your system needs a real-time balance check before creating payouts.
7. Receive payout status updates via webhook. See Webhooks.

Everything else - KYC, wallet operations, API keys, webhooks, IP whitelist, and merchant settings - happens inside the merchant portal.