--- 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` 'debit' | '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` 'debit' | 'credit', required — `debit` pulls funds from the external account into your wallet; `credit` pushes funds from your wallet to it. - `amount` integer, required — Amount in cents. - `currency` 'USD', required — Currency code. - `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. - `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 the payment debits or credits. - `data` object, required — Related resource identifier. - `type` 'wallet', required — Resource type. Always `wallet`. - `id` string, required - `externalParty` object, required — External party paid or debited. - `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 - `mandate` object, required — Mandate authorizing the debit, or null for credits. - `data` object, nullable, required — Related resource identifier. - `type` 'mandate', required — Resource type. Always `mandate`. - `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-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 - **2026-08-23** `b1ad79e918ac` — 1 info - `header` request parameter `X-Agent-ID` was deprecated - **2026-08-22** `efd3da471398` — 1 info - added the new optional `query` request parameter `customerPartyId` - **2026-08-19** `c2c65e052711` — 1 info - endpoint added [Change 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/1132c9ddb7bd?raw)