Bank of us Banking Account Transactions API

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 Banking Account Balances Banking Account Transactions API
  version: 1.36.0
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- description: Banking Account Transaction endpoints
  name: Banking Account Transactions
  x-shortName: Transactions
paths:
  /banking/accounts/{accountId}/transactions:
    get:
      description: 'Obtain transactions for a specific account.


        Some general notes that apply to all endpoints that retrieve transactions:<ul><li>Where multiple transactions are returned, transactions should be ordered according to effective date in descending order<li>As the date and time for a transaction can alter depending on status and transaction type two separate date/times are included in the payload. There are still some scenarios where neither of these time stamps is available. For the purpose of filtering and ordering it is expected that the data holder will use the "effective" date/time which will be defined as:<ul><li>Posted date/time if available, then<li>Execution date/time if available, then<li>A reasonable date/time nominated by the data holder using internal data structures</ul><li>For transaction amounts it should be assumed that a negative value indicates a reduction of the available balance on the account while a positive value indicates an increase in the available balance on the account<li>For aggregated transactions (i.e. groups of sub transactions reported as a single entry for the account) only the aggregated information, with as much consistent information across the subsidiary transactions as possible, is required to be shared.</ul>


        Obsolete versions: [v1](includes/obsolete/get-transactions-for-account-v1.html).'
      operationId: listBankingTransactions
      parameters:
      - description: The _accountId_ to obtain data for. _accountId_ values are returned by account list endpoints.
        explode: false
        in: path
        name: accountId
        required: true
        schema:
          $ref: '#/components/schemas/BankingAccountId'
        style: simple
      - description: Constrain the transaction history request to transactions with effective time at or after this date/time. If absent defaults to _newest-time_ minus 90 days. Format is aligned to [DateTimeString](#common-field-types) common type.
        explode: true
        in: query
        name: oldest-time
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateTimeString
      - description: Constrain the transaction history request to transactions with effective time at or before this date/time. If absent defaults to today. Format is aligned to [DateTimeString](#common-field-types) common type.
        explode: true
        in: query
        name: newest-time
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateTimeString
      - description: Filter transactions to only transactions with amounts higher than or equal to this amount.
        explode: true
        in: query
        name: min-amount
        required: false
        schema:
          type: string
        style: form
        x-cds-type: AmountString
      - description: Filter transactions to only transactions with amounts less than or equal to this amount.
        explode: true
        in: query
        name: max-amount
        required: false
        schema:
          type: string
        style: form
        x-cds-type: AmountString
      - description: Filter transactions to only transactions where this string value is found as a substring of either the _reference_ or _description_ fields. Format is arbitrary ASCII string. This parameter is optionally implemented by data holders. If it is not implemented then a response should be provided as normal without text filtering applied and an additional boolean field named _isQueryParamUnsupported_ should be included in the meta object and set to `true` (whether the text parameter is supplied or not).
        explode: true
        in: query
        name: text
        required: false
        schema:
          type: string
        style: form
      - description: Page of results to request (standard pagination).
        explode: true
        in: query
        name: page
        required: false
        schema:
          default: 1
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - description: Page size to request. Default is 25 (standard pagination).
        explode: true
        in: query
        name: page-size
        required: false
        schema:
          default: 25
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: An **[[RFC4122]](#nref-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]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
        explode: false
        in: header
        name: x-fapi-interaction-id
        required: false
        schema:
          type: string
        style: simple
      - description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls.
        explode: false
        in: header
        name: x-fapi-auth-date
        required: false
        schema:
          type: string
        style: simple
        x-conditional: true
      - description: The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
        explode: false
        in: header
        name: x-fapi-customer-ip-address
        required: false
        schema:
          type: string
        style: simple
      - description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls.
        explode: false
        in: header
        name: x-cds-client-headers
        required: false
        schema:
          type: string
        style: simple
        x-conditional: true
        x-cds-type: Base64
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBankingTransactionListV2'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Missing Required Header](#error-400-header-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li><li>[400 - Invalid Page Size](#error-400-field-invalid-page-size)</li><li>[400 - Invalid Date](#error-400-field-invalid-date-time)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[404 - Unavailable Banking Account](#error-404-authorisation-unavailable-banking-account)</li><li>[404 - Invalid Banking Account](#error-404-authorisation-invalid-banking-account)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[422 - Invalid Page](#error-422-field-invalid-page)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
      summary: Get Transactions For Account
      tags:
      - Banking Account Transactions
      x-scopes:
      - bank:transactions:read
      x-version: '2'
  /banking/accounts/{accountId}/transactions/{transactionId}:
    get:
      description: 'Obtain detailed information on a transaction for a specific account.


        Obsolete versions: [v1](includes/obsolete/get-transaction-detail-v1.html), [v2](includes/obsolete/get-transaction-detail-v2.html).'
      operationId: getBankingTransactionDetail
      parameters:
      - description: The _accountId_ to obtain data for. _accountId_ values are returned by account list endpoints.
        explode: false
        in: path
        name: accountId
        required: true
        schema:
          $ref: '#/components/schemas/BankingAccountId'
        style: simple
      - description: The _transactionId_ to obtain data for. _transactionId_ values are returned by transaction list endpoints.
        explode: false
        in: path
        name: transactionId
        required: true
        schema:
          $ref: '#/components/schemas/BankingTransactionId'
        style: simple
      - description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: An **[[RFC4122]](#nref-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]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
        explode: false
        in: header
        name: x-fapi-interaction-id
        required: false
        schema:
          type: string
        style: simple
      - description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls.
        explode: false
        in: header
        name: x-fapi-auth-date
        required: false
        schema:
          type: string
        style: simple
        x-conditional: true
      - description: The customer's original IP address if the customer is currently logged in to the Data Recipient Software Product. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls.
        explode: false
        in: header
        name: x-fapi-customer-ip-address
        required: false
        schema:
          type: string
        style: simple
      - description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the Data Recipient Software Product. Mandatory for customer present calls. Not required for unattended or unauthenticated calls.
        explode: false
        in: header
        name: x-cds-client-headers
        required: false
        schema:
          type: string
        style: simple
        x-conditional: true
        x-cds-type: Base64
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBankingTransactionByIdV3'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Missing Required Header](#error-400-header-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li><li>[400 - Invalid Date](#error-400-field-invalid-date-time)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[404 - Unavailable Banking Account](#error-404-authorisation-unavailable-banking-account)</li><li>[404 - Invalid Banking Account](#error-404-authorisation-invalid-banking-account)</li><li>[404 - Unavailable Resource](#error-404-resource-unavailable)</li><li>[404 - Invalid Resource](#error-404-resource-invalid)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/XFAPIInteractionId'
      summary: Get Transaction Detail
      tags:
      - Banking Account Transactions
      x-scopes:
      - bank:transactions:read
      x-version: '3'
components:
  schemas:
    ErrorV2_meta:
      description: Additional data for customised error codes.
      properties:
        urn:
          description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code.
          type: string
      type: object
      x-conditional:
      - urn
    MetaPaginatedTransaction_allOf:
      properties:
        isQueryParamUnsupported:
          default: false
          description: '`true` if _text_ query parameter is not supported.'
          type: boolean
      type: object
    ResponseBankingTransactionListV2:
      properties:
        data:
          $ref: '#/components/schemas/ResponseBankingTransactionListV2_data'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginatedTransaction'
      required:
      - data
      - links
      - meta
      type: object
    BankingTransactionV2:
      properties:
        accountId:
          allOf:
          - $ref: '#/components/schemas/BankingAccountId'
          description: Unique identifier for the account.
        transactionId:
          allOf:
          - $ref: '#/components/schemas/BankingTransactionId'
          description: Unique identifier for the transaction. This is mandatory (through hashing if necessary) unless there are specific and justifiable technical reasons why a transaction cannot be uniquely identified for a particular account type. Mandatory if the _isDetailAvailable_ value is `true`.
        isDetailAvailable:
          description: '`true` if extended information is available using the transaction detail endpoint. `false` if extended data is not available.'
          type: boolean
        type:
          description: The type of the transaction.
          enum:
          - DIRECT_DEBIT
          - FEE
          - INTEREST_CHARGED
          - INTEREST_PAID
          - OTHER
          - PAYMENT
          - TRANSFER_INCOMING
          - TRANSFER_OUTGOING
          type: string
        status:
          description: Status of the transaction whether pending or posted. Note that there is currently no provision in the standards to guarantee the ability to correlate a pending transaction with an associated posted transaction.
          enum:
          - PENDING
          - POSTED
          type: string
        description:
          description: The transaction description as applied by the financial institution.
          type: string
        postingDateTime:
          description: The time the transaction was posted. This field is Mandatory if the transaction has status `POSTED`. This is the time that appears on a standard statement.
          type: string
          x-cds-type: DateTimeString
        valueDateTime:
          description: Date and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry.
          type: string
          x-cds-type: DateTimeString
        executionDateTime:
          description: The time the transaction was executed by the originating customer, if available.
          type: string
          x-cds-type: DateTimeString
        amount:
          description: The value of the transaction. Negative values mean money was outgoing from the account.
          type: string
          x-cds-type: AmountString
        currency:
          default: AUD
          description: The currency for the transaction amount. `AUD` assumed if not present.
          type: string
          x-cds-type: CurrencyString
        reference:
          description: The reference for the transaction provided by the originating institution. Empty string if no data provided.
          type: string
        merchantName:
          description: Name of the merchant for an outgoing payment to a merchant.
          type: string
        merchantCategoryCode:
          description: The merchant category code (or MCC) for an outgoing payment to a merchant.
          type: string
        instalmentPlanId:
          allOf:
          - $ref: '#/components/schemas/BankingInstalmentPlanId'
          description: If the transaction is associated with an instalment plan, the corresponding _planId_ value. It should be noted that if the transaction is for a fee associated with a plan, or any amount of repayment, the _amount_ of the transaction may not match a scheduled instalment amount.
        billerCode:
          description: BPAY Biller Code for the transaction (if available).
          type: string
        billerName:
          description: Name of the BPAY biller for the transaction (if available).
          type: string
        crn:
          description: BPAY CRN for the transaction (if available).<br/>Where the CRN contains sensitive information, it should be masked in line with how the Data Holder currently displays account identifiers in their existing online banking channels. If the contents of the CRN match the format of a Credit Card PAN they should be masked according to the rules applicable for [MaskedPANString](#common-field-types). If the contents are otherwise sensitive, then it should be masked using the rules applicable for the [MaskedAccountString](#common-field-types) common type.
          type: string
        apcaNumber:
          description: 6 Digit APCA number for the initiating institution. The field is fixed-width and padded with leading zeros if applicable.
          type: string
      required:
      - accountId
      - amount
      - description
      - isDetailAvailable
      - reference
      - status
      - type
      type: object
      x-conditional:
      - transactionId
      - postingDateTime
      - crn
    ResponseErrorListV2:
      properties:
        errors:
          description: List of errors.
          items:
            $ref: '#/components/schemas/ErrorV2'
          type: array
      required:
      - errors
      type: object
    BankingTransactionId:
      description: A unique identifier for a Banking transaction, generated according to [CDR ID Permanence](#id-permanence) requirements.
      type: string
      x-cds-type: ASCIIString
    LinksPaginated:
      properties:
        self:
          description: Fully qualified link that generated the current response document.
          type: string
          x-cds-type: URIString
        first:
          description: URI to the first page of this set. Mandatory if this response is not the first page.
          type: string
          x-cds-type: URIString
        prev:
          description: URI to the previous page of this set. Mandatory if this response is not the first page.
          type: string
          x-cds-type: URIString
        next:
          description: URI to the next page of this set. Mandatory if this response is not the last page.
          type: string
          x-cds-type: URIString
        last:
          description: URI to the last page of this set. Mandatory if this response is not the last page.
          type: string
          x-cds-type: URIString
      required:
      - self
      type: object
      x-conditional:
      - prev
      - next
      - first
      - last
    BankingTransactionDetailV3_allOf_extendedData:
      properties:
        payer:
          description: Label of the originating payer. Mandatory for inbound payment.
          type: string
        payee:
          description: Label of the target PayID. Mandatory for an outbound payment. The name assigned to the BSB/Account Number or PayID (by the owner of the PayID).
          type: string
        extensionUType:
          description: Optional extended data specific to transactions. Currently extended data is supported for NPP service overlays.
          enum:
          - nppPayload
          type: string
        nppPayload:
          $ref: '#/components/schemas/BankingTransactionDetailV3_allOf_extendedData_nppPayload'
      type: object
      x-conditional:
      - payer
      - payee
      - nppPayload
    Meta:
      type: object
    MetaPaginated:
      properties:
        totalRecords:
          description: The total number of records in the full set. See [pagination](#pagination).
          type: integer
          x-cds-type: NaturalNumber
        totalPages:
          description: The total number of pages in the full set. See [pagination](#pagination).
          type: integer
          x-cds-type: NaturalNumber
      required:
      - totalPages
      - totalRecords
      type: object
    ResponseBankingTransactionByIdV3:
      properties:
        data:
          $ref: '#/components/schemas/BankingTransactionDetailV3'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      - links
      type: object
    NppPaymentService:
      description: Identifier of the applicable overlay service. The _service_ is used in conjunction with the _serviceVersion_. See [here](#npp-services) for more details.
      enum:
      - X2P1
      - IFTI
      - BSCT
      - CATSCT
      example: X2P1
      type: string
    BankingAccountId:
      description: A unique identifier for a Banking account, generated according to [CDR ID Permanence](#id-permanence) requirements.
      type: string
      x-cds-type: ASCIIString
    BankingTransactionDetailV3_allOf_extendedData_nppPayload:
      description: Mandatory if the _extensionUType_ value is `nppPayload`.
      properties:
        extendedDescription:
          description: An extended string description. Mandatory if the _extensionUType_ value is `nppPayload`.
          type: string
        endToEndId:
          description: An end to end ID for the payment created at initiation.
          type: string
        purposeCode:
          description: Purpose of the payment. Format is defined by the NPP standards for the NPP overlay services including Osko (X2P1).
          type: string
          x-cds-type: ExternalRef
        service:
          $ref: '#/components/schemas/NppPaymentService'
        serviceVersion:
          description: Two-digit NPP service overlay version with leading zero.
          example: '03'
          type: string
          x-cds-type: ExternalRef
      required:
      - service
      - serviceVersion
      type: object
      x-conditional:
      - extendedDescription
    ResponseBankingTransactionListV2_data:
      properties:
        transactions:
          items:
            $ref: '#/components/schemas/BankingTransactionV2'
          type: array
      required:
      - transactions
      type: object
    BankingTransactionDetailV3_allOf:
      properties:
        extendedData:
          $ref: '#/components/schemas/BankingTransactionDetailV3_allOf_extendedData'
      required:
      - extendedData
      type: object
    Links:
      properties:
        self:
          description: Fully qualified link that generated the current response document.
          type: string
          x-cds-type: URIString
      required:
      - self
      type: object
    MetaPaginatedTransaction:
      allOf:
      - $ref: '#/components/schemas/MetaPaginated'
      - $ref: '#/components/schemas/MetaPaginatedTransaction_allOf'
    ErrorV2:
      properties:
        code:
          description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN.
          type: string
        title:
          description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        meta:
          $ref: '#/components/schemas/ErrorV2_meta'
      required:
      - code
      - detail
      - title
      type: object
      x-conditional:
      - meta
    BankingTransactionDetailV3:
      allOf:
      - $ref: '#/components/schemas/BankingTransactionV2'
      - $ref: '#/components/schemas/BankingTransactionDetailV3_allOf'
    BankingInstalmentPlanId:
      description: A unique identifier for a Banking instalment plan, generated according to [CDR ID Permanence](#id-permanence) requirements.
      type: string
      x-cds-type: ASCIIString
  headers:
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      explode: false
      required: true
      schema:
        type: string
      style: simple
    XFAPIInteractionId:
      description: An **[[RFC4122]](#nref-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]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction.
      explode: false
      required: true
      schema:
        type: string
      style: simple