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 Payees API
  version: 1.36.0
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Payees
paths:
  /banking/payees:
    get:
      tags:
      - Payees
      summary: Get Payees
      description: Obtain a list of pre-registered payees
      operationId: listPayees
      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:
          - DOMESTIC
          - INTERNATIONAL
          - BILLER
          - ALL
      - 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: '2'
      - 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/ResponseBankingPayeeList'
        '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:payees:read
      - default:
        - bank:payees:read
      x-version: '1'
      x-auth-type: Application User
      x-throttling-tier: Unlimited
  /banking/payees/{payeeId}:
    get:
      tags:
      - 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'
      operationId: getPayeeDetail
      parameters:
      - name: payeeId
        in: path
        description: The ID used to locate the details of a particular payee
        required: true
        schema:
          type: string
          x-cds-type: ASCIIString
        x-cds-type: ASCIIString
      - 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: '2'
      - 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/ResponseBankingPayeeById'
        '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:payees:read
      - default:
        - bank:payees:read
      x-version: '1'
      x-auth-type: Application User
      x-throttling-tier: Unlimited
components:
  schemas:
    BankingPayee:
      required:
      - nickname
      - payeeId
      - type
      type: object
      properties:
        payeeId:
          type: string
          description: ID of the payee adhering to the rules of ID permanence
          x-cds-type: ASCIIString
        nickname:
          type: string
          description: The short display name of the payee as provided by the customer
        description:
          type: string
          description: A description of the payee provided by the customer
        type:
          type: string
          description: The type of payee. DOMESTIC means a registered payee for domestic payments including NPP. INTERNATIONAL means a registered payee for international payments. BILLER means a registered payee for BPAY
          enum:
          - DOMESTIC
          - INTERNATIONAL
          - BILLER
        creationDate:
          type: string
          description: The date the payee was created by the customer
          x-cds-type: DateString
    ResponseErrorList:
      required:
      - errors
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseErrorList_errors'
    BankingInternationalPayee_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:
          $ref: '#/components/schemas/BankingInternationalPayee_bankDetails_bankAddress'
        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
    BankingInternationalPayee_bankDetails_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
    ResponseBankingPayeeById:
      required:
      - data
      - links
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BankingPayeeDetail'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    BankingDomesticPayeeCard:
      required:
      - cardNumber
      type: object
      properties:
        cardNumber:
          type: string
          description: Name of the account to pay to
          x-cds-type: MaskedPANString
    BankingPayeeDetail:
      allOf:
      - $ref: '#/components/schemas/BankingPayee'
      - required:
        - payeeUType
        type: object
        properties:
          payeeUType:
            type: string
            description: Type of object included that describes the payee in detail
            enum:
            - domestic
            - biller
            - international
          domestic:
            $ref: '#/components/schemas/BankingDomesticPayee'
          biller:
            $ref: '#/components/schemas/BankingBillerPayee'
          international:
            $ref: '#/components/schemas/BankingInternationalPayee'
        x-conditional:
        - domestic
        - biller
        - international
    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
    Meta:
      type: object
    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
    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
    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 the contents of the CRN match the format of a Credit Card PAN then it should be masked using the rules applicable for the MaskedPANString common type
        billerName:
          type: string
          description: Name of the Biller
      x-conditional:
      - crn
    BankingInternationalPayee_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
    ResponseBankingPayeeList_data:
      required:
      - payees
      type: object
      properties:
        payees:
          type: array
          description: The list of payees returned
          items:
            $ref: '#/components/schemas/BankingPayee'
    ResponseBankingPayeeList:
      required:
      - data
      - links
      - meta
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ResponseBankingPayeeList_data'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
    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:
          - EMAIL
          - TELEPHONE
          - ABN
          - ORG_IDENTIFIER
    BankingDomesticPayee:
      required:
      - payeeAccountUType
      type: object
      properties:
        payeeAccountUType:
          type: string
          description: 'Type of account object included. Valid values are: **account** A standard Australian account defined by BSB/Account Number. **card** A credit or charge card to pay to (note that PANs are masked). **payId** A PayID recognised by NPP'
          enum:
          - account
          - card
          - payId
        account:
          $ref: '#/components/schemas/BankingDomesticPayeeAccount'
        card:
          $ref: '#/components/schemas/BankingDomesticPayeeCard'
        payId:
          $ref: '#/components/schemas/BankingDomesticPayeePayId'
      x-conditional:
      - account
      - card
      - payId
    BankingInternationalPayee:
      required:
      - bankDetails
      - beneficiaryDetails
      type: object
      properties:
        beneficiaryDetails:
          $ref: '#/components/schemas/BankingInternationalPayee_beneficiaryDetails'
        bankDetails:
          $ref: '#/components/schemas/BankingInternationalPayee_bankDetails'
    Links:
      required:
      - self
      type: object
      properties:
        self:
          type: string
          description: Fully qualified link that generated the current response document
          x-cds-type: URIString