OpenAPI Specification
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:
ResponseBankingPayeeListV2_data:
properties:
payees:
description: The list of payees returned.
items:
$ref: '#/components/schemas/BankingPayeeV2'
type: array
required:
- payees
type: object
BankingDomesticPayee:
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
BankingInternationalPayee_beneficiaryDetails:
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
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
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
Meta:
type: object
BankingBillerPayee:
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
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
BankingPayeeDetailV2:
allOf:
- $ref: '#/components/schemas/BankingPayeeV2'
- $ref: '#/components/schemas/BankingPayeeDetailV2_allOf'
BankingPayeeId:
description: A unique identifier for a Banking payee, generated according to [CDR ID Permanence](#id-permanence) requirements.
type: string
x-cds-type: ASCIIString
BankingInternationalPayee:
properties:
beneficiaryDetails:
$ref: '#/components/schemas/BankingInternationalPayee_beneficiaryDetails'
bankDetails:
$ref: '#/components/schemas/BankingInternationalPayee_bankDetails'
required:
- bankDetails
- beneficiaryDetails
type: object
BankingInternationalPayee_bankDetails_bankAddress:
properties:
name:
description: Name of the recipient Bank.
type: string
address:
description: Address of the recipient Bank.
type: string
required:
- address
- name
type: object
ResponseErrorListV2:
properties:
errors:
description: List of errors.
items:
$ref: '#/components/schemas/ErrorV2'
type: array
required:
- errors
type: object
BankingDigitalWalletPayee:
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
BankingDomesticPayeeAccount:
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:
properties:
data:
$ref: '#/components/schemas/ResponseBankingPayeeListV2_data'
links:
$ref: '#/components/schemas/LinksPaginated'
meta:
$ref: '#/components/schemas/MetaPaginated'
required:
- data
- links
- meta
type: object
BankingInternationalPayee_bankDetails:
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
BankingDomesticPayeeCard:
properties:
cardNumber:
description: Name of the account to pay to.
type: string
x-cds-type: MaskedPANString
required:
- cardNumber
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
BankingPayeeV2:
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
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
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
BankingDomesticPayeePayId:
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
ResponseBankingPayeeByIdV2:
properties:
data:
$ref: '#/components/schemas/BankingPayeeDetailV2'
links:
$ref: '#/components/schemas/Links'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- links
type: object
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