KYC Management - Holdstation Pay

Authentication

KYC endpoints use the same Ed25519 signed-API scheme as the MID endpoints — Partner-App-Key, X-HSPay-Signature, and X-HSPay-Timestamp headers. See Request Signing.

Fields

Field	Type	Required	Notes
`id`	string (path)	Yes	Partner-provided unique id for this customer; this is the `kyc_id` used on orders
`name`	string	Yes	Full name
`email`	string	Conditional	At least one of `email` or `phone` must be provided
`phone`	string	Conditional	At least one of `email` or `phone` must be provided
`address`	string	Yes	Residential address
`id_number`	string	Yes	Identity document number
`id_type`	int enum	Yes	Only `1` = Citizen ID is currently supported
`sex`	int enum	Yes	`1` = Male, `2` = Female, `3` = Other
`nationality`	string	Yes	Nationality
`date_of_issue`	string	Yes	Identity document issue date, ISO `YYYY-MM-DD`
`date_of_expiry`	string	Yes	Identity document expiry date, ISO `YYYY-MM-DD`

All fields marked Yes are mandatory. email and phone are conditional: at least one of them must be provided, but you don’t need both. A create or update is rejected with MISSING_REQUIRED_FIELD if a required field is empty (or, for id_type / sex, left unspecified / 0).

Endpoints

The request body is the same for create and update:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+84123456789",
  "address": "123 Le Loi, District 1, Ho Chi Minh City",
  "id_number": "012345678",
  "id_type": 1,
  "sex": 2,
  "nationality": "VN",
  "date_of_issue": "2020-01-01",
  "date_of_expiry": "2030-01-01"
}

Method	Path	Description
`POST`	`/partners/kycs/{id}`	Create KYC record. Fails with `409 Conflict` if the id already exists.
`PUT`	`/partners/kycs/{id}`	Update KYC record. Fails with `404 Not Found` if the id is unknown.
`GET`	`/partners/kycs/{id}`	Get KYC record
`GET`	`/partners/kycs`	List KYC records, paged. `page_size` is capped at `100`.