Webhook events triggered by a payments status update.
Platforms leveraging Zero Hash’s payments product should subscribe to webhooks to know if payments statuses have changed. Once a platform is set up to receive payment status webhooks, the payload is a JSON object containing the following fields:
| Parameter | Description | Type |
|---|---|---|
| participant_code | The Zero Hash identifier for the customer requesting an ACH transaction. | string |
| type | Indicates if the payment is a credit or a debit for the end customer. | string |
| transaction_id | The unique identifier generated by Zero Hash for the transaction. | string |
| payment_status | The current status of the payment. See payment statuses below for more. | string |
| reason_code | The Nacha failure reason code, if the payment_status is returned. | string |
| reason_description | The description matching the reason_code, if the payment_status is returned. | string |
| expected_settlement_date | For payment type of credit, when the funds are expected to settle to the end customer bank account. This is an approximation as receiving banks are ultimately responsible for posting the update. | string; YYYY-MM-DD format |
| reject_reasons | If the payment_status is rejected, this object will share reasons why. Example: "error checking account rules: failed" |
Payments Statuses
| Status | Description |
|---|---|
| submitted | Request received and validated |
| pending | Balance and authorization confirmed and transaction initialized |
| posted | Withdrawn from end customer account |
| settled | Hold period is over and funds have moved to the bank |
| cancelled | Transaction was proactively cancelled |
| failed | Transaction failed during the process |
| returned | Transaction was returned(reason listed in the reason_code and reason_description of webhook) |
| rejected | Transaction request blocked for risk mitigation or contractual reasons |
Payloads
ACH debit
{
"participant_code": "ABC123",
"type": "debit",
"transaction_id": "e8641f4b-2098-4f86-95ba-711151cee6a5",
"payment_status": "settled"
}
ACH credit
{
"participant_code": "ABC123",
"type": "credit",
"transaction_id": "e8641f4b-2098-4f86-95ba-711151cee6a9",
"payment_status": "posted",
"expected_settlement_date": "2024-03-01"
}
ACH return
{
"participant_code": "ABC123",
"type": "debit",
"transaction_id": "e8641f4b-2098-4f86-95ba-711151cee6a5",
"payment_status": "returned",
"reason_code": "R01",
"reason_description": "Insufficient funds"
}