Nacha Reporting ACH Return Payments API

openapi: 3.2.0
info:
  version: 1.0.3
  title: RET () Reporting ACH Return Payments API
  description: Allow Originators and payment providers to share ACH return payment data to support fraud/risk mitigation.
  contact:
    email: info@afinis.org
    url: https://www.afinis.org
servers:
- url: https://api.afinis.org/payments/ach/v1
tags:
- name: Reporting ACH Return Payments
paths:
  /ret:
    post:
      operationId: Reporting ACH Return Payments
      tags:
      - Reporting ACH Return Payments
      description: Alert the network of ACH users about problematic ACH payments to help mitigate the risk of suspected bad actors perpetuating fraud against other ACH users
      responses:
        '200':
          description: OK
          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: Access denied, the operation is not allowed
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-404'
        '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:
              - originatorName
              - originatorAgentName
              - receiverName
              - receiverAgent
              - receiverAccount
              - endToEndIdentification
              - requestedExecutionDate
              - settlementDate
              - localInstrument
              - amount
              - returnReason
              - purpose
              properties:
                originatorName:
                  type: string
                  minLength: 1
                  maxLength: 70
                  example: John Edison
                originatorAgentName:
                  type: string
                  minLength: 1
                  maxLength: 70
                  example: Hank's Bank, the Think Tank at Mont Blanc
                receiverName:
                  type: string
                  minLength: 1
                  maxLength: 70
                  example: Jane Edison
                receiverAgent:
                  $ref: '#/components/schemas/agent'
                receiverAccount:
                  $ref: '#/components/schemas/account'
                endToEndIdentification:
                  description: Unique identification assigned by the initiating party to unambiguously identify the transaction.
                  type: string
                  example: ABC13609-15-18
                  minLength: 1
                  maxLength: 35
                requestedExecutionDate:
                  description: Date at which the initiating party requests the clearing agent to process the payment.
                  type: string
                  example: '2023-02-24'
                  minLength: 10
                  maxLength: 10
                settlementDate:
                  description: Indicates the date of settlement of the underlying.
                  example: '2023-02-24'
                  type: string
                  minLength: 10
                  maxLength: 10
                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
                purpose:
                  description: Underlying reason for the payment transaction.
                  type: string
                  example: Pay rent
                  minLength: 1
                  maxLength: 35
        required: true
components:
  schemas:
    error-500:
      title: Error 500 - Internal server error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-500'
    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
    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:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-401'
    response-200:
      title: Response
      type: object
      required:
      - status
      properties:
        status:
          description: Specifies the status
          type: string
          example: RCVD
          minLength: 1
          maxLength: 140
    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
    errorDetails-500:
      title: Error 500 - Internal server error - Details
      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
    error-400:
      title: Error 400 - Bad Request
      description: The request could not be understood or required parameters were missing
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-400'
    agent:
      title: Agent
      description: Identification of a financial institution.
      type: object
      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-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
      description: Details to identify an account
      type: object
      required:
      - identification
      properties:
        identification:
          description: Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.
          type: string
          example: '111010151'
          minLength: 1
          maxLength: 17
        type:
          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
  securitySchemes:
    APIKeyQueryParam:
      type: apiKey
      in: query
      name: apikey