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.


    Just getting started? See our [use case guides](/use-cases/).

    '
  title: MX Platform accounts ach return API
  version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: ach return
paths:
  /ach_returns/{ach_return_guid}:
    get:
      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 get an ACH return by its `guid` or `id`.

        '
      operationId: readACHRetrun
      parameters:
      - $ref: '#/components/parameters/achReturnGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/ACHReturnResponseBody'
          description: OK
      summary: Read ACH Return
      tags:
      - ach return
  /ach_returns:
    get:
      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 get all ACH returns.

        '
      operationId: listACHRetruns
      parameters:
      - $ref: '#/components/parameters/institutionGuid'
      - $ref: '#/components/parameters/returnedAt'
      - $ref: '#/components/parameters/resolvedStatusAt'
      - $ref: '#/components/parameters/returnCode'
      - $ref: '#/components/parameters/returnStatus'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPage'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/ACHReturnsResponseBody'
          description: OK
      summary: List ACH Returns
      tags:
      - ach return
    post:
      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
      summary: Create ACH Return
      tags:
      - ach return
components:
  schemas:
    ACHReturnsResponseBody:
      properties:
        ach_returns:
          items:
            $ref: '#/components/schemas/ACHResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      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
    ACHReturnResponseBody:
      properties:
        ach_return:
          $ref: '#/components/schemas/ACHResponse'
      type: object
    ACHReturnCreateRequestBody:
      properties:
        ach_return:
          $ref: '#/components/schemas/ACHReturnCreateRequest'
      type: object
    PaginationResponse:
      properties:
        current_page:
          example: 1
          type: integer
        per_page:
          example: 25
          type: integer
        total_entries:
          example: 1
          type: integer
        total_pages:
          example: 1
          type: integer
      type: object
    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
  parameters:
    resolvedStatusAt:
      description: The date and time when the return was resolved by the Receiving Financial Depository Institution (RDFI) in ISO 8601 format without timestamp
      example: '2025-02-13T18:09:00+00:00'
      in: query
      name: resolved_status_at
      required: false
      schema:
        type: string
    institutionGuid:
      description: The identifier for the institution associated with the ACH return. Defined by MX.
      in: query
      name: institution_guid
      required: false
      schema:
        type: string
    recordsPerPage:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `100`. If the value exceeds `100`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    returnCode:
      description: The associated ACH return code and notice of change code. See [Return Codes](/api-reference/platform-api/reference/ach-return-fields#return-codes) for a complete list.
      in: query
      name: return_code
      required: false
      schema:
        type: string
    achReturnGuid:
      name: ach_return_guid
      description: The unique identifier (`guid`) for the ACH return. Defined by MX.
      required: true
      in: path
      schema:
        type: string
    returnedAt:
      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'
      in: query
      name: returned_at
      required: false
      schema:
        type: string
    returnStatus:
      description: The status of the return. See [Return Statuses](/api-reference/platform-api/reference/ach-return-fields#return-status) for a complete list.
      example: SUBMITTED
      in: query
      name: return_status
      required: false
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      scheme: basic
      type: http