Release date
Prod: Apr 26, 2023
Platform implementation requirement: Aug 1, 2023
Release type
Actionable – Updates required for platforms
Breaking – If updates are not made by Aug 1, 2023, newly submitted participants will be declined
Summary
Zero Hash has identified several areas for enhancement within participant onboarding. The following updates maintain the integrity of data, while making inputs easily accessible, auditable, and compliant with regional reporting requirements.
Broadly, two new concepts are being introduced:
- Existing data update – KYC will no longer be parsed from <metadata>, and KYC results will need to be passed as individual data elements
- New data collection – <citizenship> will be collected to determine ID submission requirements
Action required
Existing data update
Platforms will be required to pass new participant KYC elements as their own, normalized fields, rather than as <metadata>. This enables field validation and further KYC services to be provided by Zero Hash.
The fields and entries are as follows:
|
Field |
Definition |
Requirement |
Entry |
|
kyc |
Whether the participant passed or failed the platform KYC screen. Zero Hash will not accept failed KYC |
Required |
pass, fail |
|
kyc_timestamp |
Time KYC was passed |
Required |
UNIX ms |
|
sanction_screening |
Whether the participant passed or failed the platform sanctions screen. Zero Hash will not accept failed sanctions |
Required |
pass, fail |
|
sanction_screening_timestamp |
Time sanctions screen was passed |
Required |
UNIX ms |
|
risk_rating |
Participant risk assessed as per the KYC vendor |
Required1 |
low, medium, high |
|
IDV |
Whether the participant passed or failed verification of a submitted ID (e.g. license, passport) |
Optional |
pass, fail |
|
liveness_check |
Whether the participant passed or failed a live check, sometimes called a selfie check |
Optional |
pass, fail |
|
phone_number |
Valid mobile phone number string |
Optional |
string, no ‘+’ for country code |
1 Certain platforms do not receive this field from their KYC vendor and will therefore be exempt from passing risk rating.
If a platform’s KYC provider does not return the above entries (e.g. pass, fail), submissions to Zero Hash must be mapped as follows:
|
KYC provider |
Zero Hash entry |
|
verified |
pass |
|
not verified |
fail |
|
true |
pass |
|
false |
fail |
|
green |
pass |
|
red |
fail |
|
clear |
pass |
|
hit |
fail |
Previously submitted participants will not be impacted by the addition of KYC and sanctions fields.
New data collection
As of Aug 1, 2023 platforms will be required to submit at least one new field for submitting new participants – <citizenship> – and, conditionally, <tax_id>.
Collection of <citizenship> enables regional compliance when it comes to tax reporting, transaction availability, and fraud monitoring. Gathering citizenship is up to the discretion of the platform.
<tax_id> is a globally agnostic field name that captures the likes of SSN for the United States, CPF for Brazil, and even EIN for United States businesses or ABN for Australian businesses. <tax_id> will take the place of <ssn>, as previously available in <id_number> and <id_number_type>.
Citizenship validations for platforms using the Zero Hash US entity2 will be as follows:
|
Citizenship |
Validations |
|
“United States” |
<tax_id> required and the need to submit <id_number> and <id_number_type> is removed, although still allowed if a platform wishes to also submit identity documents. The submission will fail if the <tax_id> is not nine digits long or is consecutive numbers (e.g. 000000000). Additionally, if the <tax_id> begins with the number 9, therefore indicating an ITIN, <id_number> and <id_number_type> are still required. |
|
Anything other than “United States” |
<tax_id> is not required and <id_number> and <id_number_type> are required as usual |
2 When Zero Hash entities roll out in other regions (e.g. Brazil) platforms may encounter other validations.
Because <tax_id> is taking the place of <ssn>, the updated list of valid id options are listed here.
Endpoints impacted
- POST /participants/customers/new
- POST /participants/entity/new (<tax_id> and <citizenship> only)
- PATCH /participants/customers/:participantCode (used if <tax_id> is missing where <citizenship> = “United States”)
- POST /participants/customers/promote_minor
|
Scenario |
Response |
|
Successfully submitted data (POST) |
200 + payload of the participant record |
|
Successfully updated data (PATCH) |
200 + payload of the updated participant record |
|
KYC data is missing |
400 - Missing fields: |
|
Citizenship is not submitted |
400 - Missing fields: “citizenship” |
|
Citizenship is “United States” and tax_id is not submitted |
400 - Missing fields: “tax_id” |
Relevant documentation
Zero Hash has updated Participants API documentation to reflect the above.