# Add a beneficiary

Adds a bank account or UPI ID that the customer can send money to. The beneficiary belongs to this payment
account and receives payouts only from it.
The body is the same as Create a beneficiary (`POST /v2/beneficiaries`),
with these differences:
- `category`
 is
`payout`
, and it is the default. Any other value returns
`400`
.
- `beneficiary.documents`
 is not accepted and returns
`400`
.

A new beneficiary is `active`, or `pending` while Glomo verifies it. A payout to a `pending` or
`rejected` beneficiary returns `400`. There is no update endpoint: to change a beneficiary, delete it and
add it again.

Endpoint: POST /payment-accounts/{payment_account_id}/beneficiaries
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Path parameters:

  - `payment_account_id` (string, required)
    The ID of a payment account you own. Starts with `pacct_`.

## Request fields (application/json):

  - `category` (string, required)
    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.

An **account funding** beneficiary uses `payout`. It is the customer's own account - the account
the card funds are credited to - not a third party.
    Enum: "payout", "lrs"

  - `beneficiary` (object, required)
    The beneficiary details including name, contact information, and address.

  - `beneficiary.name` (string, required)
    The name of the beneficiary. This is a required field. Reserved sandbox test values: `jexru7`, `nerqu8`, `havku9`, `dexru6` and `renvak4` (any letter case) force a sanctions-screening hit when a payout to this beneficiary is screened.
    Example: ACME Corporation

  - `beneficiary.type` (string, required)
    The type of beneficiary. Must be either `individual` or `business`.
    Enum: "individual", "business"

  - `beneficiary.email` (string)
    The email address of the beneficiary.
    Example: finance@acme.com

  - `beneficiary.phone` (string)
    The phone number of the beneficiary.
    Example: +1-555-123-4567

  - `beneficiary.nickname` (string)
    A nickname for the beneficiary. If not provided, it will be auto-generated as "{beneficiary_name} - {bank_name}".
    Example: ACME Primary Account

  - `beneficiary.address` (object, required)
    The address of the beneficiary. `address_line1`, `city`, `state` and `country_code` are required; `address_line2` and `postal_code` are optional.

  - `beneficiary.address.address_line1` (string, required)
    The street address of the beneficiary (required).
    Example: 123 Business Park

  - `beneficiary.address.address_line2` (string)
    The second line of street address of the beneficiary (optional).
    Example: Suite 100

  - `beneficiary.address.city` (string, required)
    The city where the beneficiary is located (required).
    Example: New York

  - `beneficiary.address.state` (string, required)
    The state or administrative area where the beneficiary is located (required).
    Example: NY

  - `beneficiary.address.country_code` (string, required)
    The country where the beneficiary is located (required). Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
    Example: USA

  - `beneficiary.address.postal_code` (string)
    The postal code of the beneficiary's address (optional).
    Example: 10001

  - `beneficiary.documents` (array)
    Optional list of document IDs to attach to the beneficiary.
    Example: ["doc_68e7980auYRAs"]

  - `bank_account` (object)
    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](/payout/rails).

  - `bank_account.account_number` (string, required)
    The account number of the beneficiary (required).
    Example: 1234567890

  - `bank_account.name` (string)
    The name of the bank where the account is held. Required for `category: lrs`, optional for `category: payout`.
    Example: Citibank NA

  - `bank_account.swift_code` (string)
    The SWIFT/BIC code of the bank. Must be 8-11 characters with first 6 being letters only. For LRS category it is optional, and must be exactly 8 characters (no branch suffix like XXX). For payout category, see [Payout rails](/payout/rails).
    Example: CITIUS33

  - `bank_account.local_routing_number` (string)
    The local routing code or domestic clearing code of the bank account. Required for LRS category, optional for payout category. For reference, this is the IFSC code in India, the sort code in the UK, ABA in the US, etc. For payout category, see [Payout rails](/payout/rails).
    Example: 021000089

  - `bank_account.currency` (string, required)
    The currency of the bank account (required).
    Example: USD

  - `bank_account.address` (object)
    The address of the bank. Required for `category: lrs`, optional for `category: payout`. When sent, `address_line1`, `city`, `state` and `country_code` are required; `address_line2` and `postal_code` are optional.

  - `bank_account.address.address_line1` (string, required)
    The street address of the bank (required).
    Example: 388 Greenwich Street

  - `bank_account.address.address_line2` (string)
    The second line of street address of the bank (optional).

  - `bank_account.address.city` (string, required)
    The city where the bank is located (required).
    Example: New York

  - `bank_account.address.state` (string, required)
    The state or administrative area where the bank is located (required).
    Example: NY

  - `bank_account.address.country_code` (string, required)
    The country where the bank is located (required). Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
    Example: USA

  - `bank_account.address.postal_code` (string)
    The postal code of the bank's address (optional).
    Example: 10013

  - `bank_account.intermediate_bank` (object)
    Details of the intermediate/correspondent bank. **`swift_code` is required for LRS category beneficiaries.** Optional for payout category beneficiaries.

  - `bank_account.intermediate_bank.name` (string)
    The name of the intermediate bank (optional).
    Example: JPMorgan Chase Bank

  - `bank_account.intermediate_bank.country` (string)
    The country of the intermediate bank (optional). Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.
    Example: USA

  - `bank_account.intermediate_bank.swift_code` (string)
    The SWIFT/BIC code of the correspondent/intermediary bank used to route the remittance. Required for LRS category, optional for payout category.
    Example: CHASUS33

  - `bank_account.intermediate_bank.account_number` (string)
    The account number at the intermediate bank (optional).
    Example: 123456789

  - `upi_account` (object)
    UPI account details. Provide either bank_account or upi_account, not both.

  - `upi_account.upi_id` (string)
    The UPI ID of the beneficiary.
    Example: 1111111111@ybl

  - `notes` (object | null)
    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. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes <field> is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). 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 201:

  - `201` (unknown)
    Beneficiary added

