1 Version Control
2 Definition
3 Endpoints
- 3.1 GET /accounts/{AccountId}/beneficiaries
- 3.2 GET /beneficiaries
4 Data Model
- 4.1 UML Diagram
- 4.2 Notes
- 4.3 Permission Codes
- 4.4 Data Dictionary
- 4.5 Enumerations
5 Usage Examples
- 5.1 Specific Account
  - 5.1.1 Request
    - 5.1.1.1 Get Account Beneficiaries Request
  - 5.1.2 Response
    - 5.1.2.1 Get Account Beneficiaries Response
- 5.2 Bulk
  - 5.2.1 Request
    - 5.2.1.1 Get Beneficiaries Request
  - 5.2.2 Response
    - 5.2.2.1 Get Beneficiaries Response

Version Control

Version	Date	Author	Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline specification for Beneficiaries resource

2.1-draft1

Jun 15, 2020

@Gavin Wong (Unlicensed)

Updated:

Added MaskedCardNumber as new SchemeName enumeration for the account identification object in data dictionary as per https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/361955329 and https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/362020869
Definition of MaskedCardNumber
Usage Example version from v2.0 to v2.1

Removed:

ReadPAN permission as per https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/361922594

2.1-rc2

Sep 11, 2020

@Gavin Wong (Unlicensed)

Updated:

Updated Data Dictionary to align AccountId to 1:1 as per

Definition

A resource that contains a set of elements that describes the list of trusted beneficiaries linked to a specific account (AccountId). An account (AccountId) may have no trusted beneficiaries set up, or may have multiple beneficiaries set up.

In the case an API Provider manages beneficiaries at a customer level (logged in user), instead of account level:

If a Customer selects multiple accounts for authorisation - then their beneficiaries apply consistently to all selected accounts (i.e., in the bulk endpoint /beneficiaries)
If a different Customer selects the same accounts - a different set of beneficiaries could be returned

This is the expected behaviour of the beneficiaries endpoints - in the case an API Provider manages beneficiaries at a customer level:

The bulk endpoint /beneficiaries will return the unique list of beneficiaries against the Customer. In this case - the AccountId in the OBReadBeneficiary2 payload would be set to empty (even if the Customer only has one account).
The selected account endpoint /accounts/{AccountId}/beneficiaries will return the beneficiaries that may be accessible to the AccountId - based on the Customer. In this case - the AccountId will be populated in the payload

Endpoints

Resource	Endpoint	Mandatory?	Scope	Grant Type	Idempotency Key	Parameters	Request Object	Response Object

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

beneficiaries

GET /accounts/{AccountId}/beneficiaries

Optional

accounts

Redirect Flow; or

Decoupled Flow

OBReadBeneficiary2

beneficiaries

GET /beneficiaries

Optional

accounts

Redirect Flow; or

Decoupled Flow

Pagination

OBReadBeneficiary2

GET /accounts/{AccountId}/beneficiaries

The API endpoint allows a Third Party to retrieve the account beneficiaries for a specific AccountId (which is retrieved in the call to GET /accounts).

The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).

GET /beneficiaries

The API endpoint allows a Third Party to retrieve the account beneficiaries in bulk, if an API Provider has implemented the bulk retrieval endpoints.

The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).
This will retrieve the account beneficiaries for all accounts linked to the account-access-consent.

Data Model

The OBReadBeneficiary2 object will be used for the call to:

GET /accounts/{AccountId}/beneficiaries
GET /beneficiaries

UML Diagram

Notes

The CreditorAccount is used consistently throughout the Account Information APIs to identify an account
The CreditorAgent object may be used to represent either (1) the BIC (with BICFI in the SchemeName field and the BIC in the Identification field), or (2) the Name and Address details for the financial institution
The CreditorAccount/Identification field may only be used to represent NZ account numbers with a CreditorAccount/SchemeName of "BECSElectronicCredit"
For the /accounts/{AccountId}/beneficiaries endpoint - the CreditorAccount and CreditorAgent blocks represent the account of the beneficiary that is receiving funds (so has been named the CreditorAccount - for consistency with the Third Party use case).

Permission Codes

The resource response differs depending on the permissions (ReadBeneficiariesBasic and ReadBeneficiariesDetail) used to access the resource. In the event the resource is accessed with both ReadBeneficiariesBasic and ReadBeneficiariesDetail, the most detailed level (ReadBeneficiariesDetail) must be used.

