Payouts

Initiate Payout

POST /v1/payouts

Initiates a payout transfer to a beneficiary. Wallet balance is validated and debited during processing.

Processing flow

1. Payout record created
2. Wallet validation and debit (reserves the funds atomically)
3. Webhook triggered (if configured)
4. Bank transfer dispatched
5. Final status persisted; second webhook fired on terminal state

A 200 response only confirms the payout was accepted for processing (status 4 — InProgress). Final status arrives via webhook or you can poll with the Get Payout endpoint.

Request body

Field	Type	Required	Description
beneficiaryId	UUID	yes	Beneficiary must exist, be active, and belong to the authenticated business.
amount	string	yes	Payout amount as a decimal string, e.g. "1000.00". Must respect your business's per-txn and per-rail limits.
transactionType	string	yes	Rail. One of I (IMPS), N (NEFT), R (RTGS), S (SELF).

Sample request body

{
  "beneficiaryId": "123e4567-e89b-12d3-a456-426614174001",
  "amount": "1000.00",
  "transactionType": "N"
}

Responses

200 Payout accepted and currently in progress

{
  "status": 200,
  "data": {
    "payoutTransactionId": "ca4bac52-2800-11f1-8a8e-0a0c26167b3f",
    "transactionId": "BMPT2026032500001",
    "amount": 100,
    "status": 4,
    "commissionAmount": 0.75,
    "commissionGSTAmount": 0.14
  },
  "message": "Payout initiated and is being processed",
  "meta": null
}

500 Payout failed at bank

{
  "status": 500,
  "data": {
    "payoutTransactionId": "ca4bac52-2800-11f1-8a8e-0a0c26167b3f",
    "transactionId": "BMPT2026032500001",
    "amount": 100,
    "status": 12,
    "commissionAmount": 0.75,
    "commissionGSTAmount": 0.14
  },
  "message": "Payout failed",
  "meta": null
}

Transaction types

Code	Rail
I	IMPS
N	NEFT
R	RTGS
S	SELF (intra-bank)

Payout status codes

Code	Status	Notes
2	Initiated	Record created, pre-validation.
3	Acknowledged	Picked up by the bank queue.
4	InProgress	Dispatched to the bank rail, awaiting settlement.
11	Successful	Funds transferred.
12	Failed	Bank rejected or reversed.

---

Get Payout Transaction

GET /v1/payouts/:payoutTransactionId

Fetches the full payout record — beneficiary, bank reference, commission breakdown, response code/message, and current status.

Path parameters

Name	Type	Required	Description
payoutTransactionId	UUID	yes	The internal payout id returned by POST /v1/payouts.

Sample response (200)

{
  "status": 200,
  "data": [
    {
      "payoutTransactionId": "ca4bac52-2800-11f1-8a8e-0a0c26167b3f",
      "transactionId": "BMPT2026032500001",
      "businessId": "123e4567-e89b-12d3-a456-426614174000",
      "merchantId": "123e4567-e89b-12d3-a456-426614174999",
      "vendorId": "123e4567-e89b-12d3-a456-426614174001",
      "vendorCode": "BMBN2026032500001",
      "name": "Ravi Traders",
      "ifsc": "HDFC0001234",
      "accountNumber": "123456789012",
      "transactionType": "N",
      "transactionTypeName": "NEFT",
      "amount": 1000,
      "commissionAmount": 0.75,
      "commissionGSTAmount": 0.14,
      "status": 11,
      "responseCode": "100",
      "responseMessage": "Transfer completed",
      "transactionReference": "BANKREF12345",
      "createdDate": "2026-03-25T10:30:00Z",
      "updatedDate": "2026-03-25T10:31:00Z"
    }
  ],
  "message": null,
  "meta": null
}

The data field is an array containing the payout record (preserved from the legacy v1 contract). If no record is found, the API returns 404 with data: null.

---

End-to-end example (TypeScript)

import axios from 'axios';
import crypto from 'crypto';
 
const API_KEY = process.env.BRIDG_API_KEY!;
const API_SECRET = process.env.BRIDG_API_SECRET!;
const BASE_URL = 'https://api-beta.bridg.money'; // or https://api.n3v.in for UAT
 
async function initiatePayout() {
  const method = 'POST';
  const path = '/v1/payouts';
  const body = {
    beneficiaryId: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
    amount: '100.00',
    transactionType: 'I',
  };
 
  const timestamp = Date.now().toString();
  const payload = JSON.stringify(body);
  const canonical = [method, path, timestamp, payload].join('|');
 
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(canonical)
    .digest('hex');
 
  const res = await axios.post(BASE_URL + path, body, {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
      'x-timestamp': timestamp,
      'x-signature': signature,
    },
  });
 
  console.log(res.data);
}
 
initiatePayout();