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.
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

{
  "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

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.