openapi: 3.0.3
info:
  title: CDR Banking Banking Account Balances Banking Payees API
  version: 1.36.0
  description: Specifications for resource endpoints applicable to data holders in the Banking sector.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: Data Standards Body
    email: contact@dsb.gov.au
    url: https://dsb.gov.au/
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Banking Payees
  x-shortName: Payees
  description: Banking Payee endpoints
paths:
  /banking/payees:
    get:
      tags:
      - Banking Payees
      summary: Get Payees
      description: 'Obtain a list of pre-registered payees.


        Obsolete versions: [v1](includes/obsolete/get-payees-v1.html).'
      operationId: listBankingPayees
      parameters:
      - name: type
        in: query
        description: Filter on the payee _type_ field. In addition to normal _type_ field values, `ALL` can be specified to retrieve all payees. If absent the assumed value is `ALL`.
        schema:
          type: string
          default: ALL
          enum:
          - ALL
          - BILLER
          - DIGITAL_WALLET
          - DOMESTIC
          - INTERNATIONAL
      - $ref: '#/components/parameters/QueryPage'
      - $ref: '#/components/parameters/QueryPageSize'
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      responses:
        '200':
          $ref: '#/components/responses/ListBankingPayees200'
        '400':
          $ref: '#/components/responses/ListBankingPayees400'
        '406':
          $ref: '#/components/responses/ListBankingPayees406'
        '422':
          $ref: '#/components/responses/ListBankingPayees422'
      x-scopes:
      - bank:payees:read
      x-version: '2'
  /banking/payees/{payeeId}:
    get:
      tags:
      - Banking Payees
      summary: Get Payee Detail
      description: 'Obtain detailed information on a single payee.


        Note that the payee sub-structure should be selected to represent the payment destination only rather than any known characteristics of the payment recipient.


        Obsolete versions: [v1](includes/obsolete/get-payee-detail-v1.html).'
      operationId: getBankingPayeeDetail
      parameters:
      - name: payeeId
        in: path
        description: The _payeeId_ to obtain data for. _payeeId_ values are returned by payee list endpoints.
        required: true
        schema:
          $ref: '#/components/schemas/BankingPayeeId'
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      - $ref: '#/components/parameters/HeaderXFAPIInteractionId'
      - $ref: '#/components/parameters/HeaderXFAPIAuthDate'
      - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress'
      - $ref: '#/components/parameters/HeaderXCDSClientHeaders'
      responses:
        '200':
          $ref: '#/components/responses/GetBankingPayeeDetail200'
        '400':
          $ref: '#/components/responses/GetBankingPayeeDetail400'
        '404':
          $ref: '#/components/responses/GetBankingPayeeDetail404'
        '406':
          $ref: '#/components/responses/GetBankingPayeeDetail406'
        '422':
          $ref: '#/components/responses/GetBankingPayeeDetail422'
      x-scopes:
      - bank:payees:read
      x-version: '2'
