BankSA Banking Payees 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 Payees API
  version: 1.36.0
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- description: Banking Payee endpoints
  name: Banking Payees
  x-shortName: Payees
paths:
  /banking/payees:
    get:
      description: 'Obtain a list of pre-registered payees.


        Obsolete versions: [v1](includes/obsolete/get-payees-v1.html).'
      operationId: listBankingPayees
      parameters:
      - 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`.
        explode: true
        in: query
        name: type
        required: false
        schema:
          default: ALL
          enum:
          - ALL
          - BILLER
          - DIGITAL_WALLET
          - DOMESTIC
          - INTERNATIONAL
          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/ResponseBankingPayeeListV2'
          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></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 Payees
      tags:
      - Banking Payees
      x-scopes:
      - bank:payees:read
      x-version: '2'
  /banking/payees/{payeeId}:
    get:
      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:
      - description: The _payeeId_ to obtain data for. _payeeId_ values are returned by payee list endpoints.
        explode: false
        in: path
        name: payeeId
        required: true
        schema:
          $ref: '#/components/schemas/BankingPayeeId'
        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/ResponseBankingPayeeByIdV2'
          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></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 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'
        '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 Payee Detail
      tags:
      - Banking Payees
      x-scopes:
      - bank:payees:read
      x-version: '2'
components:
  schemas:
    BankingInternationalPayee:
      example:
        bankDetails:
          country: country
          routingNumber: routingNumber
          fedWireNumber: fedWireNumber
          chipNumber: chipNumber
          legalEntityIdentifier: legalEntityIdentifier
          accountNumber: accountNumber
          bankAddress:
            address: address
            name: name
          sortCode: sortCode
          beneficiaryBankBIC: beneficiaryBankBIC
        beneficiaryDetails:
          country: country
          name: name
          message: message
      properties:
        beneficiaryDetails:
          $ref: '#/components/schemas/BankingInternationalPayee_beneficiaryDetails'
        bankDetails:
          $ref: '#/components/schemas/BankingInternationalPayee_bankDetails'
      required:
      - bankDetails
      - beneficiaryDetails
      type: object
    ResponseBankingPayeeListV2:
      example:
        data:
          payees:
          - nickname: nickname
            description: description
            payeeId: ''
            type: BILLER
            creationDate: creationDate
          - nickname: nickname
            description: description
            payeeId: ''
            type: BILLER
            creationDate: creationDate
        meta:
          totalRecords: 0
          totalPages: 6
        links:
          next: next
          last: last
          prev: prev
          self: self
          first: first
      properties:
        data:
          $ref: '#/components/schemas/ResponseBankingPayeeListV2_data'
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
      required:
      - data
      - links
      - meta
      type: object
    BankingDomesticPayeeCard:
      example:
        cardNumber: cardNumber
      properties:
        cardNumber:
          description: Name of the account to pay to.
          type: string
          x-cds-type: MaskedPANString
      required:
      - cardNumber
      type: object
    BankingInternationalPayee_bankDetails:
      example:
        country: country
        routingNumber: routingNumber
        fedWireNumber: fedWireNumber
        chipNumber: chipNumber
        legalEntityIdentifier: legalEntityIdentifier
        accountNumber: accountNumber
        bankAddress:
          address: address
          name: name
        sortCode: sortCode
        beneficiaryBankBIC: beneficiaryBankBIC
      properties:
        country:
          description: Country of the recipient institution. A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code.
          type: string
          x-cds-type: ExternalRef
        accountNumber:
          description: Account Targeted for payment.
          type: string
        bankAddress:
          $ref: '#/components/schemas/BankingInternationalPayee_bankDetails_bankAddress'
        beneficiaryBankBIC:
          description: Swift bank code. Aligns with standard [ISO 9362](https://www.iso.org/standard/60390.html).
          type: string
          x-cds-type: ExternalRef
        fedWireNumber:
          description: Number for Fedwire payment (Federal Reserve Wire Network).
          type: string
        sortCode:
          description: Sort code used for account identification in some jurisdictions.
          type: string
        chipNumber:
          description: Number for the Clearing House Interbank Payments System.
          type: string
        routingNumber:
          description: International bank routing number.
          type: string
        legalEntityIdentifier:
          description: The legal entity identifier (LEI) for the beneficiary. Aligns with [ISO 17442](https://www.iso.org/standard/59771.html).
          type: string
          x-cds-type: ExternalRef
      required:
      - accountNumber
      - country
      type: object
    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
    LinksPaginated:
      example:
        next: next
        last: last
        prev: prev
        self: self
        first: first
      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
    BankingPayeeDetailV2:
      allOf:
      - $ref: '#/components/schemas/BankingPayeeV2'
      - $ref: '#/components/schemas/BankingPayeeDetailV2_allOf'
    ResponseBankingPayeeByIdV2:
      example:
        meta: '{}'
        links:
          self: self
      properties:
        data:
          $ref: '#/components/schemas/BankingPayeeDetailV2'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          type: object
      required:
      - data
      - links
      type: object
    BankingDomesticPayee:
      example:
        payeeAccountUType: account
        payId:
          identifier: identifier
          name: name
          type: ABN
        account:
          bsb: bsb
          accountName: accountName
          accountNumber: accountNumber
        card:
          cardNumber: cardNumber
      properties:
        payeeAccountUType:
          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
          type: string
        account:
          $ref: '#/components/schemas/BankingDomesticPayeeAccount'
        card:
          $ref: '#/components/schemas/BankingDomesticPayeeCard'
        payId:
          $ref: '#/components/schemas/BankingDomesticPayeePayId'
      required:
      - payeeAccountUType
      type: object
      x-conditional:
      - account
      - card
      - payId
    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
    BankingDomesticPayeePayId:
      example:
        identifier: identifier
        name: name
        type: ABN
      properties:
        name:
          description: The name assigned to the PayID by the owner of the PayID.
          type: string
        identifier:
          description: The identifier of the PayID (dependent on type).
          type: string
        type:
          description: The type of the PayID.
          enum:
          - ABN
          - EMAIL
          - ORG_IDENTIFIER
          - TELEPHONE
          type: string
      required:
      - identifier
      - type
      type: object
    BankingBillerPayee:
      example:
        billerName: billerName
        crn: crn
        billerCode: billerCode
      properties:
        billerCode:
          description: BPAY Biller Code of the Biller.
          type: string
        crn:
          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.
          type: string
        billerName:
          description: Name of the Biller.
          type: string
      required:
      - billerCode
      - billerName
      type: object
      x-conditional:
      - crn
    BankingPayeeV2:
      example:
        nickname: nickname
        description: description
        payeeId: ''
        type: BILLER
        creationDate: creationDate
      properties:
        payeeId:
          allOf:
          - $ref: '#/components/schemas/BankingPayeeId'
          description: Unique identifier for the payee.
        nickname:
          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.
          type: string
        description:
          description: A description of the payee provided by the customer.
          type: string
        type:
          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
          type: string
        creationDate:
          description: The date the payee was created by the customer.
          type: string
          x-cds-type: DateString
      required:
      - nickname
      - payeeId
      - type
      type: object
    BankingPayeeId:
      description: A unique identifier for a Banking payee, generated according to [CDR ID Permanence](#id-permanence) requirements.
      type: string
      x-cds-type: ASCIIString
    BankingPayeeDetailV2_allOf:
      properties:
        payeeUType:
          description: Type of object included that describes the payee in detail.
          enum:
          - biller
          - digitalWallet
          - domestic
          - international
          type: string
        biller:
          $ref: '#/components/schemas/BankingBillerPayee'
        domestic:
          $ref: '#/components/schemas/BankingDomesticPayee'
        digitalWallet:
          $ref: '#/components/schemas/BankingDigitalWalletPayee'
        international:
          $ref: '#/components/schemas/BankingInternationalPayee'
      required:
      - payeeUType
      type: object
      x-conditional:
      - biller
      - digitalWallet
      - domestic
      - international
    BankingInternationalPayee_bankDetails_bankAddress:
      example:
        address: address
        name: name
      properties:
        name:
          description: Name of the recipient Bank.
          type: string
        address:
          description: Address of the recipient Bank.
          type: string
      required:
      - address
      - name
      type: object
    MetaPaginated:
      example:
        totalRecords: 0
        totalPages: 6
      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
    BankingDomesticPayeeAccount:
      example:
        bsb: bsb
        accountName: accountName
        accountNumber: accountNumber
      properties:
        accountName:
          description: Name of the account to pay to.
          type: string
        bsb:
          description: BSB of the account to pay to.
          type: string
        accountNumber:
          description: Number of the account to pay to.
          type: string
      required:
      - accountNumber
      - bsb
      type: object
    ResponseBankingPayeeListV2_data:
      example:
        payees:
        - nickname: nickname
          description: description
          payeeId: ''
          type: BILLER
          creationDate: creationDate
        - nickname: nickname
          description: description
          payeeId: ''
          type: BILLER
          creationDate: creationDate
      properties:
        payees:
          description: The list of payees returned.
          items:
            $ref: '#/components/schemas/BankingPayeeV2'
          type: array
      required:
      - payees
      type: object
    BankingDigitalWalletPayee:
      example:
        identifier: identifier
        provider: PAYPAL_AU
        name: name
        type: EMAIL
      properties:
        name:
          description: The display name of the wallet as given by the customer, else a default value defined by the data holder.
          type: string
        identifier:
          description: The identifier of the digital wallet (dependent on type).
          type: string
        type:
          description: The type of the digital wallet identifier.
          enum:
          - EMAIL
          - CONTACT_NAME
          - TELEPHONE
          type: string
        provider:
          description: The provider of the digital wallet.
          enum:
          - PAYPAL_AU
          - OTHER
          type: string
      required:
      - identifier
      - name
      - provider
      - type
      type: object
    Links:
      example:
        self: self
      properties:
        self:
          description: Fully qualified link that generated the current response document.
          type: string
          x-cds-type: URIString
      required:
      - self
      type: object
    BankingInternationalPayee_beneficiaryDetails:
      example:
        country: country
        name: name
        message: message
      properties:
        name:
          description: Name of the beneficiary.
          type: string
        country:
          description: Country where the beneficiary resides. A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code.
          type: string
          x-cds-type: ExternalRef
        message:
          description: Response message for the payment.
          type: string
      required:
      - country
      type: object
    ResponseErrorListV2:
      properties:
        errors:
          description: List of errors.
          items:
            $ref: '#/components/schemas/ErrorV2'
          type: array
      required:
      - errors
      type: object
  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.
      explode: false
      required: true
      schema:
        type: string
      style: simple
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      explode: false
      required: true
      schema:
        type: string
      style: simple