openapi: 3.2.0
info:
  description: Afinis is a diverse group of organizations working to support advancement and use of API standardization in the financial services industry. Utilization of this API requires a developer to [register](https://www.afinis.org/user/register) their application.
  version: 1.0.7
  title: Initiate Payment ACH Payments API
  contact:
    email: info@afinis.org
    url: https://www.afinis.org
servers:
- url: https://api.asig.org/v1
tags:
- name: ACH Payments
paths:
  /payments/ach/debit:
    post:
      operationId: ACH Payments Debit
      tags:
      - ACH Payments
      summary: Process ACH Debit Transactions
      description: Process ACH Debit Transactions
      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: Payment transactions RCVD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/initiatePaymentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-401'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-500'
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentInformation:
                  $ref: '#/components/schemas/paymentInformationDebit'
        description: ACH details to process debit transactions
        required: true
  /payments/ach/credit:
    post:
      operationId: ACH Payments Credit
      tags:
      - ACH Payments
      summary: Process ACH Credit Transactions
      description: Process ACH Credit Transactions
      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: Payment transactions  RCVD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/initiatePaymentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-401'
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-500'
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentInformation:
                  $ref: '#/components/schemas/paymentInformationCredit'
        description: ACH details to process credit transactions
        required: true
components:
  schemas:
    paymentInformationDebit:
      title: PaymentInformationDebit
      type: object
      required:
      - creditor
      - directDebitTransactionInformation
      properties:
        paymentInformationIdentification:
          $ref: '#/components/schemas/paymentInformationIdentification'
        creditor:
          $ref: '#/components/schemas/creditor'
        creditorAccount:
          $ref: '#/components/schemas/creditorAccount'
        directDebitTransactionInformation:
          $ref: '#/components/schemas/directDebitTransactionInformation'
    creditorAccount:
      title: CreditorAccount
      type: object
      required:
      - identification
      properties:
        identification:
          description: Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.
          type: string
          example: '2345678911'
          maxLength: 17
    error-401:
      title: 401 Error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-401'
    discretionaryData:
      title: DiscretionaryData
      type: string
      description: Additional information.
      example: 957abc
      maxLength: 20
    errorDetails:
      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 JSON structure.
          type: string
      required:
      - errorcode
      - message
    categoryPurpose:
      title: CategoryPurpose
      description: Specifies the high-level purpose of the instruction based on a set of pre-defined categories
      type: object
      required:
      - proprietary
      properties:
        proprietary:
          description: Category purpose, in a proprietary form.
          type: string
          example: Payment
          maxLength: 10
    instructedAmount:
      title: InstructedAmount
      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
          example: 100.01
          maxLength: 11
        currency:
          type: string
          example: USD
          default: USD
    settlementTimeIndication:
      title: SettlementTimeIndication
      description: Provides information on the occurred settlement time(s) of the payment transaction.
      type: string
      example: '2018-12-12T13:00:00'
    paymentIdentification:
      title: PaymentIdentification
      type: object
      required:
      - instructionIdentification
      properties:
        instructionIdentification:
          description: Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.
          type: string
          example: ABC0928
          maxLength: 11
        endToEndIdentification:
          description: Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.
          type: string
          example: ABC13609-15-18
          maxLength: 22
    transactionCreditorAccount:
      title: TransactionCreditorAccount
      type: object
      required:
      - identification
      - type
      properties:
        identification:
          description: Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction
          type: string
          example: '2345678911'
          maxLength: 17
        type:
          type: string
          enum:
          - CACC: null
            description: Current Account used to post debits and credits when no specific account has been nominated
          - SCGS: null
            description: Account used for savings
          example: CACC
    transactionCreditor:
      title: TransactionCreditor
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: John Smith
          maxLength: 22
    paymentInformationIdentification:
      title: PaymentInformationIdentification
      description: Unique identification, as assigned by a sending party, to unambiguously identify the payment information group within the message.
      type: string
      example: 1001ABCUSDO1_20181212
    transactionDebtor:
      title: TransactionDebtor
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: John Q. Public
          maxLength: 22
    unstructured:
      title: unstructured
      description: Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.
      type: array
      items:
        type: object
        properties:
          lineNumber:
            type: integer
            example: 1
          value:
            type: string
            example: Addenda 1
    debtorAgent:
      title: DebtorAgent
      type: object
      description: Financial institution servicing an account for the debtor.
      required:
      - clearingSystemIdentification
      - memberIdentification
      properties:
        clearingSystemIdentification:
          description: Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed
          type: string
          example: USABA
          enum:
          - CACPA: null
            description: Bank Branch Code used in Canada.
          - USABA: null
            description: Routing Transit number assigned by the ABA for US financial Institutions.
        memberIdentification:
          description: Identification of a member of a clearing system  e.g., a U.S. transit routing number or Canadian Payments Association Routing Number
          type: string
          minLength: 9
          maxLength: 9
          example: 061103852
    error-500:
      title: 500 Error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails-500'
    remittanceInformation:
      title: RemittanceInformation
      description: Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.
      type: array
      items:
        type: object
        properties:
          unstructured:
            $ref: '#/components/schemas/unstructured'
    debtorAccount:
      title: DebtorAccount
      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'
          maxLength: 17
    creditor:
      title: Creditor
      type: object
      description: Party to which an amount of money is due.
      required:
      - identification
      properties:
        identification:
          description: Identification assigned by an institution
          type: string
          example: '1234567891'
          maxLength: 10
        name:
          type: string
          example: XYZ Supply Co.
          maxLength: 16
    transactionDebtorAccount:
      title: TransactionDebtorAccount
      type: object
      required:
      - identification
      - type
      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: '1111111122'
          maxLength: 17
        type:
          type: string
          enum:
          - CACC: null
            description: Current Account used to post debits and credits when no specific account has been nominated
          - SCGS: null
            description: Account used for savings
          example: CACC
    errorDetails-401:
      title: 401 ErrorDetails
      type: object
      properties:
        errorcode:
          description: A programmatic error code
          example: 1000
          type: number
        message:
          description: A human readable description of the problem
          example: API key is missing, invalid or expired.
          type: string
      required:
      - errorcode
      - message
    paymentInformationCredit:
      title: PaymentInformationCredit
      type: object
      required:
      - debtor
      - creditTransferTransactionInformation
      properties:
        paymentInformationIdentification:
          $ref: '#/components/schemas/paymentInformationIdentification'
        debtor:
          $ref: '#/components/schemas/debtor'
        debtorAccount:
          $ref: '#/components/schemas/debtorAccount'
        creditTransferTransactionInformation:
          $ref: '#/components/schemas/creditTransferTransactionInformation'
    paymentTypeInformation:
      title: PaymentTypeInformation
      description: Set of elements used to further specify the type of transaction.
      type: object
      required:
      - localInstrument
      properties:
        localInstrument:
          type: string
          example: WEB
          enum:
          - CCD: null
          - CTX: null
          - PPD: null
          - WEB: null
          - TEL: null
          - CIE: null
        sequenceType:
          type: string
          default: OOFF
          enum:
          - OOFF: null
            description: Direct debit instruction where the debtor's authorization is used to initiate on single direct debt transaction.
          - RCUR: null
            description: Direct debit transaction where the debtor authorization is used for regular direct debit transactions initiated by the creditor.
        categoryPurpose:
          $ref: '#/components/schemas/categoryPurpose'
    debtor:
      title: Debtor
      type: object
      description: Party that owes an amount of money to the (ultimate) creditor.
      required:
      - identification
      properties:
        identification:
          description: Identification assigned by an institution
          type: string
          example: '1234567891'
          maxLength: 10
        name:
          type: string
          example: Company ABC
          maxLength: 16
    creditTransferTransactionInformation:
      title: CreditTransferTransactionInformation
      type: array
      required:
      - paymentIdentification
      - paymentTypeInformation
      - instructedAmount
      - requestedExecutionDate
      - creditor
      - creditorAccount
      - creditorAgent
      items:
        type: object
        properties:
          paymentIdentification:
            $ref: '#/components/schemas/paymentIdentification'
          paymentTypeInformation:
            $ref: '#/components/schemas/paymentTypeInformation'
          discretionaryData:
            $ref: '#/components/schemas/discretionaryData'
          requestedExecutionDate:
            type: string
            example: '2018-12-12'
            maxLength: 10
          settlementTimeIndication:
            $ref: '#/components/schemas/settlementTimeIndication'
          instructedAmount:
            $ref: '#/components/schemas/instructedAmount'
          creditorAgent:
            $ref: '#/components/schemas/creditorAgent'
          creditor:
            $ref: '#/components/schemas/transactionCreditor'
          creditorAccount:
            $ref: '#/components/schemas/transactionCreditorAccount'
          remittanceInformation:
            $ref: '#/components/schemas/remittanceInformation'
    directDebitTransactionInformation:
      title: DirectDebitTransactionInformation
      type: array
      required:
      - paymentIdentification
      - paymentTypeInformation
      - instructedAmount
      - requestedCollectionDate
      - debtor
      - debtorAccount
      - debtorAgent
      items:
        type: object
        properties:
          paymentIdentification:
            $ref: '#/components/schemas/paymentIdentification'
          paymentTypeInformation:
            $ref: '#/components/schemas/paymentTypeInformation'
          discretionaryData:
            $ref: '#/components/schemas/discretionaryData'
          requestedCollectionDate:
            type: string
            example: '2018-12-12'
          settlementTimeIndication:
            $ref: '#/components/schemas/settlementTimeIndication'
          instructedAmount:
            $ref: '#/components/schemas/instructedAmount'
          debtorAgent:
            $ref: '#/components/schemas/debtorAgent'
          debtor:
            $ref: '#/components/schemas/transactionDebtor'
          debtorAccount:
            $ref: '#/components/schemas/transactionDebtorAccount'
          remittanceInformation:
            $ref: '#/components/schemas/remittanceInformation'
    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
    initiatePaymentResponse:
      title: InitiatePaymentResponse
      type: object
      required:
      - transactionStatus
      - callback
      properties:
        transactionStatus:
          description: Payment initiation has been received by the receiving agent.
          type: string
          example: RCVD
        callback:
          description: Callback URL get transaction status.
          type: string
    error:
      title: Error
      type: object
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/errorDetails'
    creditorAgent:
      title: CreditorAgent
      type: object
      description: Financial institution servicing an account for the creditor.
      required:
      - memberIdentification
      - clearingSystemIdentification
      properties:
        clearingSystemIdentification:
          description: Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed
          type: string
          example: USABA
          enum:
          - CACPA: null
            description: Bank Branch Code used in Canada.
          - USABA: null
            description: Routing Transit number assigned by the ABA for US financial Institutions.
        memberIdentification:
          description: Identification of a member of a clearing system  e.g., a U.S. transit routing number or Canadian Payments Association Routing Number
          type: string
          minLength: 9
          maxLength: 9
          example: 061103852
  securitySchemes:
    APIKeyQueryParam:
      type: apiKey
      in: query
      name: apikey