{
"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..." }
]
}
]
}
{
"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"
}
}
}
{
"error": "invalid request",
"error_code": "BAD_REQUEST",
"message": "Invalid parameters"
}
{
"error": "unauthorized",
"error_code": "UNAUTHORIZED",
"message": "Invalid or missing signature"
}
{
"error": "CONFLICT",
"message": "A pending or approved KYB record already exists for this subject",
"detail": ""
}
{
"error": "UNSUPPORTED_MEDIA_TYPE",
"message": "File type not accepted",
"detail": ""
}
{
"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\"}]}"
}
Partner Business KYB
Submit KYB
Submit a business verification (KYB) record for your partner account or a merchant under it.
POST
/
partners
/
kyb
{
"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..." }
]
}
]
}
{
"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"
}
}
}
{
"error": "invalid request",
"error_code": "BAD_REQUEST",
"message": "Invalid parameters"
}
{
"error": "unauthorized",
"error_code": "UNAUTHORIZED",
"message": "Invalid or missing signature"
}
{
"error": "CONFLICT",
"message": "A pending or approved KYB record already exists for this subject",
"detail": ""
}
{
"error": "UNSUPPORTED_MEDIA_TYPE",
"message": "File type not accepted",
"detail": ""
}
{
"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\"}]}"
}
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 for the lifecycle, the Field Reference for every field, Submission Rules for the cross-field checks, and Submitting Documents for file rules.
Authentication
string
required
Your partner app key.
string
required
Base64-encoded Ed25519 signature of the sign data.
string
required
Unix timestamp (seconds) of the request. Must be within 60 seconds of server time.
Body Parameters
integer
required
1 = partner (self), 2 = sub-merchant.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.string
required
Company name exactly as on the incorporation document.
string
required
Business registration / incorporation number.
string
required
ISO 3166-1 alpha-2 preferred. Alpha-3 (
VNM) and full names (Vietnam) are accepted and normalized to alpha-2.string
required
Incorporation date in ISO
YYYY-MM-DD format.string
required
Registered company address.
string
Business email.
string
Business phone number.
string
Business website.
string
required
What the company does: industry, products, services, customers, business model.
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.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.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.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 withMISSING_LEGAL_REPRESENTATIVE. - A person whose
nationalitydiffers fromincorporation_countrymust useid_type: 2with a type10document. - 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 withFILE_CORRUPT. Each file is capped at 10 MB decoded, the body at 40 MB, and a submission at 30 documents and 20 persons.
{
"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..." }
]
}
]
}
{
"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"
}
}
}
{
"error": "invalid request",
"error_code": "BAD_REQUEST",
"message": "Invalid parameters"
}
{
"error": "unauthorized",
"error_code": "UNAUTHORIZED",
"message": "Invalid or missing signature"
}
{
"error": "CONFLICT",
"message": "A pending or approved KYB record already exists for this subject",
"detail": ""
}
{
"error": "UNSUPPORTED_MEDIA_TYPE",
"message": "File type not accepted",
"detail": ""
}
{
"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\"}]}"
}