Nacha Accounts API

openapi: 3.2.0
info:
  title: Nacha Accounts API
  version: '1.0'
  description: 'Operations tagged Accounts across 3 of this provider''s published API definitions: nacha-account-validation-plus-name-ret.json, nacha-account-validation-plus-name.json, nacha-account-validation.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /accounts/v1
- url: https://api.asig.org/afinis/accounts/aavplus/v1
- url: https://api.afinis.org/v1
tags:
- name: Accounts
paths:
  /validatewithnameandret:
    post:
      summary: ''
      tags:
      - Accounts
      operationId: validateAccountWithNameAndRET
      parameters:
      - name: apiVersion
        in: header
        required: false
        schema:
          type: string
          format: string
      - name: Request_Id
        in: header
        required: false
        description: ''
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Valid account request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-200'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-404'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-405'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-406'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-415'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-503'
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - account
              - agent
              - owner
              properties:
                account:
                  $ref: '#/components/schemas/account'
                agent:
                  $ref: '#/components/schemas/agent'
                owner:
                  $ref: '#/components/schemas/owner'
                cashAccountType:
                  type: string
                  default: Current
                  enum:
                  - Current
                  - Savings
        description: Account to be validated
    servers:
    - url: /accounts/v1
  /validate:
    post:
      summary: Account eligibility for debit ACH transactions
      tags:
      - Accounts
      operationId: validateAccount
      parameters:
      - name: apiVersion
        in: header
        required: false
        schema:
          type: string
          format: string
      - name: Request_Id
        in: header
        required: false
        description: Optional Request ID allows application developer to trace requests through the systems logs
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Valid account request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-200_2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-404'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-405'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-406'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-415'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-503'
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - debtorAccount
              - debtorAgent
              - associatedName
              properties:
                debtorAccount:
                  $ref: '#/components/schemas/debtorAccount'
                debtorAgent:
                  $ref: '#/components/schemas/debtorAgent'
                associatedName:
                  $ref: '#/components/schemas/associatedName'
                cashAccountType:
                  type: string
                  default: Current
                  enum:
                  - Current
                  - Savings
        description: Account to be validated
    servers:
    - url: https://api.asig.org/afinis/accounts/aavplus/v1
  /accounts/validate/achPaymentDebitAcceptance:
    post:
      summary: Account eligibility for debit ACH transactions
      tags:
      - Accounts
      operationId: validateDebtorAccount
      parameters:
      - name: Request_Id
        in: header
        required: false
        description: Optional Request ID allows application developer to trace requests through the systems logs
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Valid account request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-400_2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-401_2'
        '404':
          description: Not Found
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-500_2'
        '503':
          description: Service unavailable
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACHPaymentAcceptanceDebit'
        description: Account to be validated for debit transactions
        required: true
    servers:
    - url: https://api.afinis.org/v1
  /accounts/validate/achPaymentCreditAcceptance:
    post:
      summary: Account eligibility for credit ACH transactions
      tags:
      - Accounts
      operationId: validateCreditorAccount
      parameters:
      - name: Request_Id
        in: header
        required: false
        description: Optional Request ID allows application developer to trace requests through the systems logs
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Valid account request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-400_2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-401_2'
        '404':
          description: Not Found
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-500_2'
        '503':
          description: Service unavailable
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACHPaymentAcceptanceCredit'
        description: Account to be validated for Credit transactions
        required: true
    servers:
    - url: https://api.afinis.org/v1
