POST/v2/beneficiary/add-virtual-account/{beneficiaryID}

Add Virtual Account

Adds a virtual account to an existing beneficiary. Use Get Required Fields (Add Virtual Account) for the field list.

Path variables

Field	Type	Required	Possible values	Description
`beneficiaryID`	string	Required	{beneficiaryID}	Unique beneficiary ID returned from Create Beneficiary or List Beneficiaries.

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
`fields`	object	Required	[{ "field": "FieldName", "value": "..." }]	Use Get Required Fields (Add Virtual Account) (POST /v2/beneficiary/get-required-fields-for-virtual-account) endpoint to get the field values. Structure differs for individual vs business beneficiaries (see examples in Postman).

Example request

[
  {
    "field": "Beneficiary_Type",
    "value": "business"
  },
  {
    "field": "Beneficiary_Document",
    "value": [
      {
        "field": "Document_Type",
        "value": "Cretificate_Of_Incorporation"
      },
  …

Example above is for a business beneficiary. For individual beneficiaries, include Beneficiary_DOB and use ID_Type, ID_Number, ID_Expiration_Date, Front_Document, and Back_Document inside Beneficiary_Document (upload files first via POST /v2/files/upload to obtain FileId values).

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	Confirmation message when the virtual account is added successfully.

Example response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": "Beneficiary successfully updated"
}

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