Payments status updates

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:

ParameterDescriptionType
participant_codeThe Zero Hash identifier for the customer requesting an ACH transaction.string
typeIndicates if the payment is a credit or a debit for the end customer.string
transaction_idThe unique identifier generated by Zero Hash for the transaction.string
payment_statusThe current status of the payment. See payment statuses below for more.string
reason_codeThe Nacha failure reason code, if the payment_status is returned.string
reason_descriptionThe description matching the reason_code, if the payment_status is returned.string
expected_settlement_dateFor 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_reasonsIf the payment_status is rejected, this object will share reasons why. Example: "error checking account rules: failed"

Payments Statuses

StatusDescription
submittedRequest received and validated
pendingBalance and authorization confirmed and transaction initialized
postedWithdrawn from end customer account
settledHold period is over and funds have moved to the bank
cancelledTransaction was proactively cancelled
failedTransaction failed during the process
returnedTransaction was returned prior to funds settling, most commonly due to insufficient funds (reason listed in the reason_code and reason_description of webhook)
rejectedTransaction request blocked for risk mitigation or contractual reasons
returned_settledTransaction was returned after funds settled (reason listed in the reason_code and reason_description of webhook)

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"
}