## Response 201 fields (application/json):

  - `id` (string)
    Example: bene_6ab5a1c9gflRf

  - `payment_account_id` (string)
    The payment account that owns the beneficiary.
    Example: pacct_6ab59a10Hk3Zq

  - `name` (string)
    Example: Aarav Nair

  - `category` (string)
    Enum: "payout"

  - `type` (string)
    Enum: "individual", "business"

  - `email` (string | null)
    Example: aarav.nair@example.com

  - `phone` (string | null)
    Example: null

  - `nickname` (string | null)
    Example: My NRE account

  - `status` (string)
    `active` beneficiaries can receive payouts. A payout to a `pending` or `rejected` beneficiary returns `400`.
    Enum: "active", "pending", "rejected"

  - `notes` (object | null)
    Example: null

  - `address` (object | null)

  - `address.address_line1` (string)
    Example: 12 Marina Walk

  - `address.address_line2` (string | null)
    Example: null

  - `address.city` (string)
    Example: Kochi

  - `address.state` (string)
    Example: Kerala

  - `address.country_code` (string)
    ISO 3166-1 alpha-3 country code.
    Example: IND

  - `address.postal_code` (string | null)
    Example: 682001

  - `bank_account` (object | null)
    The bank account details. `null` on a UPI beneficiary.

  - `bank_account.account_number` (string)
    Example: 000111222333

  - `bank_account.name` (string | null)
    The name of the bank.
    Example: HDFC Bank

  - `bank_account.swift_code` (string | null)
    Example: null

  - `bank_account.local_routing_number` (string | null)
    The local routing code, for example the IFSC for an INR account.
    Example: HDFC0000123

  - `bank_account.currency` (string)
    Example: INR

  - `bank_account.category` (string | null)
    Example: null

  - `bank_account.intermediate_bank` (object | null)
    Example: null

  - `bank_account.intermediate_bank.name` (string)

  - `bank_account.intermediate_bank.country` (string)

  - `bank_account.intermediate_bank.swift_code` (string)

  - `bank_account.intermediate_bank.account_number` (string)

  - `upi_account` (object | null)
    The UPI details. `null` on a bank account beneficiary.
    Example: null

  - `upi_account.upi_id` (string)
    Example: aarav@okhdfcbank

  - `created_at` (string)
    Example: 2026-10-15T10:40:12Z

  - `updated_at` (string)
    Example: 2026-10-15T10:40:12Z

## Response 400:

  - `400` (unknown)
    The request is not valid

## Response 400 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

## Response 404:

  - `404` (unknown)
    The payment account does not exist or you do not own it

## Response 404 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

## Response 409:

  - `409` (unknown)
    This payment account already has a beneficiary with this account number

## Response 409 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

## Response 422:

  - `422` (unknown)
    Glomo could not create the beneficiary. `message` gives the reasons.

## Response 422 fields (application/json):

  - `error` (string, required)
    The HTTP reason phrase.
    Example: Bad Request

  - `message` (string, required)
    What went wrong. Show it in logs, not to the customer.
    Example: Payment account cannot send money

  - `code` (string)
    A stable code for the error. Present only on some errors, for example `INSUFFICIENT_BALANCE` on a payout and `order_amount_above_cap` on an order. Branch on `code` when it is present, and on the HTTP status when it is not.
    Example: INSUFFICIENT_BALANCE

