> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/institution-api/kyb.md).

# KYB

Platform KYB submission and status; channel deposit-account onboarding (channel KYB).

## Submit platform KYB

> Submit company/representative information for a sub-account's \*\*platform\
> KYB\*\*. A \`userId\` has a single platform KYB application; resubmitting\
> updates it while it is still under review. Once \`APPROVED\`, it can no\
> longer be resubmitted.\
> \
> Validation (key validity + unconditional required + enum) passing returns\
> \`SUBMITTED\`; otherwise \`P\_PAY\_OPEN\_API\_INVALID\_ARGUMENT\` and nothing is\
> stored.\
> \
> Platform KYB must reach status \`APPROVED\` before any channel deposit\
> onboarding; all \`wire/\*\` endpoints require the \`userId\`'s platform KYB to\
> be \`APPROVED\` (otherwise \`P\_PAY\_OPEN\_API\_INTERNAL\_KYB\_NOT\_APPROVED\`).\
> \
> \## Submission structure\
> \
> \`\`\`json\
> {\
>   "userId": "88001234-....",\
>   "subject": { "fields": \[ { "key": "subject.legalNameEn", "value": "Acme Ltd." } ] },\
>   "representatives": \[ { "representativeRef": "PERSON-01", "fields": \[ { "key": "representative.firstName", "value": "..." } ] } ],\
>   "documents": \[ { "purpose": "subject.sourceOfFundsProof", "fileId": "...", "scope": "SUBJECT" },\
>                  { "purpose": "representative.passport", "fileId": "...", "scope": "REPRESENTATIVE", "representativeRef": "PERSON-01" } ]\
> }\
> \`\`\`\
> \
> \- Subject (company) fields use the \`subject.\` prefix; each is one\
>   \`{ "key": "...", "value": "..." }\` under \`subject.fields\`.\
> \- Each related natural person uses the \`representative.\` prefix; submit one\
>   entry per person under \`representatives\[]\`, distinguished by the\
>   \`representativeRef\` property (a stable per-person id, \*\*not\*\* a\
>   \`fields\[]\` key). Keep it unchanged across supplements.\
>   \`subject.signerPersonRefId\` references this value.\
> \- Documents share the same key space (their key is the document's purpose)\
>   and carry a \`fileId\` - upload first (see File endpoints), then reference\
>   by \`fileId\`. Any \`fileId\` you reference must belong to this \`userId\`.\
> \
> \# Platform KYB Field Reference\
> \
> The canonical fields and documents accepted by \`POST /kyb/create\`. Applies\
> to companies registered in \*\*Hong Kong (HK)\*\* or the \*\*United States\
> (US)\*\*.\
> \
> \## Required markers\
> \
> \| Marker | Meaning |\
> \|--------|---------|\
> \| \*\*M\*\* | Mandatory - a missing value fails validation (\`P\_PAY\_OPEN\_API\_INVALID\_ARGUMENT\`). |\
> \| \*\*C\*\* | Conditional - required when the trigger in the description holds. |\
> \| \*\*O\*\* | Optional - providing it speeds up review; omitting it does not block. |\
> \
> The \`HK\` / \`US\` columns give the marker per jurisdiction\
> (\`subject.country\`). \`N/A\` means the field is ignored for that\
> jurisdiction. Files are submitted as \`documents\[]\` with the document's\
> canonical key as \`purpose\` and a \`fileId\`.\
> \
> \## 1. Subject fields (\`subject.\*\`)\
> \
> \| Key | HK | US | Rules |\
> \|-----|:--:|:--:|-------|\
> \| \`subject.country\` | M | M | Registration jurisdiction. \`HK\` / \`US\`. Drives all validation. |\
> \| \`subject.legalNameEn\` | M | M | Legal English name, <=200. Must match the registration document exactly (incl. \`Limited\`/\`Ltd.\`/\`Inc.\` suffix). Non-Latin names need an official English translation. |\
> \| \`subject.legalNameCn\` | O | N/A | Legal Chinese name, <=100. HK companies registered in Chinese should provide it; N/A for US. |\
> \| \`subject.registrationNo\` | M | M | HK: Business Registration No.; US: IRS EIN (format \`XX-XXXXXXX\`). <=32. |\
> \| \`subject.registrationNoType\` | M | M | \`BRN\` (HK) / \`EIN\` (US). Must match \`subject.country\`. |\
> \| \`subject.businessType\` | M | M | Org form (enum below). Also determines which US charter document is required. |\
> \| \`subject.incorporationDate\` | M | M | \`yyyy-MM-dd\`. Companies incorporated < 6 months may enter enhanced due diligence. |\
> \| \`subject.incorporationState\` | N/A | M | US state code (e.g. \`DE\`, \`CA\`). US only. |\
> \| \`subject.email\` | M | M | Official business email, <=128. A free-email domain (gmail/qq/163...) triggers manual review. |\
> \| \`subject.phone.countryCode\` | C | C | Intl. dialing code without \`+\` (e.g. \`852\`, \`1\`). Required if phone is provided. |\
> \| \`subject.phone.number\` | C | C | Required if phone is provided. <=20. |\
> \| \`subject.website\` | O | O | Must include scheme (\`https\://\`), <=256. Recommended for e-commerce/platform businesses. |\
> \| \`subject.notifyUrl\` | O | O | Review-result callback URL. |\
> \| \`subject.registeredAddress.addressLine1\` | M | M | Street + number, <=200. \*\*No P.O. Box\*\*; US must include a street number. |\
> \| \`subject.registeredAddress.addressLine2\` | O | O | Room/floor/unit, <=200. |\
> \| \`subject.registeredAddress.city\` | M | M | <=100. |\
> \| \`subject.registeredAddress.state\` | O | M | 2-letter state code (e.g. \`NY\`). US mandatory; HK may omit. |\
> \| \`subject.registeredAddress.postalCode\` | O | M | US mandatory; HK has no postal codes. |\
> \| \`subject.registeredAddress.countryCode\` | M | M | ISO 3166-1 alpha-2. |\
> \| \`subject.operatingAddressSameAsRegistered\` | M | M | \`true\` / \`false\`. When \`true\`, omit \`operatingAddress\`. |\
> \| \`subject.operatingAddress.\*\` | C | C | Same sub-fields as \`registeredAddress\`. Required when \`operatingAddressSameAsRegistered = false\`. |\
> \| \`subject.businessDescription\` | M | M | Concrete description of products/services, <=500. Vague terms ("trading", "consulting") are rejected for supplement. |\
> \| \`subject.accountPurpose.cryptoTrading\` | O | O | \`true\`/\`false\`. At least one \`accountPurpose.\*\` should be \`true\`. |\
> \| \`subject.accountPurpose.fiatDeposit\` | O | O | \`true\`/\`false\`. |\
> \| \`subject.accountPurpose.fiatWithdrawal\` | O | O | \`true\`/\`false\`. |\
> \| \`subject.accountPurpose.cardIssuing\` | O | O | \`true\`/\`false\`. |\
> \| \`subject.accountPurpose.crossBorderPayment\` | O | O | \`true\`/\`false\`. |\
> \| \`subject.accountPurpose.fxConversion\` | O | O | \`true\`/\`false\`. |\
> \| \`subject.accountPurpose.payroll\` | O | O | \`true\`/\`false\`. |\
> \| \`subject.accountPurpose.other\` | O | O | \`true\`/\`false\`; describe in \`businessDescription\`. |\
> \| \`subject.monthlyDepositLimit.amount\` | M | M | Decimal string, <=2 decimals. Recommended in USD. |\
> \| \`subject.monthlyDepositLimit.currency\` | M | M | ISO 4217. |\
> \| \`subject.monthlyWithdrawalLimit.amount\` | M | M | Decimal string, <=2 decimals. |\
> \| \`subject.monthlyWithdrawalLimit.currency\` | M | M | ISO 4217. |\
> \| \`subject.pepDeclaration.hasPepRelation\` | M | M | \`true\`/\`false\`. Whether any director/shareholder/UBO (or close relation) is/was a politically exposed person. |\
> \| \`subject.pepDeclaration.description\` | C | C | Required when \`hasPepRelation = true\`, <=500. Names, positions, tenure. |\
> \| \`subject.ownershipDeclaration.hasShareholderOver25Percent\` | C | C | \`true\`/\`false\`. Required when no document evidencing the ownership structure is submitted. When \`true\`, \`representatives\[]\` must include at least one person with \`role.responsibility = ULTIMATE\_BENEFICIAL\_OWNER\`. |\
> \| \`subject.ownershipDeclaration.hasNomineeShareholder\` | O | O | \`true\`/\`false\`. If \`true\`, disclose the ultimate beneficial owner. |\
> \| \`subject.highRiskCountryExposure.involved\` | O | O | \`true\`/\`false\`. Whether business touches FATF high-risk jurisdictions. |\
> \| \`subject.highRiskCountryExposure.description\` | C | C | Required when \`involved = true\`, <=500. |\
> \| \`subject.termsAgreed\` | M | M | Must be \`true\`, else the application is rejected. |\
> \| \`subject.dataUsageAgreed\` | M | M | Must be \`true\` (authorizes third-party data verification). |\
> \| \`subject.serviceAgreementType\` | M | M | \`FULL\` / \`RECIPIENT\` (enum below). |\
> \| \`subject.signerPersonRefId\` | M | M | Must equal the \`representativeRef\` of the person designated as the authorized signer. |\
> \| \`subject.agreedAt\` | M | M | ISO 8601 (e.g. \`2026-08-25T10:12:33Z\`). |\
> \| \`subject.deviceData.ipAddress\` | M | M | Signer's public IP at consent time (IPv6-compatible), <=45. |\
> \| \`subject.deviceData.userAgent\` | M | M | Signer's User-Agent, <=512. |\
> \
> \## 2. Subject documents (\`subject.\*\`)\
> \
> Value is a \`fileId\`. Required matrix by jurisdiction:\
> \
> \| Key | HK | US | Notes |\
> \|-----|:--:|:--:|-------|\
> \| \`subject.businessRegistrationCertificate\` | M | N/A | Business Registration Certificate (BR). |\
> \| \`subject.businessFormation\` | M | M | Certificate of Incorporation (HK CI / US Certificate of Incorporation, issued by the Secretary of State). |\
> \| \`subject.incorporationFormNnc1\` | C | N/A | Incorporation Form NNC1. Note 1. |\
> \| \`subject.annualReturnNar1\` | C | N/A | Annual Return NAR1. Note 1. |\
> \| \`subject.einConfirmationLetter\` | N/A | M | IRS EIN confirmation letter (CP575 / 147C). |\
> \| \`subject.bylaws\` | N/A | C | Charter - when \`businessType\` is a corporation subtype (\`B\_CORPORATION\` / \`C\_CORPORATION\` / \`CLOSE\_CORPORATION\` / \`S\_CORPORATION\`). Note 4. |\
> \| \`subject.operatingAgreement\` | N/A | C | Charter - when \`businessType = LLC\`, or the merged fallback when \`businessType\` is not provided. Note 4. |\
> \| \`subject.partnershipAgreement\` | N/A | C | Charter - when \`businessType = LLP\` / \`LP\` / \`GENERAL\_PARTNERSHIP\`. Note 4. |\
> \| \`subject.registerOfDirectors\` | C | C | Register of directors. Note 2. |\
> \| \`subject.ownershipProof\` | C | C | Register of shareholders. Note 2. |\
> \| \`subject.shareholdingStructureChart\` | C | C | Shareholding structure chart. Note 2, Note 3. |\
> \| \`subject.certificateOfGoodStanding\` | N/A | O | Certificate of good standing. |\
> \| \`subject.financialStatements\` | O | O | Financial statements. |\
> \| \`subject.authorizationLetter\` | O | O | Authorization letter. |\
> \| \`subject.sourceOfFundsProof\` | M | M | Source-of-funds proof - see Note 5. |\
> \| \`subject.supportiveOther\` | O | O | Other supporting materials. |\
> \| \`subject.bankStatement\` | O | O | Address proof: bank statement. |\
> \| \`subject.utilityBill\` | O | O | Address proof: utility bill. |\
> \| \`subject.leaseAgreement\` | O | O | Address proof: lease agreement. |\
> \| \`subject.taxNotice\` | O | O | Address proof: tax authority notice. |\
> \| \`subject.addressProofOther\` | O | O | Address proof: other. |\
> \
> \*\*Conditional rules:\*\*\
> \
> \- \*\*Note 1 (HK charter docs):\*\* submit at least one of\
> &#x20; \`incorporationFormNnc1\` / \`annualReturnNar1\`. If incorporated over a\
> &#x20; year, \`annualReturnNar1\` (latest directors/shareholders/address) is\
> &#x20; preferred.\
> \- \*\*Note 2 (ownership & directors):\*\* submit at least one of\
> &#x20; \`registerOfDirectors\` / \`ownershipProof\` / \`shareholdingStructureChart\`\
> &#x20; that fully shows directors and ownership. If already evidenced by\
> &#x20; NNC1/NAR1 (HK) or the charter document (US), it may be omitted, and\
> &#x20; \`subject.ownershipDeclaration.\*\` may then also be omitted.\
> \- \*\*Note 3:\*\* if none of the above shows the full ownership chain (e.g.\
> &#x20; multi-tier holding), \`shareholdingStructureChart\` will be requested via\
> &#x20; supplement.\
> \- \*\*Note 4 (US charter):\*\* submit the charter document matching\
> &#x20; \`businessType\` - corporation subtypes (\`B\_CORPORATION\` /\
> &#x20; \`C\_CORPORATION\` / \`CLOSE\_CORPORATION\` / \`S\_CORPORATION\`) -> \`bylaws\`;\
> &#x20; \`LLC\` -> \`operatingAgreement\`; \`LLP\` / \`LP\` / \`GENERAL\_PARTNERSHIP\` ->\
> &#x20; \`partnershipAgreement\`. Only one, matching the true org form.\
> &#x20; (\`operatingAgreement\` also serves as the fallback when the specific\
> &#x20; charter type is unclear.)\
> \- \*\*Note 5 (source of funds):\*\* mandatory. Acceptable forms include recent\
> &#x20; 6-month corporate bank statements, audited financials, key trade\
> &#x20; contracts + invoices, capital-contribution proof, or investment\
> &#x20; agreements + receipts. Multiple entries allowed (at least one). An\
> &#x20; account-balance screenshot alone is insufficient - the funds' formation\
> &#x20; chain must be shown.\
> \
> \*\*Address proof:\*\* required when\
> \`operatingAddressSameAsRegistered = false\`, or when the submitted\
> registration documents do not state an address. Provide via the\
> \`subject.bankStatement\` / \`utilityBill\` / \`leaseAgreement\` / \`taxNotice\` /\
> \`addressProofOther\` keys; issued within the last 3 months.\
> \
> \## 3. Representative fields (\`representative.\*\`)\
> \
> One set per person, distinguished by the \`representativeRef\` property. The\
> per-person id is the \`representativeRef\` property of each\
> \`representatives\[]\` entry, \*\*not\*\* a \`fields\[]\` key.\
> \
> \| Key | HK | US | Rules |\
> \|-----|:--:|:--:|-------|\
> \| \`representativeRef\` \*(property - not a \`fields\[]\` key)\* | M | M | Stable per-person id in your system; keep unchanged across supplements. Supplied as the \`representativeRef\` property of each \`representatives\[]\` entry - do \*\*not\*\* place it inside \`fields\`. \`subject.signerPersonRefId\` references this value. |\
> \| \`representative.role.responsibility\` | O | O | The person's responsibility relative to the company - \*\*single value\*\* from the enum: \`ULTIMATE\_BENEFICIAL\_OWNER\` / \`AUTHORIZED\_REPRESENTATIVE\` / \`DIRECTOR\`. |\
> \| \`representative.firstName\` | M | M | English first name, <=100. Must match the ID exactly. |\
> \| \`representative.middleName\` | O | O | English middle name, <=100. Provide if present on the ID. |\
> \| \`representative.lastName\` | M | M | English last name, <=100. Must match the ID exactly. |\
> \| \`representative.fullNameCn\` | O | N/A | Chinese name, <=50. HK: provide if the ID carries a Chinese name. |\
> \| \`representative.jobTitle\` | M | M | Title (e.g. Director, CEO), <=100. |\
> \| \`representative.birthDate\` | M | M | \`yyyy-MM-dd\`. Must match the ID; must be >= 18 years old. |\
> \| \`representative.nationality\` | M | M | ISO 3166-1 alpha-2. |\
> \| \`representative.ownershipPercentage\` | C | C | Required when \`role.responsibility = ULTIMATE\_BENEFICIAL\_OWNER\`. \`0.01\`-\`100\`, <=2 decimals; look-through actual percentage. |\
> \| \`representative.residentialAddress.addressLine1\` | M | M | Actual residential address (not temporary), <=200. |\
> \| \`representative.residentialAddress.addressLine2\` | O | O | <=200. |\
> \| \`representative.residentialAddress.city\` | M | M | <=100. |\
> \| \`representative.residentialAddress.state\` | O | M | US mandatory (2-letter state code). |\
> \| \`representative.residentialAddress.postalCode\` | O | M | US mandatory. |\
> \| \`representative.residentialAddress.countryCode\` | M | M | ISO 3166-1 alpha-2. |\
> \| \`representative.email\` | M | M | Required for every person, <=128 (used for verification-code delivery). |\
> \| \`representative.phone.countryCode\` | O | O | Recommended for the primary contact person. |\
> \| \`representative.phone.number\` | O | O | Recommended for the primary contact person. |\
> \| \`representative.identityDocument.ssn\` | N/A | M | US: personal tax id (SSN/ITIN) for every person; N/A for HK. |\
> \| \`representative.identityDocument.idType\` | M | M | Enum below. |\
> \| \`representative.identityDocument.idNumber\` | M | M | <=64. |\
> \| \`representative.identityDocument.issuingCountry\` | M | M | ISO 3166-1 alpha-2. |\
> \| \`representative.identityDocument.issueDate\` | O | O | \`yyyy-MM-dd\`. |\
> \| \`representative.identityDocument.expiryDate\` | M | M | \`yyyy-MM-dd\`. Long-validity IDs use \`9999-12-31\`. An already-expired ID fails validation. |\
> \| \`representative.ownershipAttestedAt\` | C | C | ISO 8601. Required when \`subject.ownershipDeclaration.hasShareholderOver25Percent\` has a value. |\
> \
> \## 4. Representative documents (\`representative.\*\`)\
> \
> Value is a \`fileId\`. ID-document files are routed by\
> \`identityDocument.idType\` (see the Role/ID enum below).\
> \
> \| Key | Req | Notes |\
> \|-----|:--:|-------|\
> \| \`representative.passport\` | C | Passport photo page (front only) - when \`idType = PASSPORT\`. |\
> \| \`representative.idCardFront\` / \`representative.idCardBack\` | C | Both required for card-style IDs - see the idType routing note below. |\
> \| \`representative.driversLicenseFront\` / \`representative.driversLicenseBack\` | C | Both required when \`idType = DRIVERS\_LICENSE\`. |\
> \| \`representative.taxIdDocument\` | C | Tax-id proof (SSN / ITIN); provide together with \`representative.identityDocument.ssn\` for US persons. |\
> \| \`representative.proofOfAddress\` | C | Required when the residential address differs from the ID's stated address. |\
> \| \`representative.photoHoldingId\` | O | Requested by risk control when fraud is suspected. |\
> \| \`representative.liveSelfie\` | O | As above. |\
> \| \`representative.appointmentDocument\` | O | Appointment/authorization document. |\
> \| \`representative.nameChangeCertificate\` | C | Required when the ID name differs from the declared name. |\
> \| \`representative.supportiveOther\` | O | Other supporting materials. |\
> \
> \## 5. Enums\
> \
> Values below are the exact accepted values. The subset actually allowed for\
> a given channel/country is returned by the requirements flow - do not\
> assume every value is accepted everywhere.\
> \
> \- \*\*\`subject.country\`\*\*: \`HK\`, \`US\`.\
> \- \*\*\`subject.registrationNoType\`\*\*: \`BRN\` (HK), \`EIN\` (US).\
> \- \*\*\`subject.businessType\`\*\* (single list, not split by jurisdiction):\
> &#x20; \`B\_CORPORATION\`, \`C\_CORPORATION\`, \`CLOSE\_CORPORATION\`, \`S\_CORPORATION\`,\
> &#x20; \`LLC\`, \`LLP\`, \`LP\`, \`GENERAL\_PARTNERSHIP\`, \`SOLE\_PROPRIETOR\`, \`TRUST\`,\
> &#x20; \`COOPERATIVE\`, \`NONPROFIT\_CORPORATION\`, \`OTHER\`. \`OTHER\` requires an\
> &#x20; accompanying description.\
> \- \*\*\`subject.serviceAgreementType\`\*\*: \`FULL\` (direct service\
> &#x20; relationship), \`RECIPIENT\` (payee only, no direct relationship).\
> \- \*\*\`representative.role.responsibility\`\*\* (single value):\
> &#x20; \`ULTIMATE\_BENEFICIAL\_OWNER\`, \`AUTHORIZED\_REPRESENTATIVE\`, \`DIRECTOR\`.\
> \- \*\*\`representative.identityDocument.idType\`\*\*: \`PASSPORT\`,\
> &#x20; \`DRIVERS\_LICENSE\`, \`NATIONAL\_ID\`, \`STATE\_OR\_PROVINCIAL\_ID\`,\
> &#x20; \`PERMANENT\_RESIDENCY\_ID\`, \`MATRICULATE\_ID\`, \`MILITARY\_ID\`, \`VISA\`.\
> \
> \*\*ID-document files by \`idType\`:\*\* \`PASSPORT\` -> \`passport\`;\
> \`DRIVERS\_LICENSE\` -> \`driversLicenseFront\` + \`driversLicenseBack\`; all\
> other government IDs (\`NATIONAL\_ID\`, \`STATE\_OR\_PROVINCIAL\_ID\`,\
> \`PERMANENT\_RESIDENCY\_ID\`, \`MATRICULATE\_ID\`, \`MILITARY\_ID\`, \`VISA\`) ->\
> \`idCardFront\` + \`idCardBack\`.\
> \
> \*\*Address proof\*\* (which \`subject.\*\` document key to use): bank statement\
> -> \`bankStatement\`; utility bill -> \`utilityBill\`; lease ->\
> \`leaseAgreement\`; tax notice -> \`taxNotice\`; other -> \`addressProofOther\`.\
> \
> \## 6. File limits\
> \
> \| Limit | Value |\
> \|-------|-------|\
> \| Max file count per submission | 30 |\
> \| Max bytes per file | 12,582,912 (12 MB) |\
> \| Max total bytes per submission | 104,857,600 (100 MB) |\
> \| Allowed content types | \`application/pdf\`, \`image/jpeg\`, \`image/png\`, \`image/heic\` |\
> \
> \## 7. Role integrity & cross-field rules\
> \
> Submission is rejected with \`P\_PAY\_OPEN\_API\_INVALID\_ARGUMENT\` when any of\
> the following fails:\
> \
> \- \*\*Registration type matches jurisdiction:\*\* \`HK\` => \`registrationNoType = BRN\`; \`US\` => \`EIN\`.\
> \- \*\*US state present:\*\* \`US\` requires \`subject.incorporationState\`.\
> \- \*\*Operating address present\*\* when \`operatingAddressSameAsRegistered = false\`.\
> \- \*\*Every representative has an \`email\`.\*\*\
> \- \*\*Beneficial owner ownership:\*\* when \`subject.ownershipDeclaration.hasShareholderOver25Percent = true\` (or an ownership document shows a >=25% holder), at least one representative must have \`role.responsibility = ULTIMATE\_BENEFICIAL\_OWNER\`. Each such person's \`ownershipPercentage\` must be in \`(0, 100]\`, and the sum must not exceed 100.\
> \- \*\*ID not expired\*\*; ID \*\*back\*\* file present for card-style IDs and \`DRIVERS\_LICENSE\`.\
> \- \*\*Age >= 18\*\* (from \`birthDate\`).\
> \- \*\*US charter document matches \`businessType\`\*\* (see Note 4).\
> \- \*\*US personal tax id present\*\* (\`representative.identityDocument.ssn\`) for every representative.\
> \- \*\*Required company documents present\*\* per the matrix; source-of-funds proof present; ownership information resolvable (either an ownership document or \`subject.ownershipDeclaration.\*\`).\
> \- \*\*Consents accepted:\*\* \`termsAgreed\` and \`dataUsageAgreed\` are \`true\`.\
> \
> \*\*Errors:\*\*\
> \
> \| Error Code | Description |\
> \|------------|-------------|\
> \| \`P\_PAY\_OPEN\_API\_KYB\_ALREADY\_APPROVED\` | Platform KYB is already \`APPROVED\` and can no longer be resubmitted. |\
> \| \`P\_PAY\_OPEN\_API\_KYB\_SUBMIT\_IN\_PROGRESS\` | A submission for this \`userId\` is already being processed; retry later. |<br>

````json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"KYB","description":"Platform KYB submission and status; channel deposit-account onboarding (channel KYB)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}}},"schemas":{"KybCreateRequest":{"type":"object","required":["userId"],"description":"Platform KYB submission. `subject`, `representatives`, and `documents`\ncarry canonical keys as documented in the Platform KYB Field Reference.\n","properties":{"userId":{"type":"string","description":"Sub-account UUID. A `userId` has a single platform KYB application."},"subject":{"$ref":"#/components/schemas/KybFieldGroup"},"representatives":{"type":"array","items":{"$ref":"#/components/schemas/KybRepresentative"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/KybDocument"}}}},"KybFieldGroup":{"type":"object","description":"A group of canonical key/value fields: `{ fields: [ { key, value } ] }`.","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/KeyValue"}}}},"KeyValue":{"type":"object","description":"A generic key/value pair.","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"KybRepresentative":{"type":"object","description":"One natural person, identified by `representativeRef`.","properties":{"representativeRef":{"type":"string","description":"Stable per-person id; keep unchanged across supplements."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/KeyValue"}}}},"KybDocument":{"type":"object","description":"A KYB document reference. Upload the file first, then reference by `fileId`.","properties":{"purpose":{"type":"string","description":"The document's canonical key (e.g. `subject.sourceOfFundsProof`)."},"fileId":{"type":"string"},"scope":{"type":"string","enum":["SUBJECT","REPRESENTATIVE"]},"representativeRef":{"type":"string","description":"Required when `scope = REPRESENTATIVE`."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/kyb/create":{"post":{"tags":["KYB"],"summary":"Submit platform KYB","description":"Submit company/representative information for a sub-account's **platform\nKYB**. A `userId` has a single platform KYB application; resubmitting\nupdates it while it is still under review. Once `APPROVED`, it can no\nlonger be resubmitted.\n\nValidation (key validity + unconditional required + enum) passing returns\n`SUBMITTED`; otherwise `P_PAY_OPEN_API_INVALID_ARGUMENT` and nothing is\nstored.\n\nPlatform KYB must reach status `APPROVED` before any channel deposit\nonboarding; all `wire/*` endpoints require the `userId`'s platform KYB to\nbe `APPROVED` (otherwise `P_PAY_OPEN_API_INTERNAL_KYB_NOT_APPROVED`).\n\n## Submission structure\n\n```json\n{\n  \"userId\": \"88001234-....\",\n  \"subject\": { \"fields\": [ { \"key\": \"subject.legalNameEn\", \"value\": \"Acme Ltd.\" } ] },\n  \"representatives\": [ { \"representativeRef\": \"PERSON-01\", \"fields\": [ { \"key\": \"representative.firstName\", \"value\": \"...\" } ] } ],\n  \"documents\": [ { \"purpose\": \"subject.sourceOfFundsProof\", \"fileId\": \"...\", \"scope\": \"SUBJECT\" },\n                 { \"purpose\": \"representative.passport\", \"fileId\": \"...\", \"scope\": \"REPRESENTATIVE\", \"representativeRef\": \"PERSON-01\" } ]\n}\n```\n\n- Subject (company) fields use the `subject.` prefix; each is one\n  `{ \"key\": \"...\", \"value\": \"...\" }` under `subject.fields`.\n- Each related natural person uses the `representative.` prefix; submit one\n  entry per person under `representatives[]`, distinguished by the\n  `representativeRef` property (a stable per-person id, **not** a\n  `fields[]` key). Keep it unchanged across supplements.\n  `subject.signerPersonRefId` references this value.\n- Documents share the same key space (their key is the document's purpose)\n  and carry a `fileId` - upload first (see File endpoints), then reference\n  by `fileId`. Any `fileId` you reference must belong to this `userId`.\n\n# Platform KYB Field Reference\n\nThe canonical fields and documents accepted by `POST /kyb/create`. Applies\nto companies registered in **Hong Kong (HK)** or the **United States\n(US)**.\n\n## Required markers\n\n| Marker | Meaning |\n|--------|---------|\n| **M** | Mandatory - a missing value fails validation (`P_PAY_OPEN_API_INVALID_ARGUMENT`). |\n| **C** | Conditional - required when the trigger in the description holds. |\n| **O** | Optional - providing it speeds up review; omitting it does not block. |\n\nThe `HK` / `US` columns give the marker per jurisdiction\n(`subject.country`). `N/A` means the field is ignored for that\njurisdiction. Files are submitted as `documents[]` with the document's\ncanonical key as `purpose` and a `fileId`.\n\n## 1. Subject fields (`subject.*`)\n\n| Key | HK | US | Rules |\n|-----|:--:|:--:|-------|\n| `subject.country` | M | M | Registration jurisdiction. `HK` / `US`. Drives all validation. |\n| `subject.legalNameEn` | M | M | Legal English name, <=200. Must match the registration document exactly (incl. `Limited`/`Ltd.`/`Inc.` suffix). Non-Latin names need an official English translation. |\n| `subject.legalNameCn` | O | N/A | Legal Chinese name, <=100. HK companies registered in Chinese should provide it; N/A for US. |\n| `subject.registrationNo` | M | M | HK: Business Registration No.; US: IRS EIN (format `XX-XXXXXXX`). <=32. |\n| `subject.registrationNoType` | M | M | `BRN` (HK) / `EIN` (US). Must match `subject.country`. |\n| `subject.businessType` | M | M | Org form (enum below). Also determines which US charter document is required. |\n| `subject.incorporationDate` | M | M | `yyyy-MM-dd`. Companies incorporated < 6 months may enter enhanced due diligence. |\n| `subject.incorporationState` | N/A | M | US state code (e.g. `DE`, `CA`). US only. |\n| `subject.email` | M | M | Official business email, <=128. A free-email domain (gmail/qq/163...) triggers manual review. |\n| `subject.phone.countryCode` | C | C | Intl. dialing code without `+` (e.g. `852`, `1`). Required if phone is provided. |\n| `subject.phone.number` | C | C | Required if phone is provided. <=20. |\n| `subject.website` | O | O | Must include scheme (`https://`), <=256. Recommended for e-commerce/platform businesses. |\n| `subject.notifyUrl` | O | O | Review-result callback URL. |\n| `subject.registeredAddress.addressLine1` | M | M | Street + number, <=200. **No P.O. Box**; US must include a street number. |\n| `subject.registeredAddress.addressLine2` | O | O | Room/floor/unit, <=200. |\n| `subject.registeredAddress.city` | M | M | <=100. |\n| `subject.registeredAddress.state` | O | M | 2-letter state code (e.g. `NY`). US mandatory; HK may omit. |\n| `subject.registeredAddress.postalCode` | O | M | US mandatory; HK has no postal codes. |\n| `subject.registeredAddress.countryCode` | M | M | ISO 3166-1 alpha-2. |\n| `subject.operatingAddressSameAsRegistered` | M | M | `true` / `false`. When `true`, omit `operatingAddress`. |\n| `subject.operatingAddress.*` | C | C | Same sub-fields as `registeredAddress`. Required when `operatingAddressSameAsRegistered = false`. |\n| `subject.businessDescription` | M | M | Concrete description of products/services, <=500. Vague terms (\"trading\", \"consulting\") are rejected for supplement. |\n| `subject.accountPurpose.cryptoTrading` | O | O | `true`/`false`. At least one `accountPurpose.*` should be `true`. |\n| `subject.accountPurpose.fiatDeposit` | O | O | `true`/`false`. |\n| `subject.accountPurpose.fiatWithdrawal` | O | O | `true`/`false`. |\n| `subject.accountPurpose.cardIssuing` | O | O | `true`/`false`. |\n| `subject.accountPurpose.crossBorderPayment` | O | O | `true`/`false`. |\n| `subject.accountPurpose.fxConversion` | O | O | `true`/`false`. |\n| `subject.accountPurpose.payroll` | O | O | `true`/`false`. |\n| `subject.accountPurpose.other` | O | O | `true`/`false`; describe in `businessDescription`. |\n| `subject.monthlyDepositLimit.amount` | M | M | Decimal string, <=2 decimals. Recommended in USD. |\n| `subject.monthlyDepositLimit.currency` | M | M | ISO 4217. |\n| `subject.monthlyWithdrawalLimit.amount` | M | M | Decimal string, <=2 decimals. |\n| `subject.monthlyWithdrawalLimit.currency` | M | M | ISO 4217. |\n| `subject.pepDeclaration.hasPepRelation` | M | M | `true`/`false`. Whether any director/shareholder/UBO (or close relation) is/was a politically exposed person. |\n| `subject.pepDeclaration.description` | C | C | Required when `hasPepRelation = true`, <=500. Names, positions, tenure. |\n| `subject.ownershipDeclaration.hasShareholderOver25Percent` | C | C | `true`/`false`. Required when no document evidencing the ownership structure is submitted. When `true`, `representatives[]` must include at least one person with `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`. |\n| `subject.ownershipDeclaration.hasNomineeShareholder` | O | O | `true`/`false`. If `true`, disclose the ultimate beneficial owner. |\n| `subject.highRiskCountryExposure.involved` | O | O | `true`/`false`. Whether business touches FATF high-risk jurisdictions. |\n| `subject.highRiskCountryExposure.description` | C | C | Required when `involved = true`, <=500. |\n| `subject.termsAgreed` | M | M | Must be `true`, else the application is rejected. |\n| `subject.dataUsageAgreed` | M | M | Must be `true` (authorizes third-party data verification). |\n| `subject.serviceAgreementType` | M | M | `FULL` / `RECIPIENT` (enum below). |\n| `subject.signerPersonRefId` | M | M | Must equal the `representativeRef` of the person designated as the authorized signer. |\n| `subject.agreedAt` | M | M | ISO 8601 (e.g. `2026-08-25T10:12:33Z`). |\n| `subject.deviceData.ipAddress` | M | M | Signer's public IP at consent time (IPv6-compatible), <=45. |\n| `subject.deviceData.userAgent` | M | M | Signer's User-Agent, <=512. |\n\n## 2. Subject documents (`subject.*`)\n\nValue is a `fileId`. Required matrix by jurisdiction:\n\n| Key | HK | US | Notes |\n|-----|:--:|:--:|-------|\n| `subject.businessRegistrationCertificate` | M | N/A | Business Registration Certificate (BR). |\n| `subject.businessFormation` | M | M | Certificate of Incorporation (HK CI / US Certificate of Incorporation, issued by the Secretary of State). |\n| `subject.incorporationFormNnc1` | C | N/A | Incorporation Form NNC1. Note 1. |\n| `subject.annualReturnNar1` | C | N/A | Annual Return NAR1. Note 1. |\n| `subject.einConfirmationLetter` | N/A | M | IRS EIN confirmation letter (CP575 / 147C). |\n| `subject.bylaws` | N/A | C | Charter - when `businessType` is a corporation subtype (`B_CORPORATION` / `C_CORPORATION` / `CLOSE_CORPORATION` / `S_CORPORATION`). Note 4. |\n| `subject.operatingAgreement` | N/A | C | Charter - when `businessType = LLC`, or the merged fallback when `businessType` is not provided. Note 4. |\n| `subject.partnershipAgreement` | N/A | C | Charter - when `businessType = LLP` / `LP` / `GENERAL_PARTNERSHIP`. Note 4. |\n| `subject.registerOfDirectors` | C | C | Register of directors. Note 2. |\n| `subject.ownershipProof` | C | C | Register of shareholders. Note 2. |\n| `subject.shareholdingStructureChart` | C | C | Shareholding structure chart. Note 2, Note 3. |\n| `subject.certificateOfGoodStanding` | N/A | O | Certificate of good standing. |\n| `subject.financialStatements` | O | O | Financial statements. |\n| `subject.authorizationLetter` | O | O | Authorization letter. |\n| `subject.sourceOfFundsProof` | M | M | Source-of-funds proof - see Note 5. |\n| `subject.supportiveOther` | O | O | Other supporting materials. |\n| `subject.bankStatement` | O | O | Address proof: bank statement. |\n| `subject.utilityBill` | O | O | Address proof: utility bill. |\n| `subject.leaseAgreement` | O | O | Address proof: lease agreement. |\n| `subject.taxNotice` | O | O | Address proof: tax authority notice. |\n| `subject.addressProofOther` | O | O | Address proof: other. |\n\n**Conditional rules:**\n\n- **Note 1 (HK charter docs):** submit at least one of\n  `incorporationFormNnc1` / `annualReturnNar1`. If incorporated over a\n  year, `annualReturnNar1` (latest directors/shareholders/address) is\n  preferred.\n- **Note 2 (ownership & directors):** submit at least one of\n  `registerOfDirectors` / `ownershipProof` / `shareholdingStructureChart`\n  that fully shows directors and ownership. If already evidenced by\n  NNC1/NAR1 (HK) or the charter document (US), it may be omitted, and\n  `subject.ownershipDeclaration.*` may then also be omitted.\n- **Note 3:** if none of the above shows the full ownership chain (e.g.\n  multi-tier holding), `shareholdingStructureChart` will be requested via\n  supplement.\n- **Note 4 (US charter):** submit the charter document matching\n  `businessType` - corporation subtypes (`B_CORPORATION` /\n  `C_CORPORATION` / `CLOSE_CORPORATION` / `S_CORPORATION`) -> `bylaws`;\n  `LLC` -> `operatingAgreement`; `LLP` / `LP` / `GENERAL_PARTNERSHIP` ->\n  `partnershipAgreement`. Only one, matching the true org form.\n  (`operatingAgreement` also serves as the fallback when the specific\n  charter type is unclear.)\n- **Note 5 (source of funds):** mandatory. Acceptable forms include recent\n  6-month corporate bank statements, audited financials, key trade\n  contracts + invoices, capital-contribution proof, or investment\n  agreements + receipts. Multiple entries allowed (at least one). An\n  account-balance screenshot alone is insufficient - the funds' formation\n  chain must be shown.\n\n**Address proof:** required when\n`operatingAddressSameAsRegistered = false`, or when the submitted\nregistration documents do not state an address. Provide via the\n`subject.bankStatement` / `utilityBill` / `leaseAgreement` / `taxNotice` /\n`addressProofOther` keys; issued within the last 3 months.\n\n## 3. Representative fields (`representative.*`)\n\nOne set per person, distinguished by the `representativeRef` property. The\nper-person id is the `representativeRef` property of each\n`representatives[]` entry, **not** a `fields[]` key.\n\n| Key | HK | US | Rules |\n|-----|:--:|:--:|-------|\n| `representativeRef` *(property - not a `fields[]` key)* | M | M | Stable per-person id in your system; keep unchanged across supplements. Supplied as the `representativeRef` property of each `representatives[]` entry - do **not** place it inside `fields`. `subject.signerPersonRefId` references this value. |\n| `representative.role.responsibility` | O | O | The person's responsibility relative to the company - **single value** from the enum: `ULTIMATE_BENEFICIAL_OWNER` / `AUTHORIZED_REPRESENTATIVE` / `DIRECTOR`. |\n| `representative.firstName` | M | M | English first name, <=100. Must match the ID exactly. |\n| `representative.middleName` | O | O | English middle name, <=100. Provide if present on the ID. |\n| `representative.lastName` | M | M | English last name, <=100. Must match the ID exactly. |\n| `representative.fullNameCn` | O | N/A | Chinese name, <=50. HK: provide if the ID carries a Chinese name. |\n| `representative.jobTitle` | M | M | Title (e.g. Director, CEO), <=100. |\n| `representative.birthDate` | M | M | `yyyy-MM-dd`. Must match the ID; must be >= 18 years old. |\n| `representative.nationality` | M | M | ISO 3166-1 alpha-2. |\n| `representative.ownershipPercentage` | C | C | Required when `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`. `0.01`-`100`, <=2 decimals; look-through actual percentage. |\n| `representative.residentialAddress.addressLine1` | M | M | Actual residential address (not temporary), <=200. |\n| `representative.residentialAddress.addressLine2` | O | O | <=200. |\n| `representative.residentialAddress.city` | M | M | <=100. |\n| `representative.residentialAddress.state` | O | M | US mandatory (2-letter state code). |\n| `representative.residentialAddress.postalCode` | O | M | US mandatory. |\n| `representative.residentialAddress.countryCode` | M | M | ISO 3166-1 alpha-2. |\n| `representative.email` | M | M | Required for every person, <=128 (used for verification-code delivery). |\n| `representative.phone.countryCode` | O | O | Recommended for the primary contact person. |\n| `representative.phone.number` | O | O | Recommended for the primary contact person. |\n| `representative.identityDocument.ssn` | N/A | M | US: personal tax id (SSN/ITIN) for every person; N/A for HK. |\n| `representative.identityDocument.idType` | M | M | Enum below. |\n| `representative.identityDocument.idNumber` | M | M | <=64. |\n| `representative.identityDocument.issuingCountry` | M | M | ISO 3166-1 alpha-2. |\n| `representative.identityDocument.issueDate` | O | O | `yyyy-MM-dd`. |\n| `representative.identityDocument.expiryDate` | M | M | `yyyy-MM-dd`. Long-validity IDs use `9999-12-31`. An already-expired ID fails validation. |\n| `representative.ownershipAttestedAt` | C | C | ISO 8601. Required when `subject.ownershipDeclaration.hasShareholderOver25Percent` has a value. |\n\n## 4. Representative documents (`representative.*`)\n\nValue is a `fileId`. ID-document files are routed by\n`identityDocument.idType` (see the Role/ID enum below).\n\n| Key | Req | Notes |\n|-----|:--:|-------|\n| `representative.passport` | C | Passport photo page (front only) - when `idType = PASSPORT`. |\n| `representative.idCardFront` / `representative.idCardBack` | C | Both required for card-style IDs - see the idType routing note below. |\n| `representative.driversLicenseFront` / `representative.driversLicenseBack` | C | Both required when `idType = DRIVERS_LICENSE`. |\n| `representative.taxIdDocument` | C | Tax-id proof (SSN / ITIN); provide together with `representative.identityDocument.ssn` for US persons. |\n| `representative.proofOfAddress` | C | Required when the residential address differs from the ID's stated address. |\n| `representative.photoHoldingId` | O | Requested by risk control when fraud is suspected. |\n| `representative.liveSelfie` | O | As above. |\n| `representative.appointmentDocument` | O | Appointment/authorization document. |\n| `representative.nameChangeCertificate` | C | Required when the ID name differs from the declared name. |\n| `representative.supportiveOther` | O | Other supporting materials. |\n\n## 5. Enums\n\nValues below are the exact accepted values. The subset actually allowed for\na given channel/country is returned by the requirements flow - do not\nassume every value is accepted everywhere.\n\n- **`subject.country`**: `HK`, `US`.\n- **`subject.registrationNoType`**: `BRN` (HK), `EIN` (US).\n- **`subject.businessType`** (single list, not split by jurisdiction):\n  `B_CORPORATION`, `C_CORPORATION`, `CLOSE_CORPORATION`, `S_CORPORATION`,\n  `LLC`, `LLP`, `LP`, `GENERAL_PARTNERSHIP`, `SOLE_PROPRIETOR`, `TRUST`,\n  `COOPERATIVE`, `NONPROFIT_CORPORATION`, `OTHER`. `OTHER` requires an\n  accompanying description.\n- **`subject.serviceAgreementType`**: `FULL` (direct service\n  relationship), `RECIPIENT` (payee only, no direct relationship).\n- **`representative.role.responsibility`** (single value):\n  `ULTIMATE_BENEFICIAL_OWNER`, `AUTHORIZED_REPRESENTATIVE`, `DIRECTOR`.\n- **`representative.identityDocument.idType`**: `PASSPORT`,\n  `DRIVERS_LICENSE`, `NATIONAL_ID`, `STATE_OR_PROVINCIAL_ID`,\n  `PERMANENT_RESIDENCY_ID`, `MATRICULATE_ID`, `MILITARY_ID`, `VISA`.\n\n**ID-document files by `idType`:** `PASSPORT` -> `passport`;\n`DRIVERS_LICENSE` -> `driversLicenseFront` + `driversLicenseBack`; all\nother government IDs (`NATIONAL_ID`, `STATE_OR_PROVINCIAL_ID`,\n`PERMANENT_RESIDENCY_ID`, `MATRICULATE_ID`, `MILITARY_ID`, `VISA`) ->\n`idCardFront` + `idCardBack`.\n\n**Address proof** (which `subject.*` document key to use): bank statement\n-> `bankStatement`; utility bill -> `utilityBill`; lease ->\n`leaseAgreement`; tax notice -> `taxNotice`; other -> `addressProofOther`.\n\n## 6. File limits\n\n| Limit | Value |\n|-------|-------|\n| Max file count per submission | 30 |\n| Max bytes per file | 12,582,912 (12 MB) |\n| Max total bytes per submission | 104,857,600 (100 MB) |\n| Allowed content types | `application/pdf`, `image/jpeg`, `image/png`, `image/heic` |\n\n## 7. Role integrity & cross-field rules\n\nSubmission is rejected with `P_PAY_OPEN_API_INVALID_ARGUMENT` when any of\nthe following fails:\n\n- **Registration type matches jurisdiction:** `HK` => `registrationNoType = BRN`; `US` => `EIN`.\n- **US state present:** `US` requires `subject.incorporationState`.\n- **Operating address present** when `operatingAddressSameAsRegistered = false`.\n- **Every representative has an `email`.**\n- **Beneficial owner ownership:** when `subject.ownershipDeclaration.hasShareholderOver25Percent = true` (or an ownership document shows a >=25% holder), at least one representative must have `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`. Each such person's `ownershipPercentage` must be in `(0, 100]`, and the sum must not exceed 100.\n- **ID not expired**; ID **back** file present for card-style IDs and `DRIVERS_LICENSE`.\n- **Age >= 18** (from `birthDate`).\n- **US charter document matches `businessType`** (see Note 4).\n- **US personal tax id present** (`representative.identityDocument.ssn`) for every representative.\n- **Required company documents present** per the matrix; source-of-funds proof present; ownership information resolvable (either an ownership document or `subject.ownershipDeclaration.*`).\n- **Consents accepted:** `termsAgreed` and `dataUsageAgreed` are `true`.\n\n**Errors:**\n\n| Error Code | Description |\n|------------|-------------|\n| `P_PAY_OPEN_API_KYB_ALREADY_APPROVED` | Platform KYB is already `APPROVED` and can no longer be resubmitted. |\n| `P_PAY_OPEN_API_KYB_SUBMIT_IN_PROGRESS` | A submission for this `userId` is already being processed; retry later. |\n","operationId":"institutionKybCreate","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KybCreateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","description":"KYB submission status."}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
````

## Get platform KYB status

> Get the platform KYB status for a \`userId\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"KYB","description":"Platform KYB submission and status; channel deposit-account onboarding (channel KYB)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}},"UserIdQueryRequired":{"name":"userId","in":"query","required":true,"description":"Target sub-account UUID. Participates in the signature.","schema":{"type":"string"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}},"KybStatus":{"type":"object","properties":{"status":{"type":"string","description":"`SUBMITTED` / `PENDING` / `SUPPLEMENT_REQUIRED` / `APPROVED` / `REJECTED`.","enum":["SUBMITTED","PENDING","SUPPLEMENT_REQUIRED","APPROVED","REJECTED"]},"reason":{"type":"string","description":"Review conclusion code; empty before review."},"message":{"type":"string","description":"Conclusion description; empty before review."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/kyb":{"get":{"tags":["KYB"],"summary":"Get platform KYB status","description":"Get the platform KYB status for a `userId`.\n","operationId":"institutionKybGet","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/UserIdQueryRequired"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KybStatus"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get channel onboarding requirements

> Returns the items still required for channel deposit onboarding.\
> Information already provided is omitted. Representative requirements are\
> returned per contact.\
> \
> Channel KYB fields are \*\*dynamic\*\* - call this endpoint first, then fill\
> per the returned \`Requirement\` items. Do not hard-code channel field lists.\
> \
> \- \*\*\`mode\`\*\* is the source of truth for whether to submit an item:\
> &#x20; \`REQUIRED\` (must submit), \`OPTIONAL\`, or \`CONDITIONAL\`. \`CONDITIONAL\`\
> &#x20; means the item becomes required only when other fields take certain\
> &#x20; values; when unsure, submit it.\
> \- \*\*\`kind\`\*\* is \`FIELD\` or \`DOCUMENT\`. Documents are referenced by\
> &#x20; \`fileId\` (upload first); do not inline file bytes.\
> \- Representatives are grouped by \`representativeRef\`.\
> \- \`regex\` / \`example\` / \`enumValues\` on a field are for client-side\
> &#x20; validation and hints.\
> \- Documents must be submitted in full.\
> \
> Do not pass \`country\` or \`businessType\` - the requirement set follows the\
> values from your platform KYB (\`subject.country\` / \`subject.businessType\`).\
> \
> \> \*\*\`channel\` currently supports \`fvbank\` and \`straitsx\`.\*\*<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"KYB","description":"Platform KYB submission and status; channel deposit-account onboarding (channel KYB)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}},"UserIdQueryRequired":{"name":"userId","in":"query","required":true,"description":"Target sub-account UUID. Participates in the signature.","schema":{"type":"string"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}},"ChannelRequirements":{"type":"object","description":"Items still required for channel deposit onboarding.","properties":{"subjectFields":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"description":"Subject fields still missing."},"subjectDocuments":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"},"description":"Subject documents still missing (flattened, one per purpose)."},"requiresRepresentatives":{"type":"boolean"},"representatives":{"type":"array","description":"What each contact still needs, one entry per contact.","items":{"type":"object","properties":{"representativeRef":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Requirement"}}}}},"fileLimit":{"type":"object","properties":{"maxFileCount":{"type":"integer"},"maxFileBytes":{"type":"integer","format":"int64"},"maxTotalBytes":{"type":"integer","format":"int64"},"contentTypes":{"type":"array","items":{"type":"string"}}}},"tosMode":{"type":"string","enum":["NONE","HOSTED_LINK","INLINE_ACCEPT"]},"tosUrl":{"type":"string","description":"Terms URL; empty when `NONE`."},"termsVersion":{"type":"string","description":"Terms version; non-empty only for `INLINE_ACCEPT`."},"requiresBusinessType":{"type":"boolean","description":"Always `false` in this API - the business type comes from platform KYB."}}},"Requirement":{"type":"object","description":"A dynamic channel-KYB requirement item.","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["FIELD","DOCUMENT"]},"mode":{"type":"string","enum":["REQUIRED","OPTIONAL","CONDITIONAL"],"description":"Source of truth for whether to submit the item."},"label":{"type":"string"},"regex":{"type":"string"},"enumValues":{"type":"array","items":{"type":"string"}}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/wire/deposit/account/requirements":{"get":{"tags":["KYB"],"summary":"Get channel onboarding requirements","description":"Returns the items still required for channel deposit onboarding.\nInformation already provided is omitted. Representative requirements are\nreturned per contact.\n\nChannel KYB fields are **dynamic** - call this endpoint first, then fill\nper the returned `Requirement` items. Do not hard-code channel field lists.\n\n- **`mode`** is the source of truth for whether to submit an item:\n  `REQUIRED` (must submit), `OPTIONAL`, or `CONDITIONAL`. `CONDITIONAL`\n  means the item becomes required only when other fields take certain\n  values; when unsure, submit it.\n- **`kind`** is `FIELD` or `DOCUMENT`. Documents are referenced by\n  `fileId` (upload first); do not inline file bytes.\n- Representatives are grouped by `representativeRef`.\n- `regex` / `example` / `enumValues` on a field are for client-side\n  validation and hints.\n- Documents must be submitted in full.\n\nDo not pass `country` or `businessType` - the requirement set follows the\nvalues from your platform KYB (`subject.country` / `subject.businessType`).\n\n> **`channel` currently supports `fvbank` and `straitsx`.**\n","operationId":"institutionDepositAccountRequirements","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/UserIdQueryRequired"},{"name":"channel","in":"query","required":true,"description":"Channel identifier. Currently supports `fvbank` and `straitsx`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelRequirements"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Onboard a deposit account (channel KYB)

> Submit channel onboarding. Returns onboarding \`status\` only; missing/invalid\
> items are not itemized - call the requirements endpoint to learn what is\
> still missing.\
> \
> Provide \*\*all\*\* required documents in full every time. Do not pass\
> \`country\` or \`businessType\` here - they come from your platform KYB. Any\
> \`fileId\` you reference must belong to this \`userId\`.\
> \
> Requires the \`userId\`'s platform KYB to be \`APPROVED\`.\
> \
> \*\*Errors:\*\*\
> \
> \| Error Code | Description |\
> \|------------|-------------|\
> \| \`P\_PAY\_OPEN\_API\_INTERNAL\_KYB\_NOT\_APPROVED\` | Platform KYB is not approved yet; it must be approved before channel onboarding. |\
> \| \`P\_PAY\_OPEN\_API\_KYB\_ADDRESS\_REJECTED\` | Address rejected by the channel; \`data.violations\` names the rejected fields. |\
> \| \`P\_PAY\_OPEN\_API\_KYB\_DOCUMENT\_REJECTED\` | A document was rejected or a required field is missing. |\
> \| \`P\_PAY\_OPEN\_API\_KYB\_SUBJECT\_TYPE\_CONFLICT\` | Another subject type already exists for this \`userId\`. |\
> \| \`P\_PAY\_OPEN\_API\_KYB\_MANUAL\_REVIEW\_REQUIRED\` | Additional review is required; do not resubmit with altered details. |\
> \| \`P\_PAY\_OPEN\_API\_KYB\_SUBJECT\_NOT\_FOUND\` | No matching company record was found. |<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"KYB","description":"Platform KYB submission and status; channel deposit-account onboarding (channel KYB)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}}},"schemas":{"KybFieldGroup":{"type":"object","description":"A group of canonical key/value fields: `{ fields: [ { key, value } ] }`.","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/KeyValue"}}}},"KeyValue":{"type":"object","description":"A generic key/value pair.","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"KybRepresentative":{"type":"object","description":"One natural person, identified by `representativeRef`.","properties":{"representativeRef":{"type":"string","description":"Stable per-person id; keep unchanged across supplements."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/KeyValue"}}}},"KybDocument":{"type":"object","description":"A KYB document reference. Upload the file first, then reference by `fileId`.","properties":{"purpose":{"type":"string","description":"The document's canonical key (e.g. `subject.sourceOfFundsProof`)."},"fileId":{"type":"string"},"scope":{"type":"string","enum":["SUBJECT","REPRESENTATIVE"]},"representativeRef":{"type":"string","description":"Required when `scope = REPRESENTATIVE`."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/wire/deposit/account/create":{"post":{"tags":["KYB"],"summary":"Onboard a deposit account (channel KYB)","description":"Submit channel onboarding. Returns onboarding `status` only; missing/invalid\nitems are not itemized - call the requirements endpoint to learn what is\nstill missing.\n\nProvide **all** required documents in full every time. Do not pass\n`country` or `businessType` here - they come from your platform KYB. Any\n`fileId` you reference must belong to this `userId`.\n\nRequires the `userId`'s platform KYB to be `APPROVED`.\n\n**Errors:**\n\n| Error Code | Description |\n|------------|-------------|\n| `P_PAY_OPEN_API_INTERNAL_KYB_NOT_APPROVED` | Platform KYB is not approved yet; it must be approved before channel onboarding. |\n| `P_PAY_OPEN_API_KYB_ADDRESS_REJECTED` | Address rejected by the channel; `data.violations` names the rejected fields. |\n| `P_PAY_OPEN_API_KYB_DOCUMENT_REJECTED` | A document was rejected or a required field is missing. |\n| `P_PAY_OPEN_API_KYB_SUBJECT_TYPE_CONFLICT` | Another subject type already exists for this `userId`. |\n| `P_PAY_OPEN_API_KYB_MANUAL_REVIEW_REQUIRED` | Additional review is required; do not resubmit with altered details. |\n| `P_PAY_OPEN_API_KYB_SUBJECT_NOT_FOUND` | No matching company record was found. |\n","operationId":"institutionDepositAccountCreate","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","description":"Sub-account UUID."},"channel":{"type":"string","description":"Channel. Currently supports `fvbank` and `straitsx`."},"signedAgreementId":{"type":"string","description":"For `tosMode = HOSTED_LINK`."},"acceptedTerms":{"type":"boolean","description":"For `tosMode = INLINE_ACCEPT`."},"termsVersion":{"type":"string","description":"For `tosMode = INLINE_ACCEPT`."},"subject":{"$ref":"#/components/schemas/KybFieldGroup"},"representatives":{"type":"array","items":{"$ref":"#/components/schemas/KybRepresentative"}},"documents":{"type":"array","description":"Provide all required documents in full every time.","items":{"$ref":"#/components/schemas/KybDocument"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","description":"Onboarding status: `NOT_CREATED` / `SUBMITTED` / `IN_REVIEW` / `ACTION_REQUIRED` / `APPROVED` / `REJECTED`.","enum":["NOT_CREATED","SUBMITTED","IN_REVIEW","ACTION_REQUIRED","APPROVED","REJECTED"]}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get deposit-account onboarding status

> Returns the channel onboarding \`status\`. \`status = NOT\_CREATED\` means not\
> yet onboarded (not an error).<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"KYB","description":"Platform KYB submission and status; channel deposit-account onboarding (channel KYB)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}},"UserIdQueryRequired":{"name":"userId","in":"query","required":true,"description":"Target sub-account UUID. Participates in the signature.","schema":{"type":"string"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/wire/deposit/account":{"get":{"tags":["KYB"],"summary":"Get deposit-account onboarding status","description":"Returns the channel onboarding `status`. `status = NOT_CREATED` means not\nyet onboarded (not an error).\n","operationId":"institutionDepositAccountStatus","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/UserIdQueryRequired"},{"name":"channel","in":"query","required":true,"description":"Channel. Currently supports `fvbank` and `straitsx`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_CREATED","SUBMITTED","IN_REVIEW","ACTION_REQUIRED","APPROVED","REJECTED"]}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```