Beneficiaries

Beneficiaries are tenant-scoped payout targets. A beneficiary may route by bank account + IFSC, or by UPI VPA.

Add Beneficiary

POST /v1/beneficiaries

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

If the beneficiary already exists under the same business, the API returns 409 with the existing beneficiary's beneficiaryId -- no duplicate is created. Bank beneficiaries dedupe on accountNumber + ifsc; UPI beneficiaries dedupe on vpa.

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.
accountNumber	string	bank only	Bank account number, 9-18 digits. Required with ifsc; do not send with vpa.
ifsc	string	bank only	Bank IFSC code, 11 characters in AAAA0XXXXXX format. Required with accountNumber; do not send with vpa.
vpa	string	UPI only	UPI VPA such as vendor@okhdfcbank. Do not send with bank fields.

Send exactly one of:

• Bank target: accountNumber + ifsc
• UPI target: vpa

Sample bank request body

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

Sample UPI request body

{
  "name": "Ravi Traders Pvt Ltd",
  "email": "ravi@merchant.com",
  "phoneNumber": "9876543210",
  "vpa": "ravi.traders@okhdfcbank"
}

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",
    "vpa": null
  },
  "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.

---

List Beneficiaries

GET /v1/beneficiaries

Returns beneficiaries for the authenticated business.

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

Query parameters

Name	Type	Default	Description
limit	number	50	Page size, clamped from 1 to 200.
offset	number	0	Zero-based offset.
since	ISO datetime	none	Include beneficiaries created at or after this time.
until	ISO datetime	none	Include beneficiaries created before this time.
search	string	none	Searches code, name, email, phone, account number, IFSC, and VPA.
status	string	active	active, inactive, or all.

Sample response

{
  "status": 200,
  "data": [
    {
      "beneficiaryId": "123e4567-e89b-12d3-a456-426614174000",
      "beneficiaryCode": "BMBN2026032500001",
      "name": "Ravi Traders Pvt Ltd",
      "email": "ravi@merchant.com",
      "phoneNumber": "9876543210",
      "accountNumber": "0002053000010425",
      "ifsc": "UTIB0000123",
      "vpa": null,
      "status": "active",
      "createdAt": "2026-03-25T10:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1
  },
  "message": null,
  "meta": null
}

---

Update Beneficiary

PATCH /v1/beneficiaries/:beneficiaryId

Updates beneficiary profile or payment details. At least one field is required.

Request body

Field	Type	Required	Description
name	string	no	Beneficiary name.
email	string, empty string, or null	no	Valid email, blank, or null. Blank is stored as null.
phoneNumber	string	no	10-15 digits.
accountNumber	string	no	Bank account number.
ifsc	string	no	IFSC. Normalized to uppercase.
vpa	string	no	UPI VPA.

Changing payment details can conflict with another beneficiary. In that case the API returns 409.

Sample request

{
  "name": "Ravi Traders",
  "phoneNumber": "9876543210"
}

Sample response

{
  "status": 200,
  "data": {
    "beneficiaryId": "123e4567-e89b-12d3-a456-426614174000",
    "beneficiaryCode": "BMBN2026032500001",
    "name": "Ravi Traders",
    "email": "ravi@merchant.com",
    "phoneNumber": "9876543210",
    "accountNumber": "0002053000010425",
    "ifsc": "UTIB0000123",
    "vpa": null,
    "status": "active",
    "createdAt": "2026-03-25T10:30:00.000Z"
  },
  "message": "Beneficiary updated successfully",
  "meta": null
}

---

Reactivate Beneficiary

POST /v1/beneficiaries/:beneficiaryId/reactivate

Reactivates an archived beneficiary so it can receive payouts again.

Request body

{
  "reason": "merchant reactivation"
}

reason is optional and may be omitted.

---

Archive Beneficiary

DELETE /v1/beneficiaries/:beneficiaryId

Archives 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 archived

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

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