> 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/sub-merchants/api-report-sub-merchant.md).

# Report Sub-Merchant

#### Endpoint: POST /v2/gc/sub-merchants/report

#### Description: Report a sub-merchant using a lighter-weight registration flow that does not require full KYC/KYB onboarding documentation.

## Request

#### Request Body Field Descriptions (JSON)

| Field Name       | Type   | Required | Description                                                                                                 |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| requestId        | string | Yes      | Merchant-generated unique request ID (*UUID recommended*). Used for idempotency.                            |
| reportType       | string | Yes      | Type of entity being reported. Enum: `SUB_MERCHANT`, `SUPPLIER`.                                            |
| subMerchantType  | string | Yes      | Category of the sub-merchant. Enum: `PERSON`, `INDIVIDUAL`, `ENTERPRISE`.                                   |
| platformMemberId | string | Yes      | Merchant's own identifier for this member on their platform.                                                |
| signedName       | string | Yes      | Legal name of the sub-merchant as it appears on signed agreements.                                          |
| countryCode      | string | Yes      | Country of the sub-merchant in ISO 3166-1 alpha-3 format (e.g. `HKG`, `CHN`, `SGP`).                        |
| vouchers         | array  | Yes      | List of supporting document vouchers. See `vouchers` object item fields below.                              |
| businessType     | string | No       | Primary business type of the sub-merchant (e.g. `LOGISTICS_COST`, `GOODS_PURCHASE`, `ADVERTISING_SERVICE`). |
| bankInfos        | array  | No       | List of bank account details associated with the sub-merchant.                                              |
| shopInfos        | array  | No       | List of shop or storefront information associated with the sub-merchant.                                    |
| notifyUrl        | string | No       | Merchant-hosted callback URL to receive asynchronous report status notifications.                           |

#### `vouchers` object item fields:

| Field Name  | Type   | Required | Description                                                                                                              |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| voucherType | string | Yes      | Type of the supporting document (e.g. `BUSINESS_LICENSE`, `ID_CARD`).                                                    |
| url         | string | Yes      | File path of the uploaded voucher document. Use the `path` returned by the File Upload API (`POST /v2/gc/files/upload`). |

#### Request sample

```json
{
  "requestId": "d5e6f7a8-2345-4d89-cabc-1122334455ee",
  "reportType": "SUB_MERCHANT",
  "subMerchantType": "ENTERPRISE",
  "platformMemberId": "PLT-MBR-001234",
  "signedName": "Bright Star Commerce Ltd",
  "countryCode": "HKG",
  "vouchers": [
    {
      "voucherType": "BUSINESS_LICENSE",
      "url": "gpt/NETWORK_ACCESS/20240301/biz_license_d5e6f7a8.jpg"
    }
  ],
  "businessType": "GOODS_PURCHASE",
  "bankInfos": [],
  "shopInfos": [],
  "notifyUrl": "https://merchant.example.com/webhooks/report"
}
```

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| code          | number | Response code.                         |
| state         | number | State of the response.                 |
| data          | object | Sub-merchant report submission result. |
| message       | string | Response message.                      |
| neoResponseId | string | Unique NeoX response identifier.       |

#### `data` object fields:

| Field Name    | Type   | Description                                                                     |
| ------------- | ------ | ------------------------------------------------------------------------------- |
| requestId     | string | Echoes the merchant-supplied `requestId`.                                       |
| merchantId    | string | NeoX merchant identifier for the parent merchant.                               |
| subMerchantId | string | NeoX identifier assigned to the reported sub-merchant.                          |
| status        | string | Current report status. Enum: `ACTIVATED`, `FAILED`, `PROCESSING`.               |
| beneficiaryId | string | Beneficiary identifier assigned to the sub-merchant, used for payout targeting. |

#### Response sample

```json
{
  "code": 1,
  "state": 2,
  "data": {
    "requestId": "d5e6f7a8-2345-4d89-cabc-1122334455ee",
    "merchantId": "MC-00012345",
    "subMerchantId": "SM-00098762",
    "status": "PROCESSING",
    "beneficiaryId": "BEN-00056789"
  },
  "message": "Successful",
  "neoResponseId": "e1f2a3b4-66cb-4c23-9d04-5a7890123456"
}
```

## Example cURL

```bash
curl -X POST "https://{base_url_openapi}/v2/gc/sub-merchants/report" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "d5e6f7a8-2345-4d89-cabc-1122334455ee",
    "reportType": "SUB_MERCHANT",
    "subMerchantType": "ENTERPRISE",
    "platformMemberId": "PLT-MBR-001234",
    "signedName": "Bright Star Commerce Ltd",
    "countryCode": "HKG",
    "vouchers": [
      {
        "voucherType": "BUSINESS_LICENSE",
        "url": "gpt/NETWORK_ACCESS/20240301/biz_license_d5e6f7a8.jpg"
      }
    ],
    "businessType": "GOODS_PURCHASE",
    "bankInfos": [],
    "shopInfos": [],
    "notifyUrl": "https://merchant.example.com/webhooks/report"
  }'
```

### Notes

* Requires Bearer token in the Authorization header.
* The Accept-Language header can be used to specify the response language (Support: "vi", "en").
* Use a unique `requestId` for each request to avoid duplicate submissions.
* The request body must be in JSON format.
* All `vouchers[].url` values must be `path` values returned by the File Upload API (`POST /v2/gc/files/upload`).
* This is an asynchronous operation. The final result is delivered via the `SUB_MERCHANT` webhook and can also be polled using `GET /v2/gc/sub-merchants/report/{requestId}`.