Payouts

Integration Map

• POST /v1/payouts initiates a new payout to an active bank or UPI beneficiary.
• GET /v1/payouts lists recent payouts or searches across all dates.
• GET /v1/payouts/:payoutTransactionId fetches the current state and bank reference for one payout.
• GET /v1/payouts/:payoutTransactionId/status-events shows the payout's state transition timeline.

Initiate Payout

POST /v1/payouts

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

If your system needs to check balance before attempting a payout, call GET /v1/wallet and compare the payout total against spendablePaise.

Send a unique Idempotency-Key header for every merchant-side payout attempt. If your client retries the same attempt, reuse the same key. If the same key is reused for a different payout, the API returns the original payout associated with that key, so do not recycle keys across payout attempts.

Processing flow

1. Payout record created.
2. Wallet validation and debit reserve amount + commission + GST atomically.
3. Payout is dispatched to the bank adapter.
4. Intermediate bank states are stored in the status timeline.
5. Final status is persisted and a terminal webhook is sent if configured.

A 200 response confirms the payout was accepted for processing. Final status arrives via webhook, or you can poll with Get Payout Transaction.

Headers

Request body

Sample request body

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

Examples

curl --request POST 'https://api.bridg.money/v1/payouts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: pub_live_xxx' \
  --header 'x-timestamp: 1733740800000' \
  --header 'x-signature: <hmac-signature>' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --data '{
    "beneficiaryId": "123e4567-e89b-12d3-a456-426614174001",
    "amount": "1000.00",
    "transactionType": "N",
    "merchantReferenceId": "ORDER-123456"
  }'

List Payouts

GET /v1/payouts

Returns paginated payouts for the authenticated business.

This endpoint uses query parameters, so sign it with HMAC v2. Keep the URL as /v1/payouts; do not call /v2/payouts. See API Keys and IP Whitelist.

Query parameters

Search is paginated with the same limit and offset parameters as normal listing. Use search when you know an identifier but do not know the payout date. If search is not present, the selected date range applies normally.

Examples

curl --request GET 'https://api.bridg.money/v1/payouts?limit=50&offset=0' \
  --header 'x-bridg-sig-version: 2' \
  --header 'x-api-key: pub_live_xxx' \
  --header 'x-timestamp: 1733740800000' \
  --header 'x-nonce: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-signature: <hmac-v2-signature>'

curl --request GET 'https://api.bridg.money/v1/payouts?limit=50&offset=0&search=ORDER-123456' \
  --header 'x-bridg-sig-version: 2' \
  --header 'x-api-key: pub_live_xxx' \
  --header 'x-timestamp: 1733740800000' \
  --header 'x-nonce: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-signature: <hmac-v2-signature>'

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

Examples

curl --request GET 'https://api.bridg.money/v1/payouts/ca4bac52-2800-11f1-8a8e-0a0c26167b3f' \
  --header 'x-api-key: pub_live_xxx' \
  --header 'x-timestamp: 1733740800000' \
  --header 'x-signature: <hmac-signature>'

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.

Reconciliation Guidance

Store these identifiers from every successful POST /v1/payouts response:

merchantReferenceId is not an idempotency key and is not a replacement for payoutTransactionId. Use Idempotency-Key for safe retries of the same payout attempt, and use merchantReferenceId to connect BridgPay reports/webhooks back to your order or transaction table.

If your client times out before reading the POST /v1/payouts response, first search GET /v1/payouts?search=<your-merchantReferenceId> before creating a new payout. If you did not send a merchantReferenceId, search by the idempotency key in your own logs and contact support with the request timestamp.

Status Events

GET /v1/payouts/:payoutTransactionId/status-events

Returns the state transition timeline for a payout. This is useful when a payout is still pending and the merchant needs to see whether the bank has acknowledged, processed, failed, or gone silent.

Examples

curl --request GET 'https://api.bridg.money/v1/payouts/ca4bac52-2800-11f1-8a8e-0a0c26167b3f/status-events' \
  --header 'x-api-key: pub_live_xxx' \
  --header 'x-timestamp: 1733740800000' \
  --header 'x-signature: <hmac-signature>'