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

GET /beneficiaries

If an ASPSP has implemented the bulk retrieval endpoints for beneficiaries - an AISP 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 OBReadBeneficiary1 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 ASPSP manages beneficiaries at a customer level (logged in user), instead of account level:

• If a PSU selects multiple accounts for authorisation - then their beneficiaries apply consistently to all selected accounts (i.e., in the bulk endpoint /beneficiaries)
• If a different PSU 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 ASPSP manages beneficiaries at a customer level:

• The bulk endpoint /beneficiaries will return the unique list of beneficiaries against the PSU. In this case - the AccountId in the OBReadBeneficiary1 payload would be set to NULL / empty (even if the PSU 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 PSU. 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
• Due to internationalisation requirements:
  • 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 be used to represent a non-UK specific branch and account numbering scheme with "SortCodeAccountNumber" being populated in the CreditorAccount/SchemeName
• 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 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 PSU:
  • OBReadBeneficiary2/Data/Beneficiary/CreditorAgent may be returned if applicable to the account and ASPSP (0..1)
  • OBReadBeneficiary2/Data/Beneficiary/CreditorAccount must be returned (1..1)

If the ReadPAN permission is granted by the PSU - the ASPSP may choose to populate the OBReadBeneficiary2/Data/Beneficiary/CreditorAccount/Identification with the unmasked PAN (if the PAN is being populated in the response).

Data Dictionary

Usage Examples