These objects must not be returned without the ReadBeneficiariesDetail permission:
- OBReadBeneficiary2/Data/Beneficiary/CreditorAgent
- OBReadBeneficiary2/Data/Beneficiary/CreditorAccount
If the ReadBeneficiariesDetail is granted by the Customer:
- OBReadBeneficiary2/Data/Beneficiary/CreditorAgent may be returned if applicable to the account and API Provider (0..1)
- OBReadBeneficiary2/Data/Beneficiary/CreditorAccount must be returned (1..1)

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBReadBeneficiary2		OBReadBeneficiary2		OBReadBeneficiary2
Data	1..1	OBReadBeneficiary2/Data		OBReadDataBeneficiary2
Beneficiary	0..n	OBReadBeneficiary2/Data/Beneficiary		OBBeneficiary2
AccountId	1..1	OBReadBeneficiary2/Data/Beneficiary/AccountId	A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.	Max40Text
BeneficiaryId	0..1	OBReadBeneficiary2/Data/Beneficiary/BeneficiaryId	A unique and immutable identifier used to identify the beneficiary resource. This identifier has no meaning to the account owner.	Max40Text
Reference	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference	Remittance information for use with BECSElectronicCredit payment scheme.	NZBECSRemittance1
CreditorName	1..1	OBReadBeneficiary2/Data/Beneficiary/Reference/CreditorName	The Creditor's Name.	Max20Text
DebtorName	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/DebtorName	The Debtor's Name.	Max20Text
CreditorReference	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/CreditorReference	Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZBECSReference1
Particulars	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/CreditorReference/Particulars	Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.	Max12Text
Code	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/CreditorReference/Code	Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.	Max12Text
Reference	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/CreditorReference/Reference	Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.	Max12Text
DebtorReference	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/DebtorReference	Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZBECSReference1
Particulars	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/DebtorReference/Particulars	Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.	Max12Text
Code	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/DebtorReference/Code	Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.	Max12Text
Reference	0..1	OBReadBeneficiary2/Data/Beneficiary/Reference/DebtorReference/Reference	Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.	Max12Text
CreditorAgent	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent	Party that manages the account on behalf of the account owner, that is manages the registration and booking of entries on the account, calculates balances on the account and provides information about the account. This is the servicer of the beneficiary account.	OBBranchAndFinancialInstitutionIdentification3
SchemeName	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalFinancialInstitutionIdentification2Code	BICFI
Identification	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/Identification	Unique and unambiguous identification of the servicing institution.	Max35Text
Name	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/Name	Name by which an agent is known and which is usually used to identify that agent.	Max140Text
PostalAddress	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress	Information that locates and identifies a specific address, as defined by postal services.	OBPostalAddress8
AddressType	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/AddressType	Identifies the nature of the postal address.	OBAddressTypeCode	Business Correspondence DeliveryTo MailTo POBox Postal Residential Statement
AddressLine	0..5	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/AddressLine	Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text.	Max70Text
StreetName	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/StreetName	Name of a street or thoroughfare.	Max70Text
BuildingNumber	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/BuildingNumber	Number that identifies the position of a building on a street.	Max16Text
PostCode	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/PostCode	Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.	Max16Text
TownName	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/TownName	Name of a built-up area, with defined boundaries, and a local government.	Max35Text
CountrySubDivision	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/CountrySubDivision	Identifies a subdivision of a country eg, state, region, county.	Max35Text
Country	1..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAgent/PostalAddress/Country	Nation with its own government, occupying a particular territory.	CountryCode	^[A-Z]{2,2}$
CreditorAccount	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAccount	Provides the details to identify the beneficiary account.	OBCashAccount1
SchemeName	1..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAccount/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification3Code	BECSElectronicCredit MaskedCardNumber
Identification	1..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAccount/Identification	Identification assigned by an institution to identify an account. This identification is known by the account owner.	Max34Text
Name	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAccount/Name	Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.	Max70Text
SecondaryIdentification	0..1	OBReadBeneficiary2/Data/Beneficiary/CreditorAccount/SecondaryIdentification	This is secondary identification of the account, as assigned by the account servicing institution.	Max34Text

Enumerations

This section gives the definitions for enumerations used.

Code Class	Name	Definition

Code Class	Name	Definition
OBExternalAccountIdentification3Code	BECSElectronicCredit	An identifier used to uniquely identify the account of a customer at a financial institution, structured in the form of 12-1234-1234567-12 where: the first two digits are the bank number, which tells us which bank the account resides with; the next four digits indicate the branch number, which tells us which branch of that bank the account is domiciled; the next seven digits indicate the account number; and the last two digits indicate the account number suffix.
OBExternalAccountIdentification3Code	MaskedCardNumber	Masked credit card number. This masked credit card number is the card identification number exactly as it is presented to the Customer in the API Provider’s online portal.
OBExternalFinancialInstitutionIdentification2Code	BICFI	Valid BICs for financial institutions are registered by the ISO 9362 Registration Authority in the BIC directory, and consist of eight (8) or eleven (11) contiguous characters.
OBAddressTypeCode	Business	Address is the business address.
OBAddressTypeCode	Correspondence	Address is the address where correspondence is sent.
OBAddressTypeCode	DeliveryTo	Address is the address to which delivery is to take place.
OBAddressTypeCode	MailTo	Address is the address to which mail is sent.
OBAddressTypeCode	POBox	Address is a postal office (PO) box.
OBAddressTypeCode	Postal	Address is the complete postal address.
OBAddressTypeCode	Residential	Address is the home address.
OBAddressTypeCode	Statement	Address is the address where statements are sent.

Usage Examples

Specific Account

Retrieving beneficiaries for a specific account.

Request

Get Account Beneficiaries Request

GET /accounts/22289/beneficiaries HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

Get Account Beneficiaries Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Beneficiary": [
      {
        "AccountId": "22289",
        "BeneficiaryId": "Ben1",
        "Reference": {
          "CreditorName": "Towbar",
          "CreditorReference": {
            "Particulars": "CreditorPart",
            "Code": "CreditorCode",
            "Reference": "CreditorRef"
          },
          "DebtorName": "The Debtor",
          "DebtorReference": {
            "Particulars": "DebtorPart",
            "Code": "DebtorCode",
            "Reference": "DebtorRef"
          }
        },
        "CreditorAccount": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "01-1234-1234567-00",
          "Name": "Mrs Juniper"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking-nz/v2.1/accounts/22289/beneficiaries"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Bulk

Retrieving beneficiaries for all accounts linked to the account-access-consent.

Request

Get Beneficiaries Request

GET /beneficiaries HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Payments NZ API standards

Beneficiaries v2.1.0

Version Control

Definition

Endpoints

GET /accounts/{AccountId}/beneficiaries

GET /beneficiaries

Data Model

UML Diagram

Notes

Permission Codes

Data Dictionary

Enumerations

Usage Examples

Specific Account

Request

Get Account Beneficiaries Request

Response

Get Account Beneficiaries Response

Bulk

Request

Get Beneficiaries Request

Response

Get Beneficiaries Response