openapi: 3.0.3
info:
  contact:
    email: contact@dsb.gov.au
    name: Data Standards Body
    url: https://dsb.gov.au/
  description: Specifications for resource endpoints applicable to data holders in the Banking sector.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  title: CDR Banking Accounts Direct Debits API
  version: 1.36.0
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Direct Debits
paths:
  /banking/accounts/{accountId}/direct-debits:
    get:
      tags:
      - Direct Debits
      summary: Get Direct Debits For Account
      description: Obtain direct debit authorisations for a specific account
      operationId: listDirectDebits
      parameters:
      - name: accountId
        in: path
        description: ID of the account to get direct debit authorisations for.  Must have previously been returned by one of the account list end points.
        required: true
        schema:
          type: string
          x-cds-type: ASCIIString
        x-cds-type: ASCIIString
      - name: page
        in: query
        description: Page of results to request (standard pagination)
        schema:
          type: integer
          default: 1
          x-cds-type: PositiveInteger
        x-cds-type: PositiveInteger
      - name: page-size
        in: query
        description: Page size to request. Default is 25 (standard pagination)
        schema:
          type: integer
          default: 25
          x-cds-type: PositiveInteger
        x-cds-type: PositiveInteger
      - name: x-v
        in: header
        description: Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ) and [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ). If the value of [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ) is equal to or higher than the value of [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ) then the [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ) header should be treated as absent. If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable. See [HTTP Headers](https://consumerdatastandardsaustralia.github.io/standards/#http-headers )
        required: true
        schema:
          type: string
          default: '1'
      - name: x-min-v
        in: header
        description: Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ) and [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers ). If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable.
        schema:
          type: string
      - name: x-fapi-interaction-id
        in: header
        description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
        schema:
          type: string
          format: uuid
      - name: x-fapi-auth-date
        in: header
        description: The time when the customer last logged in to the data recipient. Required for all resource calls (customer present and unattended). Not to be included for unauthenticated calls.
        schema:
          type: string
      - name: x-fapi-customer-ip-address
        in: header
        description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
        schema:
          type: string
      - name: x-cds-client-headers
        in: header
        description: The customer's original standard http headers [Base64](https://consumerdatastandardsaustralia.github.io/standards/#common-field-types) encoded, including the original User Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls.  Not required for unattended or unauthenticated calls.
        schema:
          pattern: ^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$
          type: string
          x-cds-type: Base64
        x-cds-type: Base64
      responses:
        '200':
          description: Success
          headers:
            x-v:
              description: The [version](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) of the API end point that the data holder has responded with.
              schema:
                type: string
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBankingDirectDebitAuthorisationList'
        '400':
          description: Bad Request
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '404':
          description: Not Found
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '406':
          description: Not Acceptable
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '422':
          description: Unprocessable Entity
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
      security:
      - PSUOAuth2Security:
        - bank:regular_payments:read
      - default:
        - bank:regular_payments:read
      x-version: '1'
      x-auth-type: Application User
      x-throttling-tier: Unlimited
  /banking/accounts/direct-debits:
    get:
      tags:
      - Direct Debits
      summary: Get Bulk Direct Debits
      description: Obtain direct debit authorisations for multiple, filtered accounts
      operationId: listDirectDebitsBulk
      parameters:
      - name: product-category
        in: query
        description: Used to filter results on the productCategory field applicable to accounts. Any one of the valid values for this field can be supplied. If absent then all accounts returned.
        schema:
          type: string
          enum:
          - TRANS_AND_SAVINGS_ACCOUNTS
          - TERM_DEPOSITS
          - TRAVEL_CARDS
          - REGULATED_TRUST_ACCOUNTS
          - RESIDENTIAL_MORTGAGES
          - CRED_AND_CHRG_CARDS
          - PERS_LOANS
          - MARGIN_LOANS
          - LEASES
          - TRADE_FINANCE
          - OVERDRAFTS
          - BUSINESS_LOANS
      - name: open-status
        in: query
        description: Used to filter results according to open/closed status. Values can be OPEN, CLOSED or ALL. If absent then ALL is assumed
        schema:
          type: string
          default: ALL
          enum:
          - OPEN
          - CLOSED
          - ALL
      - name: is-owned
        in: query
        description: Filters accounts based on whether they are owned by the authorised customer.  True for owned accounts, false for unowned accounts and absent for all accounts
        schema:
          type: boolean
          x-cds-type: Boolean
        x-cds-type: Boolean
      - name: page
        in: query
        description: Page of results to request (standard pagination)
        schema:
          type: integer
          default: 1
          x-cds-type: PositiveInteger
        x-cds-type: PositiveInteger
      - name: page-size
        in: query
        description: Page size to request. Default is 25 (standard pagination)
        schema:
          type: integer
          default: 25
          x-cds-type: PositiveInteger
        x-cds-type: PositiveInteger
      - name: x-v
        in: header
        description: Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) and [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers). If the value of [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) is equal to or higher than the value of [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) then the [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) header should be treated as absent. If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable. See [HTTP Headers](https://consumerdatastandardsaustralia.github.io/standards/#http-headers)
        required: true
        schema:
          type: string
          default: '1'
      - name: x-min-v
        in: header
        description: Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) and [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers). If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable.
        schema:
          type: string
      - name: x-fapi-interaction-id
        in: header
        description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
        schema:
          type: string
          format: uuid
      - name: x-fapi-auth-date
        in: header
        description: The time when the customer last logged in to the data recipient. Required for all resource calls (customer present and unattended). Not to be included for unauthenticated calls.
        schema:
          type: string
      - name: x-fapi-customer-ip-address
        in: header
        description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
        schema:
          type: string
      - name: x-cds-client-headers
        in: header
        description: The customer's original standard http headers [Base64](https://consumerdatastandardsaustralia.github.io/standards/#common-field-types) encoded, including the original User Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls.  Not required for unattended or unauthenticated calls.
        schema:
          pattern: ^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$
          type: string
          x-cds-type: Base64
        x-cds-type: Base64
      responses:
        '200':
          description: Success
          headers:
            x-v:
              description: The [version](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) of the API end point that the data holder has responded with.
              schema:
                type: string
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBankingDirectDebitAuthorisationList'
        '400':
          description: Bad Request
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '406':
          description: Not Acceptable
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '422':
          description: Unprocessable Entity
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
      security:
      - PSUOAuth2Security:
        - bank:regular_payments:read
      - default:
        - bank:regular_payments:read
      x-version: '1'
      x-auth-type: Application User
      x-throttling-tier: Unlimited
    post:
      tags:
      - Direct Debits
      summary: Get Direct Debits For Specific Accounts
      description: Obtain direct debit authorisations for a specified list of accounts
      operationId: listDirectDebitsSpecificAccounts
      parameters:
      - name: page
        in: query
        description: Page of results to request (standard pagination)
        schema:
          type: integer
          default: 1
          x-cds-type: PositiveInteger
        x-cds-type: PositiveInteger
      - name: page-size
        in: query
        description: Page size to request. Default is 25 (standard pagination)
        schema:
          type: integer
          default: 25
          x-cds-type: PositiveInteger
        x-cds-type: PositiveInteger
      - name: x-v
        in: header
        description: Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) and [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers). If the value of [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) is equal to or higher than the value of [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) then the [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) header should be treated as absent. If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable. See [HTTP Headers](https://consumerdatastandardsaustralia.github.io/standards/#http-headers)
        required: true
        schema:
          type: string
          default: '1'
      - name: x-min-v
        in: header
        description: Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between [x-min-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) and [x-v](https://consumerdatastandardsaustralia.github.io/standards/#http-headers). If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable.
        schema:
          type: string
      - name: x-fapi-interaction-id
        in: header
        description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
        schema:
          type: string
          format: uuid
      - name: x-fapi-auth-date
        in: header
        description: The time when the customer last logged in to the data recipient. Required for all resource calls (customer present and unattended). Not to be included for unauthenticated calls.
        schema:
          type: string
      - name: x-fapi-customer-ip-address
        in: header
        description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
        schema:
          type: string
      - name: x-cds-client-headers
        in: header
        description: The customer's original standard http headers [Base64](https://consumerdatastandardsaustralia.github.io/standards/#common-field-types) encoded, including the original User Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls.  Not required for unattended or unauthenticated calls.
        schema:
          pattern: ^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$
          type: string
          x-cds-type: Base64
        x-cds-type: Base64
      requestBody:
        description: Array of specific accountIds to obtain authorisations for
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestAccountIds'
        required: true
      responses:
        '200':
          description: Success
          headers:
            x-v:
              description: The [version](https://consumerdatastandardsaustralia.github.io/standards/#http-headers) of the API end point that the data holder has responded with.
              schema:
                type: string
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBankingDirectDebitAuthorisationList'
        '400':
          description: Bad Request
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '406':
          description: Not Acceptable
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
        '422':
          description: Unprocessable Entity
          headers:
            x-fapi-interaction-id:
              description: An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorList'
      security:
      - PSUOAuth2Security:
        - bank:regular_payments:read
      - default:
        - bank:regular_payments:read
      x-version: '1'
      x-auth-type: Application User
      x-throttling-tier: Unlimited
      x-codegen-request-body-name: accountIds
components:
  schemas:
    BankingAuthorisedEntity:
      type: object
      properties:
        description:
          type: string
          description: Description of the authorised entity derived from previously executed direct debits
        financialInstitution:
          type: string
          description: Name of the financial institution through which the direct debit will be executed. Is required unless the payment is made via a credit card scheme
        abn:
          type: string
          description: Australian Business Number for the authorised entity
        acn:
          type: string
          description: Australian Company Number for the authorised entity
        arbn:
          type: string
          description: Australian Registered Body Number for the authorised entity
    RequestAccountIds:
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RequestAccountIds_data'
        meta:
          $ref: '#/components/schemas/Meta'
    ResponseBankingDirectDebitAuthorisationList:
      required:
      - data
      - links
      - meta
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ResponseBankingDirectDebitAuthorisationList_data'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
    Meta:
      type: object
    ResponseErrorList:
      required:
      - errors
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseErrorList_errors'
    RequestAccountIds_data:
      required:
      - accountIds
      type: object
      properties:
        accountIds:
          type: array
          items:
            type: string
            description: Array of specific accountIds to obtain authorisations for
            x-cds-type: ASCIIString
    BankingDirectDebit:
      required:
      - accountId
      - authorisedEntity
      type: object
      properties:
        accountId:
          type: string
          description: A unique ID of the account adhering to the standards for ID permanence.
          x-cds-type: ASCIIString
        authorisedEntity:
          $ref: '#/components/schemas/BankingAuthorisedEntity'
        lastDebitDateTime:
          type: string
          description: The date and time of the last debit executed under this authorisation
          x-cds-type: DateTimeString
        lastDebitAmount:
          type: string
          description: The amount of the last debit executed under this authorisation
          x-cds-type: AmountString
    MetaPaginated:
      required:
      - totalPages
      - totalRecords
      type: object
      properties:
        totalRecords:
          type: integer
          description: The total number of records in the full set. See [pagination](https://consumerdatastandardsaustralia.github.io/standards/#pagination).
          x-cds-type: NaturalNumber
        totalPages:
          type: integer
          description: The total number of pages in the full set. See [pagination](https://consumerdatastandardsaustralia.github.io/standards/#pagination).
          x-cds-type: NaturalNumber
    ResponseErrorList_errors:
      required:
      - code
      - detail
      - title
      type: object
      properties:
        code:
          type: string
          description: Error code
        title:
          type: string
          description: Error title
        detail:
          type: string
          description: Error details
        meta:
          type: object
          properties: {}
          description: Optional additional data for specific error types
    ResponseBankingDirectDebitAuthorisationList_data:
      required:
      - directDebitAuthorisations
      type: object
      properties:
        directDebitAuthorisations:
          type: array
          description: The list of authorisations returned
          items:
            $ref: '#/components/schemas/BankingDirectDebit'
    LinksPaginated:
      required:
      - self
      type: object
      properties:
        self:
          type: string
          description: Fully qualified link that generated the current response document
          x-cds-type: URIString
        first:
          type: string
          description: URI to the first page of this set. Mandatory if this response is not the first page
          x-cds-type: URIString
        prev:
          type: string
          description: URI to the previous page of this set. Mandatory if this response is not the first page
          x-cds-type: URIString
        next:
          type: string
          description: URI to the next page of this set. Mandatory if this response is not the last page
          x-cds-type: URIString
        last:
          type: string
          description: URI to the last page of this set. Mandatory if this response is not the last page
          x-cds-type: URIString
      x-conditional:
      - prev
      - next
      - first
      - last