--- title: "List ACH payments" method: GET path: "/ach" tags: ["ACH"] --- # List ACH payments `GET /ach` List your ACH payments ## Query parameters - `customerPartyId` string — Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf. - `status` 'CREATED' | 'AWAITING_APPROVAL' | 'APPROVAL_DENIED' | 'PROCESSING' | 'SETTLED' | 'FAILED' | 'RETURNED' | 'CANCELED' — Filter by status. - `direction` 'credit' — Filter by direction. - `externalPartyId` string — Only payments to this external party (epty_*). - `externalPartyAccountId` string — Only payments using this account (epa_*). - `limit` integer — Maximum results per page. - `cursor` string — Cursor from the previous page. ## Headers - `X-Instance-ID` string, nullable ## Response `200` Successful Response - object - `data` object[], required - `type` 'ach', required — Resource type. Always `ach`. - `id` string, required — ACH payment ID (ach_*). - `attributes` object, required - `direction` 'credit', required — Direction of the payment. - `amount` integer, required — Amount in cents. - `currency` 'USD', required — Currency code. - `fee` object, nullable, required — Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer. - `amount` integer, required — Fee amount in cents. - `currency` 'USD', required — Currency of the fee. - `payer` 'sender', required — Party role charged the fee. - `applied` 'on_top', required — The fee is added to the sender's cost without reducing the principal amount. - `status` 'CREATED' | 'AWAITING_APPROVAL' | 'APPROVAL_DENIED' | 'PROCESSING' | 'SETTLED' | 'FAILED' | 'RETURNED' | 'CANCELED', required — ACH payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, RETURNED, or CANCELED end it. - `companyEntryDescription` string, required — The company entry description requested at creation. Echoes the create input verbatim; see `submittedDescriptor` for what was sent to the bank. - `internalDescription` string, nullable, required — Description for your internal reference, or null. Never shared with the counterparty or the banking network. - `addenda` string, nullable, required — Payment-related information carried to the receiving bank as the NACHA addenda record, or null when none was provided. - `secCode` 'WEB' | 'PPD' | 'TEL' | 'CCD', required — ACH SEC code the entry is submitted under: WEB, PPD, TEL, or CCD. - `submittedDescriptor` object, required - `companyName` string, required — Company name submitted on the ACH payment. - `companyEntryDescription` string, required — Company entry description submitted on the ACH payment. - `traceNumber` string, nullable, required — ACH trace number assigned at submission, or null before submission. - `failure` object, nullable, required — Failure details when the payment failed, or null. - `reason` string, nullable, required — Failure reason, or null. - `code` string, nullable, required — Failure code, or null. - `return` object, nullable, required — Return details when the payment was returned, or null. - `code` string, required — ACH return code, such as R01. - `reason` string, nullable, required — Return reason, or null. - `returnedAt` string, required — RFC 3339 timestamp when the return was received. - `dishonoredAt` string, nullable, required — RFC 3339 timestamp when the return was dishonored, or null. - `contestedAt` string, nullable, required — RFC 3339 timestamp when the dishonor was contested, or null. - `fundsUnlockedAt` string, nullable, required — RFC 3339 timestamp when the returned funds were released, or null. - `submittedAt` string, nullable, required — RFC 3339 timestamp when the payment was submitted to the bank, or null. - `settledAt` string, nullable, required — RFC 3339 timestamp when the ACH payment settled, or null. A return can still arrive after settlement. - `expectedAvailableAt` string, nullable, required — RFC 3339 timestamp when the funds are expected to be available, or null when unknown. - `terminalAt` string, nullable, required — RFC 3339 timestamp when the payment reached a terminal status, or null. - `createdAt` string, required — RFC 3339 timestamp when the ACH payment was created. - `updatedAt` string, required — RFC 3339 timestamp when the ACH payment was last updated. - `relationships` object, required - `customerParty` object, required — Party the payment was created for. - `data` object, required — Related resource identifier. - `type` 'party', required — Resource type. Always `party`. - `id` string, required - `wallet` object, required — Wallet used for this payment. - `data` object, required — Related resource identifier. - `type` 'wallet', required — Resource type. Always `wallet`. - `id` string, required - `externalParty` object, required — External party the payment is with. - `data` object, required — Related resource identifier. - `type` 'external_party', required — Resource type. Always `external_party`. - `id` string, required - `externalPartyAccount` object, required — External party account used. - `data` object, required — Related resource identifier. - `type` 'external_party_account', required — Resource type. Always `external_party_account`. - `id` string, required - `meta` object, required - `pagination` object, required - `hasMore` boolean, required — Whether more results are available. - `nextCursor` string, nullable, required — Cursor for the next page, or null when there are no more results. ## Other responses - `400` — Validation Error - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. - `409` — Conflict - `422` — Validation Error. The response contains one error object for each invalid request value. - `428` — Precondition Required - `429` — Too Many Requests - `500` — Internal Server Error - `501` — Not Implemented - `502` — Bad Gateway - `503` — Service Unavailable ## Changes - **2026-09-24** `e79d669f0234` — 2 breaking, 2 info - removed the enum value `debit` from the `query` request parameter `direction` - removed the required property `data/items/relationships/mandate` from the response with the `200` status - removed the `debit` enum value from the `data/items/attributes/direction` response property for the response status `200` - added the required property `data/items/attributes/internalDescription` to the response with the `200` status - **2026-09-23** `bcf3b028c3e5` — 1 info - added the required property `data/items/attributes/fee` to the response with the `200` status - **2026-09-19** `7dd2420be291` — 1 info - added the required property `data/items/attributes/addenda` to the response with the `200` status - **2026-09-02** `c7c12da5915f` — 12 info - added the optional property `errors/items/meta/limitScope` to the response with the `400` status - added the optional property `errors/items/meta/limitScope` to the response with the `401` status - added the optional property `errors/items/meta/limitScope` to the response with the `403` status - added the optional property `errors/items/meta/limitScope` to the response with the `404` status - …8 more - **2026-08-27** `359d267dca88` — 1 info - deleted the `header` request parameter `X-Agent-ID` with deprecation [Full history](https://skmtc.dev/natural/apis/natural-api/changes/ach/get.md) --- [API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/b61b8441fba4?raw)