---
title: "Create ACH payment"
method: POST
path: "/ach"
tags: ["ACH"]
---

# Create ACH payment

`POST /ach`

Create an ACH payment to an external party account

## Headers

- `Idempotency-Key` string, required
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `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.
      - `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' — Currency code. Defaults to USD.
      - `walletId` string — Wallet (wal_*) to debit or credit. Defaults to the party's default wallet.
      - `externalPartyAccountId` string, required — External party account (epa_*) to pay or debit.
      - `mandateId` string — Mandate (mdt_*) authorizing the debit. Required for debits; not allowed for credits.
      - `companyEntryDescription` string, required — ACH company entry description. Maximum 10 characters.
      - `addenda` string — Payment-related information carried to the receiving bank as the NACHA addenda record. Maximum 80 characters.

## Response `201`

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.
      - `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 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

## 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-19** `7dd2420be291` — 2 info
  - added the new optional request property `data/attributes/addenda`
  - added the required property `data/attributes/addenda` to the response with the `201` 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
- **2026-08-23** `b1ad79e918ac` — 1 info
  - `header` request parameter `X-Agent-ID` was deprecated
- **2026-08-22** `efd3da471398` — 1 info
  - added the new optional request property `data/attributes/customerPartyId`

[Full history](https://skmtc.dev/natural/apis/natural-api/changes/ach/post.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/4a05af81217f?raw)