components:
  responses:
    ListBankingPayees400:
      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></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetBankingPayeeDetail422:
      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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    ListBankingPayees422:
      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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    ListBankingPayees200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseBankingPayeeListV2'
    ListBankingPayees406:
      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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetBankingPayeeDetail200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseBankingPayeeByIdV2'
    GetBankingPayeeDetail406:
      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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetBankingPayeeDetail400:
      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></ul>
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/XFAPIInteractionId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetBankingPayeeDetail404:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
  parameters:
    HeaderXFAPICustomerIPAddress:
      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 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.
      schema:
        type: string
    HeaderXCDSClientHeaders:
      name: x-cds-client-headers
      in: header
      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.
      schema:
        type: string
      x-conditional: true
      x-cds-type: Base64
    HeaderXFAPIInteractionId:
      name: x-fapi-interaction-id
      in: header
      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.
      schema:
        type: string
    HeaderXV:
      name: x-v
      in: header
      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).
      required: true
      schema:
        type: string
    HeaderXMinV:
      name: x-min-v
      in: header
      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`.
      schema:
        type: string
    QueryPageSize:
      name: page-size
      in: query
      description: Page size to request. Default is 25 (standard pagination).
      schema:
        type: integer
        default: 25
      x-cds-type: PositiveInteger
    HeaderXFAPIAuthDate:
      name: x-fapi-auth-date
      in: header
      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.
      schema:
        type: string
      x-conditional: true
    QueryPage:
      name: page
      in: query
      description: Page of results to request (standard pagination).
      schema:
        type: integer
        default: 1
      x-cds-type: PositiveInteger
  schemas:
    BankingPayeeV2:
      required:
      - nickname
      - payeeId
      - type
      type: object
      properties:
        payeeId:
          description: Unique identifier for the payee.
          allOf:
          - $ref: '#/components/schemas/BankingPayeeId'
        nickname:
          type: string
          description: The short display name of the payee as provided by the customer. Where a customer has not provided a nickname, a display name derived by the bank for the payee consistent with existing digital banking channels.
        description:
          type: string
          description: A description of the payee provided by the customer.
        type:
          type: string
          description: The type of payee.<ul><li>`DOMESTIC` means a registered payee for domestic payments including NPP.<li>`INTERNATIONAL` means a registered payee for international payments.<li>`BILLER` means a registered payee for BPAY.<li>`DIGITAL_WALLET` means a registered payee for a bank's digital wallet.</ul>
          enum:
          - BILLER
          - DIGITAL_WALLET
          - DOMESTIC
          - INTERNATIONAL
        creationDate:
          type: string
          description: The date the payee was created by the customer.
          x-cds-type: DateString
    Meta:
      type: object
    Links:
      required:
      - self
      type: object
      properties:
        self:
          type: string
          description: Fully qualified link that generated the current response document.
          x-cds-type: URIString
    BankingPayeeDetailV2:
      allOf:
      - $ref: '#/components/schemas/BankingPayeeV2'
      - required:
        - payeeUType
        type: object
        properties:
          payeeUType:
            type: string
            description: Type of object included that describes the payee in detail.
            enum:
            - biller
            - digitalWallet
            - domestic
            - international
          biller:
            $ref: '#/components/schemas/BankingBillerPayee'
          domestic:
            $ref: '#/components/schemas/BankingDomesticPayee'
          digitalWallet:
            $ref: '#/components/schemas/BankingDigitalWalletPayee'
          international:
            $ref: '#/components/schemas/BankingInternationalPayee'
        x-conditional:
        - biller
        - digitalWallet
        - domestic
        - international
    ResponseBankingPayeeByIdV2:
      required:
      - data
      - links
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BankingPayeeDetailV2'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    BankingDomesticPayeePayId:
      required:
      - identifier
      - type
      type: object
      properties:
        name:
          type: string
          description: The name assigned to the PayID by the owner of the PayID.
        identifier:
          type: string
          description: The identifier of the PayID (dependent on type).
        type:
          type: string
          description: The type of the PayID.
          enum:
          - ABN
          - EMAIL
          - ORG_IDENTIFIER
          - TELEPHONE
    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
    ErrorV2:
      type: object
      required:
      - code
      - title
      - detail
      x-conditional:
      - meta
      properties:
        code:
          type: string
          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.
        title:
          type: string
          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.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        meta:
          type: object
          x-conditional:
          - urn
          description: Additional data for customised error codes.
          properties:
            urn:
              type: string
              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.
    ResponseBankingPayeeListV2:
      required:
      - data
      - links
      - meta
      type: object
      properties:
        data:
          required:
          - payees
          type: object
          properties:
            payees:
              type: array
              description: The list of payees returned.
              items:
                $ref: '#/components/schemas/BankingPayeeV2'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
    BankingDomesticPayeeAccount:
      required:
      - accountNumber
      - bsb
      type: object
      properties:
        accountName:
          type: string
          description: Name of the account to pay to.
        bsb:
          type: string
          description: BSB of the account to pay to.
        accountNumber:
          type: string
          description: Number of the account to pay to.
    BankingDomesticPayee:
      required:
      - payeeAccountUType
      type: object
      properties:
        payeeAccountUType:
          type: string
          description: 'Type of account object included. Valid values are: <ul><li>`account` A standard Australian account defined by BSB/Account Number.<li>`card` A credit or charge card to pay to (note that PANs are masked).<li>`payId` A PayID recognised by NPP.</ul>'
          enum:
          - account
          - card
          - payId
        account:
          $ref: '#/components/schemas/BankingDomesticPayeeAccount'
        card:
          $ref: '#/components/schemas/BankingDomesticPayeeCard'
        payId:
          $ref: '#/components/schemas/BankingDomesticPayeePayId'
      x-conditional:
      - account
      - card
      - payId
    BankingBillerPayee:
      required:
      - billerCode
      - billerName
      type: object
      properties:
        billerCode:
          type: string
          description: BPAY Biller Code of the Biller.
        crn:
          type: string
          description: BPAY CRN of the Biller (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.
        billerName:
          type: string
          description: Name of the Biller.
      x-conditional:
      - crn
    BankingDigitalWalletPayee:
      required:
      - identifier
      - name
      - provider
      - type
      type: object
      properties:
        name:
          type: string
          description: The display name of the wallet as given by the customer, else a default value defined by the data holder.
        identifier:
          type: string
          description: The identifier of the digital wallet (dependent on type).
        type:
          type: string
          description: The type of the digital wallet identifier.
          enum:
          - EMAIL
          - CONTACT_NAME
          - TELEPHONE
        provider:
          type: string
          description: The provider of the digital wallet.
          enum:
          - PAYPAL_AU
          - OTHER
    MetaPaginated:
      required:
      - totalPages
      - totalRecords
      type: object
      properties:
        totalRecords:
          type: integer
          description: The total number of records in the full set. See [pagination](#pagination).
          x-cds-type: NaturalNumber
        totalPages:
          type: integer
          description: The total number of pages in the full set. See [pagination](#pagination).
          x-cds-type: NaturalNumber
    BankingPayeeId:
      type: string
      description: A unique identifier for a Banking payee, generated according to [CDR ID Permanence](#id-permanence) requirements.
      x-cds-type: ASCIIString
    ResponseErrorListV2:
      type: object
      required:
      - errors
      properties:
        errors:
          description: List of errors.
          type: array
          items:
            $ref: '#/components/schemas/ErrorV2'
    BankingInternationalPayee:
      required:
      - bankDetails
      - beneficiaryDetails
      type: object
      properties:
        beneficiaryDetails:
          required:
          - country
          type: object
          properties:
            name:
              type: string
              description: Name of the beneficiary.
            country:
              type: string
              description: Country where the beneficiary resides. A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code.
              x-cds-type: ExternalRef
            message:
              type: string
              description: Response message for the payment.
        bankDetails:
          required:
          - accountNumber
          - country
          type: object
          properties:
            country:
              type: string
              description: Country of the recipient institution. A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code.
              x-cds-type: ExternalRef
            accountNumber:
              type: string
              description: Account Targeted for payment.
            bankAddress:
              required:
              - address
              - name
              type: object
              properties:
                name:
                  type: string
                  description: Name of the recipient Bank.
                address:
                  type: string
                  description: Address of the recipient Bank.
            beneficiaryBankBIC:
              type: string
              description: Swift bank code. Aligns with standard [ISO 9362](https://www.iso.org/standard/60390.html).
              x-cds-type: ExternalRef
            fedWireNumber:
              type: string
              description: Number for Fedwire payment (Federal Reserve Wire Network).
            sortCode:
              type: string
              description: Sort code used for account identification in some jurisdictions.
            chipNumber:
              type: string
              description: Number for the Clearing House Interbank Payments System.
            routingNumber:
              type: string
              description: International bank routing number.
            legalEntityIdentifier:
              type: string
              description: The legal entity identifier (LEI) for the beneficiary. Aligns with [ISO 17442](https://www.iso.org/standard/59771.html).
              x-cds-type: ExternalRef
    BankingDomesticPayeeCard:
      required:
      - cardNumber
      type: object
      properties:
        cardNumber:
          type: string
          description: Name of the account to pay to.
          x-cds-type: MaskedPANString
  headers:
    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.
      required: true
      schema:
        type: string
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      required: true
      schema:
        type: string