---
title: "Notification"
method: POST
path: "ach-notification"
tags: ["ACH"]
---

# Notification

`POST ach-notification` (webhook)

This is an outbound HTTP POST message from the Shift4 gateway to the merchant's environment that provides status of the ach request. This notification request will be sent from Shift4 to the URL provided in the merchant's boarding configuration.

This requires the interface vendor to establish a listening service to receive these requests.

## Payload

- union
  - WebhookAchVerificationStatusUpdate
    - `event` object
      - `type` string — `ach.verify.verification_status_update` Occurs when the status of the ACH verification request is updated.
    - `ach` object
      - `verificationType` 'P' | 'M' — The type of verification used to validate the account. Value | Description ------|--------------- P | Prenotification M | Microdeposit
    - `token` TokenACH
      - `value` string, required — The token representing the customer's bank account credentials.
      - `type` 'ACH' — Specifies the type of token. Value = `ACH`
    - `transaction` object
      - `authSource` 'A' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- A | APM (Online)
      - `responseCode` 'A' | 'D' — Code indicating the Shift4 host response. Value | Description | Details -------|-------------|-------- A | Approved | The ACH request is approved. D | Declined | The ACH request is declined.
      - `hostResponse` HostResponseACH — Returns the response code detailing why the transaction was declined.
        - `reasonCode` string — Returns a response code from the host. Value | Description ------|----------- C01 | Incorrect DFI Account Number C02 | Incorrect Routing Number C03 | Incorrect Routing Number and Incorrect DFI Account Number C05 | Incorrect Transaction Code C06 | Incorrect DFI Account Number and Incorrect Transaction Code C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code | R01 | Insufficient Funds R02 | Account Closed R03 | No Account/ Unable to Locate Account R04 | Invalid Account Number Structure R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code R06 | Returned per ODFI’s Request R07 | Authorization Revoked by Customer R08 | Payment Stopped R09 | Uncollected Funds R10 | Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization R12 | Account Sold to Another DFI R13 | Invalid ACH Routing Number R14 | Representative Payee Deceased or Unable to Continue in That Capacity R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased R16 | Account Frozen/Entry Returned Per OFAC Instruction R17 | File Record Edit Criteria/Entry with Invalid Account Number Initiated Under Questionable Circumstances/Return of Improperly-Intiated Reversal R18 | Improper Effective Entry Date R19 | Amount Field Error R20 | Non-Transaction Account R21 | Invalid Company Identification R22 | Invalid Individual ID Number R23 | Credit Entry Refused by Receiver R24 | Duplicate Entry R25 | Addenda Error R26 | Mandatory Field Error R27 | Trace Number Error R28 | Routing Number Check Digit Error R29 | Corporate Customer Advises Not Authorized R30 | RDFI Not Participant in Check Truncation Program R31 | Permissible Return Entry (CCD and CTX only) R32 | RDFI Non-Settlement R33 | Return of XCK Entry R34 | Limited Participation DFI R35 | Return of Improper Debit Entry R36 | Return of Improper Credit Entry R37 | Source Document Presented for Payment R38 | Stop Payment on Source Document R39 | Improper Source Document/Source Document Presented for Payment
        - `reasonDescription` string — Returns a description from the host.
    - `notificationId` string, uuid — Notification ID value generated by Shift4 and returned in the response. Used for matching webhook notifications back to their original request.
    - `server` object
      - `name` string — The name of the server that processed the request.
  - WebhookAchSaleStatusUpdate
    - `event` object
      - `type` string — `ach.sale.status_update` Occurs when the status of the ACH sale request is updated.
    - `token` TokenACH
      - `value` string, required — The token representing the customer's bank account credentials.
      - `type` 'ACH' — Specifies the type of token. Value = `ACH`
    - `transaction` object
      - `authSource` 'A' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- A | APM (Online)
      - `responseCode` 'A' | 'D' | 'F' — Code indicating the Shift4 host response. Value | Description | Details -------|-------------|-------- A | Approved | The ACH request is approved. D | Declined | The ACH request is declined. F | Funded | The ACH request is funded.
      - `invoice` string — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.**
      - `hostResponse` HostResponseACH — Returns the response code detailing why the transaction was declined.
        - `reasonCode` string — Returns a response code from the host. Value | Description ------|----------- C01 | Incorrect DFI Account Number C02 | Incorrect Routing Number C03 | Incorrect Routing Number and Incorrect DFI Account Number C05 | Incorrect Transaction Code C06 | Incorrect DFI Account Number and Incorrect Transaction Code C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code | R01 | Insufficient Funds R02 | Account Closed R03 | No Account/ Unable to Locate Account R04 | Invalid Account Number Structure R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code R06 | Returned per ODFI’s Request R07 | Authorization Revoked by Customer R08 | Payment Stopped R09 | Uncollected Funds R10 | Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization R12 | Account Sold to Another DFI R13 | Invalid ACH Routing Number R14 | Representative Payee Deceased or Unable to Continue in That Capacity R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased R16 | Account Frozen/Entry Returned Per OFAC Instruction R17 | File Record Edit Criteria/Entry with Invalid Account Number Initiated Under Questionable Circumstances/Return of Improperly-Intiated Reversal R18 | Improper Effective Entry Date R19 | Amount Field Error R20 | Non-Transaction Account R21 | Invalid Company Identification R22 | Invalid Individual ID Number R23 | Credit Entry Refused by Receiver R24 | Duplicate Entry R25 | Addenda Error R26 | Mandatory Field Error R27 | Trace Number Error R28 | Routing Number Check Digit Error R29 | Corporate Customer Advises Not Authorized R30 | RDFI Not Participant in Check Truncation Program R31 | Permissible Return Entry (CCD and CTX only) R32 | RDFI Non-Settlement R33 | Return of XCK Entry R34 | Limited Participation DFI R35 | Return of Improper Debit Entry R36 | Return of Improper Credit Entry R37 | Source Document Presented for Payment R38 | Stop Payment on Source Document R39 | Improper Source Document/Source Document Presented for Payment
        - `reasonDescription` string — Returns a description from the host.
    - `notificationId` string, uuid — Notification ID value generated by Shift4 and returned in the response. Used for matching webhook notifications back to their original request.
    - `server` object
      - `name` string — The name of the server that processed the request.
  - WebhookAchRefundStatusUpdate
    - `event` object
      - `type` string — `ach.refund.status_update` Occurs when the status of the ACH refund request is updated.
    - `token` TokenACH
      - `value` string, required — The token representing the customer's bank account credentials.
      - `type` 'ACH' — Specifies the type of token. Value = `ACH`
    - `transaction` object
      - `authSource` 'A' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- A | APM (Online)
      - `responseCode` 'A' | 'D' | 'F' — Code indicating the Shift4 host response. Value | Description | Details -------|-------------|-------- A | Approved | The ACH request is approved. D | Declined | The ACH request is declined. F | Funded | The ACH request is refunded.
      - `invoice` string — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.**
      - `hostResponse` HostResponseACH — Returns the response code detailing why the transaction was declined.
        - `reasonCode` string — Returns a response code from the host. Value | Description ------|----------- C01 | Incorrect DFI Account Number C02 | Incorrect Routing Number C03 | Incorrect Routing Number and Incorrect DFI Account Number C05 | Incorrect Transaction Code C06 | Incorrect DFI Account Number and Incorrect Transaction Code C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code | R01 | Insufficient Funds R02 | Account Closed R03 | No Account/ Unable to Locate Account R04 | Invalid Account Number Structure R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code R06 | Returned per ODFI’s Request R07 | Authorization Revoked by Customer R08 | Payment Stopped R09 | Uncollected Funds R10 | Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization R12 | Account Sold to Another DFI R13 | Invalid ACH Routing Number R14 | Representative Payee Deceased or Unable to Continue in That Capacity R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased R16 | Account Frozen/Entry Returned Per OFAC Instruction R17 | File Record Edit Criteria/Entry with Invalid Account Number Initiated Under Questionable Circumstances/Return of Improperly-Intiated Reversal R18 | Improper Effective Entry Date R19 | Amount Field Error R20 | Non-Transaction Account R21 | Invalid Company Identification R22 | Invalid Individual ID Number R23 | Credit Entry Refused by Receiver R24 | Duplicate Entry R25 | Addenda Error R26 | Mandatory Field Error R27 | Trace Number Error R28 | Routing Number Check Digit Error R29 | Corporate Customer Advises Not Authorized R30 | RDFI Not Participant in Check Truncation Program R31 | Permissible Return Entry (CCD and CTX only) R32 | RDFI Non-Settlement R33 | Return of XCK Entry R34 | Limited Participation DFI R35 | Return of Improper Debit Entry R36 | Return of Improper Credit Entry R37 | Source Document Presented for Payment R38 | Stop Payment on Source Document R39 | Improper Source Document/Source Document Presented for Payment
        - `reasonDescription` string — Returns a description from the host.
    - `notificationId` string, uuid — Notification ID value generated by Shift4 and returned in the response. Used for matching webhook notifications back to their original request.
    - `server` object
      - `name` string — The name of the server that processed the request.
  - WebhookAchDisputeInitiated
    - `event` object
      - `type` string — `ach.dispute.initiated` Occurs when ACH dispute is created.
    - `token` TokenACH
      - `value` string, required — The token representing the customer's bank account credentials.
      - `type` 'ACH' — Specifies the type of token. Value = `ACH`
    - `transaction` object
      - `authSource` 'A' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- A | APM (Online)
      - `responseCode` 'P' — Code indicating the Shift4 host response. Value | Description | Details -------|-------------|-------- P | Pending | The ACH transaction is pending
      - `invoice` string — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.**
      - `hostResponse` HostResponseACH — Returns the response code detailing why the transaction was declined.
        - `reasonCode` string — Returns a response code from the host. Value | Description ------|----------- C01 | Incorrect DFI Account Number C02 | Incorrect Routing Number C03 | Incorrect Routing Number and Incorrect DFI Account Number C05 | Incorrect Transaction Code C06 | Incorrect DFI Account Number and Incorrect Transaction Code C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code | R01 | Insufficient Funds R02 | Account Closed R03 | No Account/ Unable to Locate Account R04 | Invalid Account Number Structure R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code R06 | Returned per ODFI’s Request R07 | Authorization Revoked by Customer R08 | Payment Stopped R09 | Uncollected Funds R10 | Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization R12 | Account Sold to Another DFI R13 | Invalid ACH Routing Number R14 | Representative Payee Deceased or Unable to Continue in That Capacity R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased R16 | Account Frozen/Entry Returned Per OFAC Instruction R17 | File Record Edit Criteria/Entry with Invalid Account Number Initiated Under Questionable Circumstances/Return of Improperly-Intiated Reversal R18 | Improper Effective Entry Date R19 | Amount Field Error R20 | Non-Transaction Account R21 | Invalid Company Identification R22 | Invalid Individual ID Number R23 | Credit Entry Refused by Receiver R24 | Duplicate Entry R25 | Addenda Error R26 | Mandatory Field Error R27 | Trace Number Error R28 | Routing Number Check Digit Error R29 | Corporate Customer Advises Not Authorized R30 | RDFI Not Participant in Check Truncation Program R31 | Permissible Return Entry (CCD and CTX only) R32 | RDFI Non-Settlement R33 | Return of XCK Entry R34 | Limited Participation DFI R35 | Return of Improper Debit Entry R36 | Return of Improper Credit Entry R37 | Source Document Presented for Payment R38 | Stop Payment on Source Document R39 | Improper Source Document/Source Document Presented for Payment
        - `reasonDescription` string — Returns a description from the host.
    - `notificationId` string, uuid — Notification ID value generated by Shift4 and returned in the response. Used for matching webhook notifications back to their original request.
    - `server` object
      - `name` string — The name of the server that processed the request.
  - WebhookAchDisputeStatusUpdate
    - `event` object
      - `type` string — `ach.dispute.status_update` Occurs when the status of the ACH dispute is updated.
    - `token` TokenACH
      - `value` string, required — The token representing the customer's bank account credentials.
      - `type` 'ACH' — Specifies the type of token. Value = `ACH`
    - `transaction` object
      - `authSource` 'A' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- A | APM (Online)
      - `responseCode` 'D' — Code indicating the Shift4 host response. Value | Description | Details -------|-------------|-------- D | Declined | The ACH request is declined.
      - `invoice` string — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.**
      - `hostResponse` HostResponseACH — Returns the response code detailing why the transaction was declined.
        - `reasonCode` string — Returns a response code from the host. Value | Description ------|----------- C01 | Incorrect DFI Account Number C02 | Incorrect Routing Number C03 | Incorrect Routing Number and Incorrect DFI Account Number C05 | Incorrect Transaction Code C06 | Incorrect DFI Account Number and Incorrect Transaction Code C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code | R01 | Insufficient Funds R02 | Account Closed R03 | No Account/ Unable to Locate Account R04 | Invalid Account Number Structure R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code R06 | Returned per ODFI’s Request R07 | Authorization Revoked by Customer R08 | Payment Stopped R09 | Uncollected Funds R10 | Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization R12 | Account Sold to Another DFI R13 | Invalid ACH Routing Number R14 | Representative Payee Deceased or Unable to Continue in That Capacity R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased R16 | Account Frozen/Entry Returned Per OFAC Instruction R17 | File Record Edit Criteria/Entry with Invalid Account Number Initiated Under Questionable Circumstances/Return of Improperly-Intiated Reversal R18 | Improper Effective Entry Date R19 | Amount Field Error R20 | Non-Transaction Account R21 | Invalid Company Identification R22 | Invalid Individual ID Number R23 | Credit Entry Refused by Receiver R24 | Duplicate Entry R25 | Addenda Error R26 | Mandatory Field Error R27 | Trace Number Error R28 | Routing Number Check Digit Error R29 | Corporate Customer Advises Not Authorized R30 | RDFI Not Participant in Check Truncation Program R31 | Permissible Return Entry (CCD and CTX only) R32 | RDFI Non-Settlement R33 | Return of XCK Entry R34 | Limited Participation DFI R35 | Return of Improper Debit Entry R36 | Return of Improper Credit Entry R37 | Source Document Presented for Payment R38 | Stop Payment on Source Document R39 | Improper Source Document/Source Document Presented for Payment
        - `reasonDescription` string — Returns a description from the host.
    - `notificationId` string, uuid — Notification ID value generated by Shift4 and returned in the response. Used for matching webhook notifications back to their original request.
    - `server` object
      - `name` string — The name of the server that processed the request.
  - WebhookAchDistributeStatusUpdate
    - `event` object
      - `type` string — `ach.distribute.status_update` Occurs when the status of the ACH distribute request is updated.
    - `token` TokenACH
      - `value` string, required — The token representing the customer's bank account credentials.
      - `type` 'ACH' — Specifies the type of token. Value = `ACH`
    - `transaction` object
      - `authSource` 'A' — In a response, a code returned by the processor to indicate which host issued the response. Value | Description -------|---------------------------- A | APM (Online)
      - `responseCode` 'A' | 'D' | 'F' — Code indicating the Shift4 host response. Value | Description | Details -------|-------------|-------- D | Declined | The ACH request is declined. F | Funded | The ACH request is funded.
      - `invoice` string — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.**
      - `hostResponse` HostResponseACH — Returns the response code detailing why the transaction was declined.
        - `reasonCode` string — Returns a response code from the host. Value | Description ------|----------- C01 | Incorrect DFI Account Number C02 | Incorrect Routing Number C03 | Incorrect Routing Number and Incorrect DFI Account Number C05 | Incorrect Transaction Code C06 | Incorrect DFI Account Number and Incorrect Transaction Code C07 | Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code | R01 | Insufficient Funds R02 | Account Closed R03 | No Account/ Unable to Locate Account R04 | Invalid Account Number Structure R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code R06 | Returned per ODFI’s Request R07 | Authorization Revoked by Customer R08 | Payment Stopped R09 | Uncollected Funds R10 | Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account R11 | Customer Advises Entry Not in Accordance with the Terms of the Authorization R12 | Account Sold to Another DFI R13 | Invalid ACH Routing Number R14 | Representative Payee Deceased or Unable to Continue in That Capacity R15 | Beneficiary or Account Holder (Other Than a Representative Payee) Deceased R16 | Account Frozen/Entry Returned Per OFAC Instruction R17 | File Record Edit Criteria/Entry with Invalid Account Number Initiated Under Questionable Circumstances/Return of Improperly-Intiated Reversal R18 | Improper Effective Entry Date R19 | Amount Field Error R20 | Non-Transaction Account R21 | Invalid Company Identification R22 | Invalid Individual ID Number R23 | Credit Entry Refused by Receiver R24 | Duplicate Entry R25 | Addenda Error R26 | Mandatory Field Error R27 | Trace Number Error R28 | Routing Number Check Digit Error R29 | Corporate Customer Advises Not Authorized R30 | RDFI Not Participant in Check Truncation Program R31 | Permissible Return Entry (CCD and CTX only) R32 | RDFI Non-Settlement R33 | Return of XCK Entry R34 | Limited Participation DFI R35 | Return of Improper Debit Entry R36 | Return of Improper Credit Entry R37 | Source Document Presented for Payment R38 | Stop Payment on Source Document R39 | Improper Source Document/Source Document Presented for Payment
        - `reasonDescription` string — Returns a description from the host.
    - `notificationId` string, uuid — Notification ID value generated by Shift4 and returned in the response. Used for matching webhook notifications back to their original request.
    - `server` object
      - `name` string — The name of the server that processed the request.

## Acknowledgement `200`

Return 200 status to indicate that the Notification was received successfully.

---

[API](https://skmtc.dev/shift4/apis/shift4-payment-api.md) · [All operations](https://skmtc.dev/shift4/apis/shift4-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/shift4/shift4-payment-api/revisions/2f85c87cc9e5/schema)