Webhook events trigged by linked bank accounts updates.
Platforms leveraging Zero Hash’s ACH product should subscribe to webhooks to know if linked external accounts, via Create external accounts, have been approved.
Once a platform is set up to receive external account status webhooks, the payload is a JSON object containing the following fields:
| Parameter | Description | Type |
|---|---|---|
| participant_code | The Zero Hash identifier for the customer | string |
| account_nickname | Name given to the account. Empty if no nickname was given. | string |
| account_type | Indicates if the account is checking or savings | string |
| external_account_id | The unique identifier generated by Zero Hash for the account. This must be used to make subsequent payment requests. | string |
| external_account_status | The status of the linked account, which indicates if the account can be used or not. Possible values:pending, approved, rejected, closed, locked, disabled | string |
| status_reason | If status = rejected , this field gives more context as to why the account has entered this status. Possible values: UNSPECIFIED,PARTICIPANT_INFO_UNAVAILABLE , IDENTITY_MATCH_UNAVAILABLE , INVALID_SCORES , PROCESSOR_TOKEN | string |
External account statuses
The following statuses are emitted via webhook. Platforms are notified at account creation and at any point throughout the lifecycle of the account.
| Status | Description |
|---|---|
| pending | Account creation requested, basic validations passed, and Zero Hash is running identity checks. |
| approved | Identity checks passed and the account is created and ready for use. |
| rejected | Identity checks failed and the account cannot be used. |
| closed | Either the account was returned as closed when making a payment request, or the end customer actively closed their account. |
| locked* | Zero Hash risk and compliance team was alerted to suspicious activity and locked the account for further investigation. |
| disabled* | Zero Hash risk and compliance team investigations resulted in a positive hit of suspicious activity and the team determined that the account can no longer be used. |
*Note: Most often these actions will be at the whole participant level, rather than individually at the account level. See Participant Statuses for more.
Payloads
Blockchain Account
{
"account_nickname": "test-sol",
"external_account_id": "c476a81f-a29f-4e22-88db-1f521d7cf004",
"external_account_status": "pending",
"participant_code": "ABC789",
"timestamp": 1729195673718
}
Bank Account
{
"account_nickname": "Bank of America",
"account_type": "checking",
"external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
"external_account_status": "approved",
"participant_code": "ABC123",
"timestamp": 1729195673718
}