Merchant Onboarding

Use this checklist before creating live payouts. The API will reject signed server-to-server calls while API access is disabled, even if the merchant can still log in to the portal.

Environment URLs

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

Production onboarding should use the production portal and production API base URL. Testing/UAT links are for controlled validation only.

Onboarding flow

1. Sign in to the merchant portal.
2. Complete Business Details.
3. Add the Banking Details used for settlement and wallet operations.
4. Upload the required Business Documents.
5. Wait for KYC review and API access approval.
6. Generate API keys, configure IP whitelist, and configure webhooks.
7. Run test payouts in Beta/UAT, then switch the same integration to production credentials and production base URL.

Business details

The onboarding form expects:

Field	Notes
Legal Business Name	Editable during onboarding. Should match KYC documents and settlement account.
Business Description	Minimum 100 characters. Explain the business, products/services, and customer type.
Business Type	Private/Public Limited, Partnership/LLP, Proprietorship, or Trust/Society/NGO.
Business Email	Operational email for onboarding and communication.
Phone Number	Indian mobile number.
Business PAN	AAAAA9999A format.
GSTIN	15-character GSTIN. Required in the portal form; upload GST certificate where applicable.
Website URL	Public HTTPS URL.
Refund/Cancellation Policy URL	Public HTTPS URL.
Registered/operational address	Address line, city, state, and postal code.

Banking details

Add the merchant settlement account:

Field	Notes
Account Holder Name	Should match the legal entity name on the account.
Account Number	Settlement account number.
IFSC	11-character IFSC in AAAA0XXXXXX format.

KYC documents

Documents must be signed and self-attested by Directors/Authorised Signatory where applicable. The portal shows the exact slots for the selected business type; use the matrix below as the preparation checklist.

Document	Private/Public Ltd	Partnership/LLP	Proprietorship	Trust/Society/NGO
Permanent Account Number (PAN)	Required	Required	Required	Required
Business Address Proof	Required	Required	Required	Required
Bank Account Proof	Required	Required	Required	Required
Bank Statement	Required	Required	Required	Required
PAN and Aadhaar of all Directors/Owners/Authorised Persons	Required	Required	Required	Required
Certificate of Incorporation (COI)	Required	-	-	-
Memorandum of Association (MOA)	Required	-	-	-
Articles of Association (AOA)	Required	-	-	-
CIN / MCA Registration Details	Required	-	-	-
Board Resolution / Authorisation	Required	-	-	Required
Partnership Deed / LLP Agreement	-	Required	-	-
Authorisation Document / Resolution	-	Required	-	Required
Registration Certificate / Trust Deed / License	-	-	-	Required
GST Certificate	Optional	Optional	Optional	Optional
Udyam / MSME Registration Certificate	-	-	Optional	-

Approval and API access

KYC review has four business states: unstarted, in_review, approved, and rejected. API access is separate: enabled or disabled.

If API access is disabled, signed API requests return 403 with kyc_required. The merchant portal still works so the merchant can fix KYC or configuration gaps.

Integration setup

Complete these settings before live traffic:

Setting	Where	Requirement
API key and signing key	Settings -> API Keys	Store the signing key immediately; it is shown once.
IP whitelist	Settings -> IP Whitelist	Add production server egress IPs. Empty whitelist means the key is accepted from any source IP.
Webhook URL	Settings -> Webhooks	HTTPS endpoint that returns 2xx quickly. Store the webhook secret immediately.

See API Keys and IP Whitelist, Authentication Headers, and Webhooks.

First payout test

1. Create a beneficiary. Use bank account + IFSC for bank rails, or vpa for UPI.
2. Initiate a small payout with a unique Idempotency-Key.
3. Read the response and store payoutTransactionId and transactionId.
4. Poll GET /v1/payouts/:payoutTransactionId or wait for the webhook.
5. Confirm terminal status:
   • 11 Successful includes the bank reference/UTR when available.
   • 12 Failed reverses the wallet reservation.
   • 3 or 4 means the payout is still pending/in progress.
6. Verify the webhook signature and dedupe by payoutWebhookId.

Go-live checklist

Before production traffic:

• KYC approved and API access enabled.
• Production API key active and signing key stored in a secret manager.
• Production server egress IPs whitelisted.
• Webhook URL saved, secret stored, and signature verifier tested.
• Test payout lifecycle verified in Beta/UAT.
• Client handles 409 idempotency/beneficiary conflicts without duplicate payouts.
• Client stores both transactionId and payoutTransactionId.
• Client stores utr / transactionReference from payout details and webhooks.