Webhook events triggered by a participant status update.
Platforms should subscribe to these webhooks to know if a participants' status has changed. (i.e. if the participant has been approved, locked, disabled, etc.).
Request an overview of reject reasons during implementation
If you are a signed or prospective Zero Hash Platform subscribing to this webhook, you can request the complete list of reject reasons by contacting your Relationship Manager or by emailing [email protected].
Once a platform is configured to receive participant status webhooks, we will share real time events that include a JSON object containing the following fields:
Parameters
| Parameter | Description | Type |
|---|---|---|
| participant_code | The Zero Hash identifier for the new customer. Note: this value is key to enable you to submit trades and check account balances for this customer. | string |
| participant_status | The status of the participant, which dictates whether they can trade or not. e.g. submitted, pending_approval, approved, rejected, locked, disabled, divested, closed. | string |
| reason_code | If applicable, the reason the participant is in a status of locked, disabled, closed, or divested; e.g. compliance_issue, user_request. On rejection, this is set to reject_reasons[0]. | string |
| timestamp | The UNIX timestamp (in milliseconds) representing when the status was changed. | number |
| reject_reasons | If applicable, the reason(s) that a participant could have failed KYC verification. This is currently only applicable to participant rejections. | string |
| kyc_attempts | Number of attempts the participant has been rejected. By default there is a max amount of 3 retries allowed. If the participant is approved, this counter resets to 0. | number |
Participant Status Definitions
| Status | Definition |
|---|---|
| submitted | Successfully submitted to <POST /participants/customers/new> and given a participant code, but has not yet been approved to transact. |
| pending_approval | Participant requires manual review by Zero Hash before moving to an approved or rejected status. |
| approved | Participant code and relationships created and the participant passes necessary approvals to transact. |
| rejected | Participant who was rejected from becoming an active user; most often due to customer verification declines. |
| locked | Investigative state for the Zero Hash compliance team. |
| pending_unlock | Investigations conclude the participant may remain active on Zero Hash. Only available via GET /participants, and not via webhook. |
| pending_disable | Investigations conclude the participant should be indefinitely banned from Zero Hash. Only available via GET /participants, and not via webhook. |
| disabled | Indefinitely banned from Zero Hash, but balances may exist in the participant account. Zero Hash settlement team will divest existing balances. |
| divested | Indefinitely banned from Zero Hash and participant balances were moved back to the platform float. |
| closed | Indefinitely banned from Zero Hash and no balances remained at the time of ban |
Participant Reason Codes and Request Availability
| Reason Code | Definition | Request Availability |
|---|---|---|
| compliance_issue | locked | None |
| compliance_issue | pending_disable | None |
| compliance_issue | disabled | None |
| compliance_issue | closed | None |
| compliance_issue | divested | None |
| user_request | locked | Closing only (sell/withdraw) |
| user_request | pending_disable | Closing only (sell/withdraw) |
| user_request | disabled | None |
| user_request | closed | None |
| user_request | divested | None |
| risk_cleared | pending_unlock | None - the cleared risk still needs to be approved |
| risk_cleared | approved | All |
Payloads
Participant submitted
{
"participant_code": "ABC123",
"participant_status": "submitted",
"timestamp": 1670958435349
}
Participant approved
{
"participant_code": "ABC123",
"participant_status": "approved",
"timestamp": 1670958435349,
"kyc_attempts": 0
}
Verification failed
{
"participant_code": "ABC123",
"participant_status": "rejected",
"reason_code": "kyc.rejected",
"timestamp": 1708489569494,
"reject_reasons": [
"kyc.idv.name_not_extracted",
"kyc.pii.national_id_not_present"
]
"kyc_attempts": 1
}
Participant status change
{
"participant_code": "ABC123",
"participant_status": "locked",
"reason_code": "compliance_issue",
"timestamp": 1670958435349
}