POST/v2/beneficiary/get-required-fields-for-virtual-account

Get Required Fields (Add Virtual Account)

Virtual accounts are a solution that enables account holders to generate unique account numbers for receiving third-party deposits while maintaining centralized fund management. Each virtual account is linked to a specific beneficiary relationship—whether a vendor or customer—and comes with dedicated deposit instructions accessible through web portals, mobile applications, and APIs. When funds are deposited using a virtual account reference, the system automatically routes these payments to the parent account holder's primary USD bank account. This creates a seamless collection mechanism for multiple payment sources without the complexity of managing separate physical bank accounts. Pass the beneficiary type to receive the field schema required to add a virtual account to an existing beneficiary

Headers

Field	Type	Required	Possible values	Description
`Authorization`	string	Required	Bearer {SessionToken}	Session token from Get Session Token, sent as `Authorization: Bearer {SessionToken}`. Replace with the value from the `x-refresh-token` response header when present (typically within 2 minutes of expiry). Secured calls must use the same IP as the auth request.

Request body

Field	Type	Required	Possible values	Description
`BeneficiaryType`	string	Required	individual \| business	Beneficiary category: `individual` or `business`. Determines which fields are returned or required.

Example request

{
  "BeneficiaryType": "individual"
}

Response

Field	Type	Possible values	Description
`ResponseCode`	integer	200 \| 201 \| 204 \| 400 \| 401 \| 403 \| 404 \| 410 \| 422 \| 500 \| 301 \| 503 \| 422	API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized).
`ResponseMessage`	string	Success \| Created \| NoContent \| BadRequest \| Unauthorized \| Forbidden \| NotFound \| Gone \| UnprocessableContent \| ServerError \| ResourceMoved \| ServiceUnAvailable \| UnProcessableEntity	Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome.
`ResponseData`	object	Please refer to below example for response body	Dynamic field definitions required for Add Virtual Account.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "Fields": [
      {
        "Name": "Beneficiary_Type",
        "Required": true,
        "Type": "Text",
        "PossibleValues": [
          {
            "label": "Individual",
  …

Note: Please refer to attached examples for the exact values

Requires `Authorization: Bearer {SessionToken}` from Get Session Token. Refresh via `x-refresh-token` when supplied; use the same client IP as authentication.