Contents

Resource

beneficiaries

Endpoints

GET /accounts/{AccountId}/beneficiaries

GET /beneficiaries

Mandatory?

Optional

Optional

05

Version Control

Endpoints

Endpoints for the resource - and available methods.

GET /accounts/{AccountId}/beneficiaries

A Third Party may retrieve the account beneficiaries information resource for a specific AccountId (which is retrieved in the call to GET /accounts).

GET /beneficiaries

If an API Provider has implemented the bulk retrieval endpoints for beneficiaries - a Third Party may optionally retrieve the beneficiaries information in bulk.

This endpoint will retrieve the beneficiaries resources for all authorised accounts linked to a specific account-request.

Data Model

The OBReadBeneficiary2 object will be used for the call to: 

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

Resource 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

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 instiution
• 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 PISP use case).

Permission Codes

The resource 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

Enumerations

This section gives the definitions for enumerations used.

Usage Examples

Specific Account

Bulk