> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/beneficiaries/get-detail-beneficiary.md).

# Get Detail Beneficiary

#### Endpoint: GET /v2/gc/beneficiaries/{requestId}

#### Description: Retrieve the registration details and current status of a specific beneficiary by its original request ID.

## Request

#### Request Params Field Descriptions

| Field Name    | Type   | Required | Description                                                                                         |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| type          | string | No       | Filter by beneficiary type. Enum: `OVERSEAS_SUPPLIER` \| `DOMESTIC_SUPPLIER` \| `WITHDRAW_ACCOUNT`. |
| subMerchantId | string | No       | Sub-merchant identifier to scope the query to a specific sub-merchant.                              |
| accountNumber | string | No       | Bank account number to use as an additional filter when looking up the beneficiary.                 |

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                                                                                        |
| ------------- | ------ | -------------------------------------------------------------------------------------------------- |
| code          | number | Response code. Refer to [Error Codes](/docs/global/global-collections/integration/error-codes.md). |
| state         | number | State of the response.                                                                             |
| data          | object | Beneficiary details.                                                                               |
| message       | string | Response message.                                                                                  |
| neoResponseId | string | Unique NeoX response identifier (UUID).                                                            |

#### `data` object fields:

| Field Name    | Type   | Description                                                                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| requestId     | string | The original merchant-provided `requestId` used during registration.                                                                   |
| merchantId    | string | NeoX merchant identifier.                                                                                                              |
| subMerchantId | string | Sub-merchant identifier associated with this beneficiary, if applicable.                                                               |
| status        | string | Current registration status. Enum: `SUCCESS` \| `RISK_REBUT` \| `WAIT_SUPPLEMENT_MATERIAL` \| `ACTIVATED` \| `FAILED` \| `PROCESSING`. |
| beneficiaryId | string | Unique NeoX identifier for the registered beneficiary.                                                                                 |

#### Response sample

```json
{
  "code": 1,
  "state": 2,
  "data": {
    "requestId": "b2e4f6a8-5678-4321-cdef-0123456789ab",
    "merchantId": "MERCH-00012345",
    "subMerchantId": "",
    "status": "ACTIVATED",
    "beneficiaryId": "BEN-20240501-000456789"
  },
  "message": "Successful",
  "neoResponseId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
}
```

## Example cURL

```bash
curl -X GET "https://{base_url_openapi}/v2/gc/beneficiaries/{requestId}?type=OVERSEAS_SUPPLIER&subMerchantId=SUB-MERCH-00091" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en"
```

### Notes

* Requires Bearer token in the Authorization header.
* The Accept-Language header can be used to specify the response language (Support: "vi", "en").
* No request body required.
* Replace `{requestId}` with the actual `requestId` used when registering the beneficiary.
* The optional query parameters `type`, `subMerchantId`, and `accountNumber` can be appended to the URL to narrow the lookup.
* A `status` of `ACTIVATED` indicates the beneficiary is verified and ready to receive payouts.
* A `status` of `RISK_REBUT` or `WAIT_SUPPLEMENT_MATERIAL` indicates additional information may be required; contact NeoX support or resubmit via [Register Beneficiary](/docs/global/global-collections/integration/beneficiaries/api-register-beneficiary.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neox.vn/docs/global/global-collections/integration/beneficiaries/get-detail-beneficiary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.