components:
  schemas:
    error-500:
      title: Internal Server Error
      description: 500 - Internal Server Error
      type: object
      required:
      - details
      properties:
        details:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/internalServerErrorDetails'
    errorDetails-401:
      title: Error 401 - Unauthorized - Details
      type: object
      properties:
        errorCode:
          example: 1000
          type: number
          enum:
          - 1000
          - 1001
          description: "A programmatic error code:\n  * `1000` - API key is missing, invalid or expired. \n  * `1001` - API token is invalid, expired, or account associated with key does not have access to that API.\n"
        message:
          description: A human readable description of the problem
          example: API key is missing, invalid or expired.
          type: string
      required:
      - errorcode
      - message
    internalServerErrorDetails:
      title: Internal Server Error Details
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 3001
          type: number
          enum:
          - 3001
          description: "A programmatic error code:\n  * `3001` - Internal Server error.\n"
        message:
          description: A human readable description of the problem
          example: Internal Server error
          type: string
    owner:
      title: Owner
      type: object
      description: Party that legally owns the account.
      properties:
        surname:
          description: Surname is a name added to a given name and is part of a personal name. In many cases, a surname is a family name
          example: Doe
          type: string
          minLength: 1
          maxLength: 35
        givenName:
          description: Name given at birth
          example: John
          type: string
          minLength: 1
          maxLength: 35
        middleName:
          description: Second name of a person
          example: Samuel
          type: string
          minLength: 1
          maxLength: 35
        nameSuffix:
          description: Suffix for name
          example: PhD
          type: string
          minLength: 1
          maxLength: 35
        organisationName:
          description: Name by which an organisation is known and which is usually used to identify that organisation.
          example: Weyland-Yutani Corporation
          type: string
          minLength: 1
          maxLength: 35
    returns:
      title: Returns
      description: Contains RET fields for the response
      type: array
      items:
        type: object
        properties:
          sequenceNumber:
            type: number
            example: '22'
            minLength: 1
          settlementDate:
            description: Indicates the date of settlement of the underlying.
            example: '2023-02-24'
            format: date
            minLength: 10
            maxLength: 10
          purpose:
            description: Underlying reason for the payment transaction.
            type: string
            example: Pay rent
            minLength: 1
            maxLength: 35
          accountType:
            type: number
            example: '22'
            minLength: 2
            maxLength: 2
            description: "Specifies the nature, or use of the account. Available codes:  *  '22' - demand credit *  '27' - demand debit  *  '32' - savings credit *  '37' - savings debit *  '42' - general ledger credit *  '47' - general ledger debit *  '52' - loan account credit *  '55' - loan account debit (reversals only)        \n"
            enum:
            - 22
            - 27
            - 32
            - 37
            - 42
            - 47
            - 52
            - 55
          localInstrument:
            type: string
            example: WEB
            minLength: 3
            maxLength: 3
            enum:
            - ARC
            - BOC
            - CCD
            - CIE
            - CTX
            - IAT
            - MTE
            - POP
            - POS
            - PPD
            - RCK
            - SHR
            - TEL
            - WEB
            - XCK
          amount:
            description: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party
            type: object
            required:
            - amount
            - currency
            properties:
              amount:
                type: number
                format: float
                example: 1.01
                maxLength: 11
              currency:
                type: string
                example: USD
                minLength: 3
                maxLength: 3
          returnReason:
            type: string
            example: R01
            minLength: 3
            maxLength: 3
            description: 'Available codes:  *  ''R01'' - Insufficient funds *  ''R02'' - Account Closed *  ''R03'' - No Account / Unable to Locate Account *  ''R04'' - Invalid Account Number Structure *  ''R05'' - Unauthorized Debit to Consumer Account Using Corporate SEC Code *  ''R06'' - Returned per ODFI''s Request *  ''R07'' - Authorization Revoked by Customer *  ''R08'' - Payment Stopped *  ''R09'' - Uncollected Funds *  ''R10'' - Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account *  ''R11'' - Customer Advises Entry Not in Accordance with the Terms of the Authorization *  ''R12'' - Account Sold to Another DFI *  ''R14'' - Representative Payee Deceased or Unable to Continue in That Capacity *  ''R15'' - Beneficiary or Account Holder (Other Than a Representative Payee) Deceased *  ''R16'' - Account Frozen / Entry Returned Per OFAC Instruction *  ''R17'' - File Record Edit Criteria / Entry with Invalid Account Number Initated Under Questionable Circumstances / Return of Improperly Initiated Reversal *  ''R20'' - Non-Transaction Account *  ''R21'' - Invalid Company Identification *  ''R22'' - Invalid Individual ID Number *  ''R23'' - Credit Entry Refused by Receiver *  ''R29'' - Corporate Customer Advises Not Authorized *  ''R31'' - Permissible Return Entry (CCD and CTX) only *  ''R32'' - RDFI Non-Settlement *  ''R33'' - Return of XCK Entry  *  ''R34'' - Limited Participation DFI *  ''R35'' - Return of Improper Debit Entry *  ''R37'' - Source Document Presented for Payment *  ''R38'' - Stop Payment on Source Document *  ''R39'' - Improper Source Document / Source Document Presented for Payment  *  ''R50'' - State Law Affecting RCK Acceptance  *  ''R51'' - Item related to RCK Entry is Ineligible for RCK Entry is Improper *  ''R52'' - Stop Payment on Item Related to RCK Entry *  ''R53'' - Item and RCK Entry Presented for Payment

              '
            enum:
            - R01
            - R02
            - R03
            - R04
            - R05
            - R06
            - R07
            - R08
            - R09
            - R10
            - R11
            - R12
            - R14
            - R15
            - R16
            - R17
            - R20
            - R21
            - R22
            - R23
            - R29
            - R31
            - R32
            - R33
            - R34
            - R35
            - R37
            - R38
            - R39
            - R50
            - R51
            - R52
            - R53
    errorDetails-400:
      title: Error 400 - Bad Request - Details
      type: object
      properties:
        errorCode:
          description: "A programmatic error code:\n  * `2000` - Invalid JSON structure.\n  * `2001` - '[Field name] is missing or invalid.'\n  * `2002` - Invalid date.\n  * `2003` - Invalid combination of fields submitted. Check the API specification for eligible combinations. \n  * `2004` - '[Field name] cannot be more than [max number] characters.'\n"
          example: 2000
          type: number
          enum:
          - 2000
          - 2001
          - 2002
          - 2003
          - 2004
        message:
          description: A human readable description of the problem
          example: Invalid JSON structure.
          type: string
    error-401:
      title: Error 401 - Unauthorized
      description: Authentication failed or user doesn’t have permissions for requested operation
      type: object
      properties:
        details:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-401'
    response-200:
      title: Response
      type: object
      description: 200 - OK
      properties:
        accountStatus:
          type: string
          description: Status of account being validated
          example: Enabled
          enum:
          - Enabled
          - Disabled
        ownerNameMatch:
          type: object
          properties:
            surnameMatch:
              example: Match
              type: string
              enum:
              - Match
              - Partial Match
              - No Match
              - No Data Found
            givenNameMatch:
              example: Partial Match
              type: string
              enum:
              - Match
              - Partial Match
              - No Match
              - No Data Found
            middleNameMatch:
              example: No Match
              type: string
              enum:
              - Match
              - Partial Match
              - No Match
              - No Data Found
            nameSuffixMatch:
              example: No Data Found
              type: string
              enum:
              - Match
              - Partial Match
              - No Match
              - No Data Found
            organisationNameMatch:
              example: No Data Found
              type: string
              enum:
              - Match
              - Partial Match
              - No Match
              - No Data Found
        cashAccountType:
          type: string
          default: Current
          enum:
          - Current
          - Savings
        returns:
          $ref: '#/components/schemas/returns'
    error-503:
      title: Error 503 - Service Unavailable
      description: Service is temporarily unavailable
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 503
          type: number
          enum:
          - 503
          description: "A programmatic error code:\n  * `503` - Service Unavailable\n"
        message:
          description: A human readable description of the problem
          example: Service is temporarily unavailable.
          type: string
    error-406:
      title: Error 406 - Not Acceptable
      description: Web server doesn't find any content that conforms to the criteria given by the user agent.
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 406
          type: number
          enum:
          - 406
          description: "A programmatic error code:\n  * `406` - Not Acceptable\n"
        message:
          description: A human readable description of the problem
          example: Not Acceptable
          type: string
    error-405:
      title: Error 405 - Method Not Allowed
      description: The request method is known by the server but has been disabled and cannot be used.
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 405
          type: number
          enum:
          - 405
          description: "A programmatic error code:\n  * `405` - Method Not Allowed\n"
        message:
          description: A human readable description of the problem
          example: Method Not Allowed
          type: string
    error-400:
      title: Error 400 - Bad Request
      description: The request could not be understood or required parameters were missing
      type: object
      properties:
        details:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-400'
    agent:
      description: Identification of a financial institution.
      type: object
      required:
      - clearingSystemIdentification
      - memberIdentification
      properties:
        clearingSystemIdentification:
          type: string
          example: USABA
          enum:
          - USABA
          description: "Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed: \n * `USABA` - Routing Transit number assigned by the ABA for US financial Institutions. \n"
        memberIdentification:
          type: string
          minLength: 1
          maxLength: 35
          example: 061103852
    error-415:
      title: Error 415 - Unsupported Media Type
      description: The media format of the requested data is not supported by the server, so the server is rejecting the request.
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 415
          type: number
          enum:
          - 415
          description: "A programmatic error code:\n  * `415` - Unsupported Media Type\n"
        message:
          description: A human readable description of the problem
          example: Unsupported Media Type
          type: string
    error-404:
      title: Error 404 - Not Found
      description: Resource was not found.
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 404
          type: number
          enum:
          - 404
          description: "A programmatic error code:\n  * `404` - Resource was not found.\n"
        message:
          description: A human readable description of the problem
          example: Resource was not found.
          type: string
    account:
      title: Account
      type: object
      required:
      - identification
      properties:
        identification:
          description: Account number being verified
          example: '11101012'
          minLength: 1
          maxLength: 34
    error-403:
      title: Error 403 - Forbidden
      description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server.
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 403
          type: number
          enum:
          - 403
          description: "A programmatic error code:\n  * `403` - Forbidden\n"
        message:
          description: A human readable description of the problem
          example: Forbidden
          type: string
    debtorAccount:
      title: Account
      type: object
      required:
      - identification
      properties:
        identification:
          description: Account number being verified
          example: '3358700016'
          minLength: 1
          maxLength: 34
    statusReasonInformation:
      title: StatusReasonInformation
      type: object
      properties:
        reason:
          description: Specifies the reason
          example: '10000'
          type: string
          minLength: 1
          maxLength: 35
        additionalInformation:
          description: Further details on the status reason
          example: No history found
          type: string
          minLength: 1
          maxLength: 105
    response-200_2:
      title: Response
      type: object
      description: 200 - OK
      properties:
        accountStatus:
          type: string
          description: Status of account being validated
          example: Enabled
          enum:
          - Enabled
          - Unable to Locate
          - Disabled
        associatedNameMatch:
          type: object
          required:
          - surnameMatch
          - givenNameMatch
          properties:
            surnameMatch:
              example: true
              type: string
              enum:
              - true
              - false
              - NO_DATA_AVAILABLE
              - NO_MATCH_REQUESTED
            givenNameMatch:
              example: true
              type: string
              enum:
              - true
              - false
              - NO_DATA_AVAILABLE
              - NO_MATCH_REQUESTED
        statusReasonInformation:
          $ref: '#/components/schemas/statusReasonInformation'
        associatedName:
          $ref: '#/components/schemas/associatedName'
        debtorAccount:
          $ref: '#/components/schemas/debtorAccount'
        debtorAgent:
          $ref: '#/components/schemas/debtorAgent'
    debtorAgent:
      description: Identification of a financial institution.
      type: object
      required:
      - clearingSystemIdentification
      - memberIdentification
      properties:
        clearingSystemIdentification:
          type: string
          example: USABA
          enum:
          - USABA
          description: "Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed: \n * `USABA` - Routing Transit number assigned by the ABA for US financial Institutions. \n"
        memberIdentification:
          type: string
          minLength: 1
          maxLength: 35
          example: '121000358'
    associatedName:
      title: AssociatedName
      type: object
      description: Party that legally owns the account.
      properties:
        surname:
          description: Surname is a name added to a given name and is part of a personal name. In many cases, a surname is a family name
          example: CANADY
          type: string
          minLength: 1
          maxLength: 32
        givenName:
          description: Name given at birth
          example: JAYSON
          type: string
          minLength: 1
          maxLength: 32
    ACHPaymentAcceptanceDebit:
      title: ACHPaymentAcceptanceDebit
      type: object
      properties:
        debtorAccount:
          $ref: '#/components/schemas/DebtorAccount'
        debtorAgent:
          $ref: '#/components/schemas/DebtorAgent'
        cashAccountType:
          type: string
          enum:
          - Current
          - Savings
    error-500_2:
      title: 500 Error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-500'
    CreditorAccount:
      title: CreditorAccount
      type: object
      required:
      - identification
      properties:
        identification:
          description: Account number of party to be credited
          example: 11101019
          type: string
    errorDetails-401_2:
      title: 401 ErrorDetails
      type: object
      properties:
        errorcode:
          description: A programmatic error code
          example: 1000
          type: number
          enum:
          - '1000': null
            description: API key is missing, invalid or expired.
          - '1001': null
            description: API token is invalid, expired, or account associated with key does not have access to that API.
        message:
          description: A human readable description of the problem
          example: API key is missing, invalid or expired.
          type: string
      required:
      - errorcode
      - message
    ACHPaymentAcceptanceCredit:
      title: ACHPaymentAcceptanceCredit
      type: object
      properties:
        creditorAccount:
          $ref: '#/components/schemas/CreditorAccount'
        creditorAgent:
          $ref: '#/components/schemas/CreditorAgent'
        cashAccountType:
          type: string
          enum:
          - Current
          - Savings
    CreditorAgent:
      title: CreditorAgent
      type: object
      properties:
        memberIdentification:
          description: Identification number of clearing system e.g., a U.S. transit routing number or Canadian Payments Association Routing Number
          example: 061103852
          type: string
        clearingSystemIdentification:
          description: Clearing system identification
          example: United States Routing Number
          type: string
    errorDetails-400_2:
      title: ErrorDetails
      type: object
      properties:
        errorcode:
          description: A programmatic error code
          example: 2000
          type: string
        message:
          description: A human readable description of the problem
          example: Invalid request.
          type: string
      required:
      - errorcode
      - message
    error-401_2:
      title: 401 Error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-401_2'
    errorDetails-500:
      title: 500 ErrorDetails
      type: object
      properties:
        errorcode:
          description: A programmatic error code
          example: 3001
          type: number
        message:
          description: A human readable description of the problem
          example: Internal Server error
          type: string
      required:
      - errorcode
      - message
    DebtorAgent:
      title: DebtorAgent
      type: object
      properties:
        memberIdentification:
          description: Identification number of clearing system e.g., a U.S. transit routing number or a Canadian Payments Association Routing Number
          example: 061103852
          type: string
        clearingSystemIdentification:
          description: Clearing system identification
          example: United States Routing Number
          type: string
    error-400_2:
      title: Error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-400_2'
    DebtorAccount:
      title: DebtorAccount
      type: object
      required:
      - identification
      properties:
        identification:
          description: Account number of party who owes funds
          example: 11101012
          type: string
    AccountSta

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nacha/refs/heads/main/openapi/nacha-accounts-api-openapi.yml