> ## Documentation Index
> Fetch the complete documentation index at: https://pay-docs.holdstation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit KYB

> Submit a business verification (KYB) record for your partner account or a merchant under it.

Creates a KYB record with status `1` (Pending). The record id is generated by Holdstation Pay and returned as `id` — do not send one.

For `subject_type = 1` a partner holds at most one record. For `subject_type = 2` the same rule applies per `reference_id`. While a record is Pending or Approved, another `POST` for that subject fails with `409 Conflict`. Once a record is Rejected, `POST` again to replace it — the status resets to Pending, the record keeps its original id, and the files attached to the rejected submission are deleted. There is no update endpoint.

See the [Partner Business KYB guide](/guides/partner-business-kyb/overview) for the lifecycle, the [Field Reference](/guides/partner-business-kyb/field-reference) for every field, [Submission Rules](/guides/partner-business-kyb/submission-rules) for the cross-field checks, and [Submitting Documents](/guides/partner-business-kyb/submitting-documents) for file rules.

## Authentication

<ParamField header="Partner-App-Key" type="string" required>
  Your partner app key.
</ParamField>

<ParamField header="X-HSPay-Signature" type="string" required>
  Base64-encoded Ed25519 signature of the sign data.
</ParamField>

<ParamField header="X-HSPay-Timestamp" type="string" required>
  Unix timestamp (seconds) of the request. Must be within 60 seconds of server time.
</ParamField>

## Body Parameters

<ParamField body="subject_type" type="integer" required>
  `1` = partner (self), `2` = sub-merchant.
</ParamField>

<ParamField body="reference_id" type="string">
  Your own id for the subject, e.g. your merchant id. Max 128 bytes, stored trimmed. One `subject_type = 2` record per `reference_id`; generated by Holdstation Pay and returned if omitted. Not used for `subject_type = 1`.
</ParamField>

<ParamField body="legal_name" type="string" required>
  Company name exactly as on the incorporation document.
</ParamField>

<ParamField body="registration_number" type="string" required>
  Business registration / incorporation number.
</ParamField>

<ParamField body="incorporation_country" type="string" required>
  ISO 3166-1 alpha-2 preferred. Alpha-3 (`VNM`) and full names (`Vietnam`) are accepted and normalized to alpha-2.
</ParamField>

<ParamField body="incorporation_date" type="string" required>
  Incorporation date in ISO `YYYY-MM-DD` format.
</ParamField>

<ParamField body="address" type="string" required>
  Registered company address.
</ParamField>

<ParamField body="email" type="string">
  Business email.
</ParamField>

<ParamField body="phone" type="string">
  Business phone number.
</ParamField>

<ParamField body="website" type="string">
  Business website.
</ParamField>

<ParamField body="nature_of_business" type="string" required>
  What the company does: industry, products, services, customers, business model.
</ParamField>

<ParamField body="geographic_scope" type="string[]" required>
  Where the business operates and serves customers. ISO 3166-1 alpha-2 preferred, but values are not format-checked — region labels such as `EU` or `SEA` are accepted.
</ParamField>

<ParamField body="persons" type="object[]" required>
  Legal representative and directors. **Exactly one** person must have `role = 1`. Each entry requires `role` (`1` = Legal representative, `2` = Director), `name`, `date_of_birth`, `address`, `id_number`, `id_type` (`1` = Citizen ID, `2` = Passport), `sex` (`1` = Male, `2` = Female, `3` = Other), `nationality`, and exactly one `documents` entry of type `10` or `11`. `email`, `phone`, `date_of_issue`, and `date_of_expiry` are optional.
</ParamField>

<ParamField body="documents" type="object[]" required>
  Company documents, types `1`–`9` only. Must include type `1` and type `3`. Each entry requires `type` and `files` (max 10 per document); `document_number` is required for type `4`, and `date_of_issue` and `date_of_expiry` are optional.
</ParamField>

## Document Types

| Value | Document                                                              | Required       | Belongs in              |
| ----- | --------------------------------------------------------------------- | -------------- | ----------------------- |
| `1`   | Incorporation paper                                                   | **Yes**        | `documents[]`           |
| `2`   | Business registration extract                                         | No             | `documents[]`           |
| `3`   | Nature of business & geographic scope declaration, with company stamp | **Yes**        | `documents[]`           |
| `4`   | Import/export licence                                                 | No             | `documents[]`           |
| `5`   | Product images                                                        | No             | `documents[]`           |
| `9`   | Other company document                                                | No             | `documents[]`           |
| `10`  | Passport                                                              | One per person | `persons[].documents[]` |
| `11`  | Citizen ID                                                            | One per person | `persons[].documents[]` |

