Skip to content
/Beneficiary V2

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.

Schemas
Operations

Create a Beneficiary

Request

Creates a beneficiary with structured nested objects for beneficiary details, address, and bank account or UPI information.

Security
JWT
Bodyapplication/jsonrequired
categorystringrequired

The category of the beneficiary.

  • payout — the primary use case. Processes a payout from your Glomo balance.
  • lrs — a specific case. Processes an LRS (Liberalised Remittance Scheme) payin whose funds go directly to a customer-specific bank account rather than into your Glomo balance.
Enum:"payout""lrs"
Example:"payout"
beneficiaryobjectrequired

The beneficiary details including name, contact information, and address.

bank_accountobject

The bank account details of the beneficiary.

For category: payout, name and address are resolved from the swift_code, the local_routing_number, or an IBAN account_number. Send them only if the identifier cannot be resolved, or to override the resolved values. Both remain required for category: lrs.

Routing identifier rules differ by category:

  • category: lrs — local_routing_number is required. swift_code is optional.
  • category: payout — provide exactly one of swift_code or local_routing_number, except for EUR and AED accounts identified by an IBAN alone, which send neither.

For the rails each identifier maps to, see Payout rails.

upi_accountobject

UPI account details. Provide either bank_account or upi_account, not both.

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"
}
POST
/v2/beneficiaries
curl -i -X POST \
  https://api.glomopay.com/api/v2/beneficiaries \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "payout",
    "beneficiary": {
      "name": "John Doe",
      "type": "individual",
      "address": {
        "address_line1": "456 Main Street",
        "city": "Los Angeles",
        "state": "CA",
        "country_code": "USA",
        "postal_code": "90001"
      }
    },
    "bank_account": {
      "account_number": "1234567890",
      "swift_code": "CITIUS33",
      "currency": "USD"
    },
    "notes": {
      "invoice_ref": "INV-2026-002"
    }
  }'

Responses

Beneficiary created successfully

Bodyapplication/json
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"
}
Response
{
  "id": "bene_5JU9yv0lGSUP",
  "name": "ACME Corporation",
  "type": "business",
  "category": "lrs",
  "status": "pending",
  "email": "finance@acme.com",
  "phone": "+1-555-123-4567",
  "nickname": "ACME Primary Account",
  "upi_account": null,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "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": { … }
  },
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  }
}