Field Reference

The request body for POST /partners/kyb is a single JSON object. See Submission Rules for the cross-field checks that run on top of these per-field requirements.

Business Fields

Field	Type	Required	Notes
`subject_type`	int enum	Yes	`1` = partner (self), `2` = sub-merchant
`reference_id`	string	No	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 if omitted. Not used for `subject_type = 1`.
`legal_name`	string	Yes	Company name exactly as on the incorporation document
`registration_number`	string	Yes	Business registration / incorporation number
`incorporation_country`	string	Yes	ISO 3166-1 alpha-2 preferred. Alpha-3 (`VNM`) and full names (`Vietnam`) are accepted and normalized to alpha-2.
`incorporation_date`	string	Yes	ISO `YYYY-MM-DD`
`address`	string	Yes	Registered company address
`email`	string	No	Business email
`phone`	string	No	Business phone number
`website`	string	No	Business website
`nature_of_business`	string	Yes	What the company does: industry, products, services, customers, business model
`geographic_scope`	string[]	Yes	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.
`persons`	object[]	Yes	Legal representative and directors — see Persons
`documents`	object[]	Yes	Company documents, types `1`–`9` — see Documents

Do not send an id. The record id is generated by Holdstation Pay and returned in the response.

Persons

Each entry in persons[] is one legal representative or director. Field names match the Partner Customer KYC API.

Field	Type	Required	Notes
`role`	int enum	Yes	`1` = Legal representative, `2` = Director. Exactly one person must have `role = 1`.
`name`	string	Yes	Full name
`date_of_birth`	string	Yes	ISO `YYYY-MM-DD`
`email`	string	No	Email
`phone`	string	No	Phone number
`address`	string	Yes	Residential address
`id_number`	string	Yes	Identity document number
`id_type`	int enum	Yes	`1` = Citizen ID, `2` = Passport
`sex`	int enum	Yes	`1` = Male, `2` = Female, `3` = Other
`nationality`	string	Yes	ISO 3166-1 alpha-2 preferred. Alpha-3 and full names are accepted and normalized.
`date_of_issue`	string	No	Identity document issue date, ISO `YYYY-MM-DD`
`date_of_expiry`	string	No	Identity document expiry date, ISO `YYYY-MM-DD`
`documents`	object[]	Yes	Exactly one identity document, of type `10` or `11`, matching `id_type`

A person whose nationality differs from the company’s incorporation_country must use a passport — id_type: 2 with a type 10 document. See Submission Rules.

Documents

The same document object is used in both documents[] and persons[].documents[] — only the accepted type values differ.

Field	Type	Required	Notes
`type`	int enum	Yes	See Document Types
`files`	object[]	Yes	Up to 10 files per document — see Files. An empty array is accepted by the API, but a document with no file cannot be reviewed.
`document_number`	string	Conditional	Required for type `4` (import/export licence). Not needed for other types.
`date_of_issue`	string	No	ISO `YYYY-MM-DD`
`date_of_expiry`	string	No	ISO `YYYY-MM-DD`

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 of `10`/`11` per person	`persons[].documents[]`
`11`	Citizen ID	One of `10`/`11` per person	`persons[].documents[]`

Types 1–9 are valid only in the top-level documents[]; types 10 and 11 are valid only in persons[].documents[]. Using a type in the wrong array is rejected with INVALID_DOCUMENT_TYPE.

Types 4 and 5 are conditional on the company importing, exporting, or selling physical products, but no request field declares that — they are accepted when present and never demanded.

Files

Field	Type	Required	Notes
`filename`	string	Yes	Original filename
`content_type`	string	Yes	`application/pdf`, `image/jpeg`, `image/png`, or `image/heic`
`data`	string	Yes	Base64-encoded file contents. Must decode to at least one byte and must match `content_type`.

data carries the file itself. A storage path, URL, or reference is not accepted — Holdstation Pay cannot fetch files from a location you supply, and a file sent that way is rejected with FILE_CORRUPT.

See Submitting Documents for encoding rules and size limits.

Response-Only Fields

GET /partners/kyb/{id} echoes every submitted field at the same path, plus:

Field	Type	Notes
`id`	string	Server-generated record id
`partner_id`	string	The partner that owns the record
`reference_id`	string	Your id for the subject, or the one Holdstation Pay generated
`status`	int enum	`1` = Pending, `2` = Approved, `3` = Rejected
`rejection_reason`	string	Set when `status` is `3`, empty string otherwise
`submitted_at`	string	ISO 8601 timestamp
`reviewed_at`	string	ISO 8601 timestamp. `null` while pending.

Inside documents[].files[] and persons[].documents[].files[], the data field is replaced by:

Field	Type	Notes
`file_ref`	string	Opaque reference to the stored file: `f_` followed by 12 hex characters
`filename`	string	Original filename
`content_type`	string	MIME type of the stored file
`size`	integer	Size in bytes of the decoded file

Getting Started

Core Concepts

Widget Integration

Partner Merchant Virtual Account

Partner Business KYB

Partner Customer KYC

Request Signing

Business Fields

Persons

Documents

Document Types

Files

Response-Only Fields

​Business Fields

​Persons

​Documents

​Document Types

​Files

​Response-Only Fields

Business Fields

Persons

Documents

Document Types

Files

Response-Only Fields