## Key Rules

* Exactly one person must have `role = 1`, or the submission is rejected with `MISSING_LEGAL_REPRESENTATIVE`.
* A person whose `nationality` differs from `incorporation_country` must use `id_type: 2` with a type `10` document.
* Each person carries exactly one identity document; multiple files (ID front and back) go inside that one document.
* Files are sent inline as base64 in `data` — a path or URL is rejected with `FILE_CORRUPT`. Each file is capped at 10 MB decoded, the body at 40 MB, and a submission at 30 documents and 20 persons.

<RequestExample>
  ```json Request theme={null}
  {
    "subject_type": 2,
    "reference_id": "merchant-00042",
    "legal_name": "ABC Trading Co., Ltd",
    "registration_number": "0312345678",
    "incorporation_country": "VN",
    "incorporation_date": "2019-03-14",
    "address": "12 Nguyen Hue, District 1, Ho Chi Minh City, Vietnam",
    "email": "ops@abctrading.vn",
    "phone": "+84901234567",
    "website": "https://abctrading.vn",
    "nature_of_business": "Wholesale import and distribution of consumer electronics accessories to retail chains. B2B only, net-30 terms, no direct consumer sales.",
    "geographic_scope": ["VN", "KH"],
    "persons": [
      {
        "role": 1,
        "name": "Nguyen Van A",
        "date_of_birth": "1985-06-02",
        "email": "a.nguyen@abctrading.vn",
        "phone": "+84901234567",
        "address": "12 Nguyen Hue, District 1, Ho Chi Minh City, Vietnam",
        "id_number": "C1234567",
        "id_type": 2,
        "sex": 1,
        "nationality": "VN",
        "date_of_issue": "2021-01-10",
        "date_of_expiry": "2031-01-10",
        "documents": [
          {
            "type": 10,
            "files": [
              { "filename": "passport.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjQKJc..." }
            ]
          }
        ]
      },
      {
        "role": 2,
        "name": "Tran Thi B",
        "date_of_birth": "1990-11-23",
        "phone": "+84902223344",
        "address": "45 Le Loi, District 1, Ho Chi Minh City, Vietnam",
        "id_number": "079090005678",
        "id_type": 1,
        "sex": 2,
        "nationality": "VN",
        "documents": [
          {
            "type": 11,
            "files": [
              { "filename": "cid_front.jpg", "content_type": "image/jpeg", "data": "/9j/4AAQSkZJRg..." },
              { "filename": "cid_back.jpg", "content_type": "image/jpeg", "data": "/9j/4AAQSkZJRg..." }
            ]
          }
        ]
      }
    ],
    "documents": [
      {
        "type": 1,
        "date_of_issue": "2019-03-14",
        "files": [
          { "filename": "incorporation.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjQKJc..." }
        ]
      },
      {
        "type": 3,
        "date_of_issue": "2026-08-01",
        "files": [
          { "filename": "nature_and_scope_stamped.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjQKJc..." }
        ]
      },
      {
        "type": 4,
        "document_number": "IE-2021-88771",
        "date_of_issue": "2021-02-15",
        "date_of_expiry": "2027-02-14",
        "files": [
          { "filename": "import_export_license.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjQKJc..." }
        ]
      }
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "message": "success",
    "data": {
      "success": true,
      "kyb": {
        "id": "7c2f1a90-4d3b-4e2a-9f61-0b8c5d7e1234",
        "partner_id": "11111111-1111-1111-1111-111111111111",
        "subject_type": 2,
        "reference_id": "merchant-00042",
        "status": 1,
        "submitted_at": "2026-08-19T03:14:22Z"
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "invalid request",
    "error_code": "BAD_REQUEST",
    "message": "Invalid parameters"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "unauthorized",
    "error_code": "UNAUTHORIZED",
    "message": "Invalid or missing signature"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "CONFLICT",
    "message": "A pending or approved KYB record already exists for this subject",
    "detail": ""
  }
  ```

  ```json 415 theme={null}
  {
    "error": "UNSUPPORTED_MEDIA_TYPE",
    "message": "File type not accepted",
    "detail": ""
  }
  ```

  ```json 422 theme={null}
  {
    "error": "VALIDATION_FAILED",
    "message": "One or more fields are invalid",
    "detail": "{\"code\":\"VALIDATION_FAILED\",\"details\":[{\"code\":\"MISSING_LEGAL_REPRESENTATIVE\",\"target\":\"/persons\"},{\"code\":\"INVALID_FORMAT\",\"target\":\"/persons/0/id_type\"},{\"code\":\"FILE_CORRUPT\",\"target\":\"/documents/0/files/0\"}]}"
  }
  ```
</ResponseExample>