Beneficiary V2

This resource represents a payee of a payout initiated by your business. Beneficiary V2 introduces a structured nested format for beneficiary, address, and bank account details, and supports both bank account and UPI payment methods.

SchemasOperations

BeneficiaryV2

idstringread-only

The unique identifier for the beneficiary.

Example:"ben_5JU9yv0lGSUP"

namestring

The name of the beneficiary.

Example:"ACME Corporation"

typestring

The type of beneficiary.

Enum:"individual""business"

Example:"business"

categorystringread-only

The category of the beneficiary.

Enum:"payout""lrs"

Example:"payout"

emailstring, (email)

The email address of the beneficiary.

Example:"finance@acme.com"

phonestring

The phone number of the beneficiary.

Example:"+1-555-123-4567"

nicknamestring

A nickname for the beneficiary. If not provided, auto-generated as "{beneficiary_name} - {bank_name}".

Example:"ACME Primary Account"

addressobject

The address of the beneficiary.

bank_accountobject

The bank account details of the beneficiary.

statusstringread-only

The current review status of the beneficiary.

Enum:"pending""active""rejected"

Example:"pending"

documentsArray of stringsread-only

List of document IDs attached to the beneficiary.

Example:

[
  "doc_68e7980auYRAs"
]

upi_accountobject or null

The UPI account details of the beneficiary. Present when the beneficiary uses UPI, otherwise null.

created_atstring, (date-time)read-only

Timestamp representing when the beneficiary was created in ISO 8601 format.

Example:"2025-01-15T10:00:00Z"

updated_atstring, (date-time)read-only

Timestamp representing when the beneficiary was last updated in ISO 8601 format.

Example:"2025-01-15T10:00:00Z"

notesobject or null(Notes)

Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.

Example:

{
  "invoice_ref": "INV-2026-001",
  "project": "Alpha"
}

{
  "id": "ben_5JU9yv0lGSUP",
  "name": "ACME Corporation",
  "type": "business",
  "category": "payout",
  "email": "finance@acme.com",
  "phone": "+1-555-123-4567",
  "nickname": "ACME Primary Account",
  "address": {
    "address_line1": "123 Business Park",
    "address_line2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "country_code": "USA",
    "postal_code": "10001"
  },
  "bank_account": {
    "account_number": "1234567890",
    "name": "Citibank NA",
    "swift_code": "CITIUS33",
    "local_routing_number": "021000089",
    "currency": "USD",
    "address": { … },
    "intermediate_bank": { … }
  },
  "status": "pending",
  "documents": [
    "doc_68e7980auYRAs"
  ],
  "upi_account": {
    "upi_id": "1111111111@ybl"
  },
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  }
}