> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create ACH Return

>  

<Warning>
  The features documented here are in a beta state, and this documentation is considered draft material subject to frequent change.
</Warning>

Use this endpoint to create an ACH return in our system.


## OpenAPI

````yaml openapi/platform-api/v20111101.yaml POST /ach_returns
openapi: 3.0.0
info:
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  description: >
    The MX Platform API is a powerful, fully-featured API designed to make
    aggregating and enhancing financial data easy and reliable. It can
    seamlessly connect your app or website to tens of thousands of financial
    institutions.
  title: MX Platform API
  version: '20111101'
servers:
  - url: https://int-api.mx.com
  - url: https://api.mx.com
security:
  - basicAuth: []
tags:
  - name: authorization
  - name: widgets
  - name: users
  - name: members
  - name: institutions
  - name: accounts
  - name: transactions
  - name: microdeposits
  - name: managed data
  - name: transaction rules
  - name: statements
  - name: merchants
  - name: categories
  - name: insights
  - name: investment holdings
  - name: spending plan
  - name: goals
  - name: budgets
  - name: monthly cash flow profile
  - name: notifications
  - name: taggings
  - name: tags
  - name: deprecated
  - name: processor token
  - name: verifiable credentials
  - name: rewards
  - name: ach return
paths:
  /ach_returns:
    post:
      tags:
        - ach return
      summary: Create ACH Return
      description: >
        :::warning

        The features documented here are in a beta state, and this documentation
        is considered draft material subject to frequent change.

        :::


        Use this endpoint to create an ACH return in our system.
      operationId: createACHReturn
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACHReturnCreateRequestBody'
        description: ACH return object to be created.
        required: true
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/ACHReturnResponseBody'
          description: OK
components:
  schemas:
    ACHReturnCreateRequestBody:
      properties:
        ach_return:
          $ref: '#/components/schemas/ACHReturnCreateRequest'
      type: object
    ACHReturnResponseBody:
      properties:
        ach_return:
          $ref: '#/components/schemas/ACHResponse'
      type: object
    ACHReturnCreateRequest:
      properties:
        account_guid:
          description: >-
            The unique identifier for the account associated with the
            transaction. Defined by MX.
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          nullable: false
          type: string
        account_number_last_four:
          description: >-
            The last 4 digits of the account number used for the transaction by
            the Originating Depository Financial Institution (ODFI).
          example: '1234'
          type: string
        ach_initiated_at:
          description: >-
            The date and time when the transaction was initiated by the
            Originating Depository Financial Institution (ODFI) in ISO 8601
            format without timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type: string
        corrected_account_number:
          description: >-
            The account number correction reported by the RDFI. Populate only if
            the `resolution_code` is `NOTICE_OF_CHANGE`.
          example: null
          type: string
        corrected_routing_number:
          description: >-
            The routing number correction reported by the RDFI. Populate only if
            the `resolution_code` is `NOTICE_OF_CHANGE`. Must be a valid 9-digit
            routing number format.
          example: null
          type: string
        id:
          description: >-
            Client-defined identifier for this specific return submission.
            Allows you to track and reference you requests.
          example: client_ach_id_1234
          nullable: false
          type: string
        member_guid:
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          description: >-
            The unique identifier for the member associated with the
            transaction. Defined by MX.
          nullable: false
          type: string
        return_account_number:
          description: Incorrect account number used in the ACH transaction.
          example: null
          type: string
        return_code:
          description: >-
            The associated ACH return code and notice of change code (for
            example, R02, R03, R04, R05, R20, NOC). See [Return
            Codes](/api-reference/platform-api/reference/ach-return-fields#return-codes)
            for a complete list.
          example: R01
          nullable: false
          type: string
        return_notes:
          description: Notes that you set to inform MX on internal ACH processing.
          example: null
          type: string
        return_routing_number:
          description: Incorrect routing number used in the ACH transaction.
          example: null
          type: string
        returned_at:
          description: >-
            The date and time when the return was reported by the Receiving
            Financial Depository Institution (RDFI) in ISO 8601 format without
            timestamp.
          example: '2025-02-13T18:09:00+00:00'
          type: string
        sec_code:
          description: >-
            The SEC code (Standard Entry Class Code)–a three-letter code
            describing how a payment was authorized (for example, `WEB`). See
            [SEC
            Codes](/api-reference/platform-api/reference/ach-return-fields#sec-codes)
            for a complete list.
          example: PPD
          type: string
        transaction_amount:
          description: The amount of the transaction.
          example: 225.84
          type: number
        transaction_amount_range:
          description: The transaction amount range, used for impact assessment.
          example: null
          type: number
        user_guid:
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          description: MX-defined identifier for the user associated with the ACH return.
          nullable: false
          type: string
      required:
        - member_guid
        - account_guid
        - id
        - user_guid
        - return_code
    ACHResponse:
      properties:
        account_guid:
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          nullable: false
          type: string
        account_number_last_four:
          example: '1234'
          nullable: true
          type: string
        account_type:
          type: string
          nullable: true
          example: CREDIT
        ach_initiated_at:
          example: '2025-02-13T18:08:00+00:00'
          nullable: true
          type: string
        client_guid:
          example: CLT-abcd-1234
          nullable: false
          type: string
        corrected_account_number:
          example: null
          nullable: true
          type: string
        corrected_routing_number:
          example: null
          nullable: true
          type: string
        created_at:
          example: null
          nullable: false
          type: string
        guid:
          example: ACH-d74cb14f-fd0a-449f-991b-e0362a63d9c6
          nullable: false
          type: string
        id:
          example: client_ach_return_id_1234
          nullable: false
          type: string
        institution_guid:
          example: INS-34r4f44b-cfge-0f6e-3484-21f47e45tfv7
          nullable: false
          type: string
        investigation_notes:
          example: null
          nullable: true
          type: string
        member_guid:
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          nullable: false
          type: string
        processing_errors:
          example: null
          nullable: true
          type: string
        resolution_code:
          example: null
          nullable: true
          type: string
        resolution_detail:
          example: null
          nullable: true
          type: string
        resolved_status_at:
          example: null
          nullable: true
          type: string
        return_code:
          example: R01
          nullable: false
          type: string
        return_notes:
          example: null
          nullable: true
          type: string
        return_account_number:
          example: null
          nullable: true
          type: string
        return_routing_number:
          example: null
          nullable: true
          type: string
        return_status:
          example: SUBMITTED
          nullable: true
          type: string
        returned_at:
          example: '2025-02-13T18:09:00+00:00'
          nullable: true
          type: string
        sec_code:
          example: PPD
          nullable: true
          type: string
        started_processing_at:
          example: null
          nullable: true
          type: string
        submitted_at:
          example: null
          nullable: true
          type: string
        transaction_amount:
          example: 225.84
          format: double
          nullable: true
          type: number
        updated_at:
          example: null
          nullable: false
          type: string
        user_guid:
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          nullable: false
          type: string
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http

````