openapi: 3.2.0
info:
  version: 1.0.6
  title: Debit Authorizations Authorize to Pay API
  description: 'A buyer business wants to provide its bank account number or virtual card number, details on purpose of payment, and authorization for the supplier to debit the provided account number.  The buyer wishes to receive a real time acknowledgement when the instructions have been received. '
  contact:
    email: info@afinis.org
    url: https://www.afinis.org
servers:
- url: https://api.afinis.org/v1
tags:
- name: Authorize to Pay
paths:
  /debitauthorizations:
    post:
      description: Allow paying an outstanding invoice by electronically providing account information and authorization securely to the payee to execute the payment and receive an acknowledgement that payer account will be debited on desired date.
      operationId: Authorize to Pay - Request
      tags:
      - Authorize to Pay
      parameters:
      - name: apiVersion
        in: header
        required: true
        schema:
          type: string
          format: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-201'
        '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:
              - debtor
              - instructedAmount
              - pan
              - verification
              properties:
                debtor:
                  $ref: '#/components/schemas/party'
                endToEndIdentification:
                  type: string
                  minLength: 1
                  maxLength: 35
                  example: CBA321
                instructedAmount:
                  $ref: '#/components/schemas/amount'
                requestedExecutionDate:
                  type: string
                  maxLength: 10
                  minLength: 10
                  example: '2019-03-01'
                remittanceInformation:
                  $ref: '#/components/schemas/remittanceInformation'
                debtorAgent:
                  $ref: '#/components/schemas/agent'
                debtorAccount:
                  $ref: '#/components/schemas/account'
                verification:
                  $ref: '#/components/schemas/verification'
                expiryDate:
                  description: ISOYearMonth - YYYY-MM
                  type: string
                  minLength: 7
                  maxLength: 7
                  example: 2021-12
                cardholder:
                  $ref: '#/components/schemas/party'
        description: Pay an outstanding invoice electronically
        required: true
components:
  schemas:
    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'
    party:
      type: object
      properties:
        name:
          type: string
          maxLength: 70
          example: John Edison
        postalAddress:
          $ref: '#/components/schemas/postalAddress'
        identification:
          type: array
          items:
            $ref: '#/components/schemas/identification'
        phoneNumber:
          type: string
          maxLength: 30
          example: +1-302-515-5000
        emailAddress:
          type: string
          maxLength: 2048
          example: zachary.eastwood@ABCcorp.com
    postalAddress:
      description: Information that locates and identifies a specific address, as defined by postal services.
      type: object
      properties:
        streetName:
          description: Name of a street or throughfare
          type: string
          maxLength: 70
          example: Lexington Street
        postCode:
          description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail
          type: string
          maxLength: 11
          example: 19801
        townName:
          description: Name of a built-up area, with defined boundaries, and a local government
          type: string
          maxLength: 35
          example: Wilmington
        countrySubDivision:
          description: Identifies a subdivision of a country such as state, region, county
          type: string
          maxLength: 35
          example: DE
        country:
          description: Nation with its own government
          type: string
          minLength: 2
          maxLength: 2
          example: US
    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-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'
    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-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
    error-500:
      title: Internal Server Error
      description: 500 - Internal Server Error
      type: object
      required:
      - details
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/internalServerErrorDetails'
    verification:
      required:
      - authorizeToPay
      type: object
      properties:
        authorizeToPay:
          type: boolean
          description: Verification to specifically authorize the payment.
          example: true
        type:
          type: string
          example: CSCV
          enum:
          - CSCV
          description: "Name of the identification scheme:\n   * `CSCV` -  CSCVerification - Verification of Card Security Code              \n"
        textValue:
          type: string
          description: CVV code (3-4 characters) for virtual card
          example: '643'
          minLength: 1
          maxLength: 4
    remittanceInformation:
      type: object
      properties:
        number:
          type: string
          minLength: 1
          maxLength: 35
        relatedDate:
          type: string
          maxLength: 10
          minLength: 10
          example: '2019-03-01'
        duePayableAmount:
          $ref: '#/components/schemas/amount'
        discountAppliedAmount:
          $ref: '#/components/schemas/amount'
        adjustmentAmountAndReason:
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/amount'
            reason:
              type: string
              example: CM
              enum:
              - '01'
              - '03'
              - '04'
              - '05'
              - '06'
              - '07'
              - '11'
              - '12'
              - '59'
              - '75'
              - '81'
              - CM
              description: "Name of the identification scheme:\n   * `01` - Pricing Error    \n   * `03` - Extension Error    \n   * `04` - Item Not Accepted - Damaged    \n   * `05` - Item Not Accepted - Quality   \n   * `06` - Quantity Contested   \n   * `07` - Incorrect Product    \n   * `11` - Returns - Damage   \n   * `12` - Returns - Quality    \n   * `59` - Item not received    \n   * `75` - Total order not received \n   * `81` - Credit as Agreed    \n   * `CM` - Covered by Credit Memo   \n"
            additionalInformation:
              type: string
              minLength: 1
              maxLength: 140
        creditorReferenceInformation:
          $ref: '#/components/schemas/creditorReferenceInformation'
    amount:
      required:
      - name
      - currency
      type: object
      properties:
        amount:
          format: float
          example: 1.01
          minLength: 1
        currency:
          type: string
          example: USD
          maxLength: 3
          minLength: 3
    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
    identification:
      description: Information that locates and identifies a specific address, as defined by postal services.
      required:
      - identification
      type: object
      properties:
        identification:
          description: Identification assigned by an institution
          type: string
          maxLength: 35
          example: 1234567891
        schemeName:
          type: string
          example: CUST
          enum:
          - DUNS
          - CUST
          description: "Name of the identification scheme:\n   * `DUNS` - Data Universal Numbering System - A unique identification number provided by Dun & Bradstreet to identify an organisation.     \n   * `CUST` - CustomerNumber, Number assigned by an issuer to identify a customer\n"
    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
    response-201:
      title: Response 201 - Created
      type: object
      description: The request has succeeded and a new resource has been created as a result.
      properties:
        status:
          type: string
          example: Agree to debit
          enum:
          - Agree to debit
          - Do not agree to debit
        requestedExecutionDate:
          type: string
          description: Start date of the range
          example: '2020-04-29'
          minLength: 10
          maxLength: 10
        creditor:
          $ref: '#/components/schemas/party'
        originalEndToEndIdentification:
          type: string
          maxLength: 35
          example: CBA321
    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
          maxLength: 35
          example: 061103852
    creditorReferenceInformation:
      type: object
      properties:
        type:
          type: string
          example: PUOR
          enum:
          - PUOR
          description: "Name of the identification scheme:\n   * `PUOR` - PurchaseOrder - Document is a purchase order    \n"
        reference:
          type: string
          minLength: 1
          maxLength: 35
    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:
      description: Unique and unambiguous identification for the account between the account owner and the account servicer.
      type: object
      required:
      - identification
      - schemeName
      properties:
        identification:
          type: string
          description: Identification assigned by an institution
          example: '12345678'
          minLength: 1
          maxLength: 17
        schemeName:
          type: string
          example: DDA
          enum:
          - DDA
          - Virtual Card
          description: "Name of the identification scheme:\n   * `DDA` - DDA   \n   * `Virtual Card` - Virtual Card    \n"
    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
  securitySchemes:
    APIKeyQueryParam:
      type: apiKey
      in: query
      name: apikey