External account status updates

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:

ParameterDescriptionType
participant_codeThe Zero Hash identifier for the customerstring
account_nicknameName given to the account. Empty if no nickname was given.string
account_typeIndicates if the account is checking or savingsstring
external_account_idThe unique identifier generated by Zero Hash for the account. This must be used to make subsequent payment requests.string
external_account_statusThe status of the linked account, which indicates if the account can be used or not. Possible values:pending, approved, rejected, closed, locked, disabledstring
status_reasonIf 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.

StatusDescription
pendingAccount creation requested, basic validations passed, and Zero Hash is running identity checks.
approvedIdentity checks passed and the account is created and ready for use.
rejectedIdentity checks failed and the account cannot be used.
closedEither 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
}