Beneficiaries

Add Beneficiary

POST /v1/beneficiaries

Add a beneficiary by providing the beneficiary's name, phone number, and bank account details. Only active beneficiaries can receive payouts.

If the beneficiary already exists (same account + IFSC under the same business), the API returns 409 with the existing beneficiary's beneficiaryId — no duplicate is created. Use that ID to initiate payouts.

Request body

Field	Type	Required	Description
name	string	yes	Beneficiary name. Max 100 characters.
email	string	no	Valid email address.
phoneNumber	string	yes	Valid Indian mobile number (10 digits).
accountNumber	string	yes	Bank account number, 9–18 digits. Must be unique for active beneficiaries under this business.
ifsc	string	yes	Bank IFSC code, 11 characters in AAAA0XXXXXX format.

Sample request body

{
  "name": "Ravi Traders Pvt Ltd",
  "email": "ravi@merchant.com",
  "phoneNumber": "9876543210",
  "accountNumber": "0002053000010425",
  "ifsc": "UTIB0000123"
}

Responses

201 Beneficiary created successfully

{
  "status": 200,
  "data": {
    "beneficiaryId": "123e4567-e89b-12d3-a456-426614174000",
    "beneficiaryCode": "BMBN2026032500001"
  },
  "message": "Beneficiary created successfully",
  "meta": null
}

409 Beneficiary already exists

{
  "status": 409,
  "data": {
    "beneficiaryId": "50a97363-71bb-47b1-af7f-a55444684a58",
    "name": "Test User",
    "email": "test@example.com",
    "phoneNumber": "9876543210",
    "accountNumber": "123456789012",
    "ifsc": "HDFC0001234"
  },
  "message": "Beneficiary already exists",
  "meta": null
}

400 Validation error or invalid data · 401 Missing headers / expired timestamp / invalid signature · 500 Internal error — all in the error codes reference.

---

Delete Beneficiary

DELETE /v1/beneficiaries/:beneficiaryId

Soft-deletes the beneficiary by setting status to Inactive (0). Inactive beneficiaries cannot receive new payouts, but historical payout records still reference them.

Path parameters

Name	Type	Required	Description
beneficiaryId	UUID	yes	The beneficiary to deactivate.

Responses

200 Beneficiary deleted

{
  "status": 200,
  "data": {
    "beneficiaryId": "123e4567-e89b-12d3-a456-426614174000",
    "status": 0
  },
  "message": "Beneficiary deleted successfully",
  "meta": null
}

404 Beneficiary not found — already deleted, or not owned by the authenticated business.