Beneficiaries - v3.1.3

1. Overview
2. Endpoints
   1. GET/accounts/{AccountId}/beneficiaries
   2. GET /beneficiaries
3. Data Model
   1. Resource Definition
   2. UML Diagram
   3. Notes
   4. Permission Codes
   5. Data Dictionary
4. Usage Examples
   1. Specific Account
      1. Get Account Beneficiaries Request
   2. Bulk
      1. Get Beneficiaries Request
      2. Get Beneficiaries Response

Overview

The beneficiaries resource is used by an AISP to retrieve the account beneficiaries information for a specific AccountId or to retrieve the beneficiaries’ information in bulk for account(s) that the PSU has authorised to access.

This resource description should be read in conjunction with a compatible Account Information Services API Profile.

Endpoints

Endpoints for the resource and available methods.

GET /accounts/{AccountId}/beneficiaries

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 OBReadBeneficiary4 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 OBReadBeneficiary4 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 UK.OBIE.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 be used to represent a non-UK specific branch and account numbering scheme with “UK.OBIE.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 the resource. In the event that 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:
  • OBReadBeneficiary4/Data/Beneficiary/CreditorAgent
  • OBReadBeneficiary4/Data/Beneficiary/CreditorAccount
• If the ReadBeneficiariesDetail is granted by the PSU:
  • OBReadBeneficiary4/Data/Beneficiary/CreditorAgent may be returned if applicable to the account and ASPSP (0..1)
  • OBReadBeneficiary4/Data/Beneficiary/CreditorAccount must be returned (1..1)

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

Data Dictionary

Usage Examples

Specific Account

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 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

#### 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": "Towbar Club",
        "CreditorAccount": {
          "SchemeName": "UK.OBIE.SortCodeAccountNumber",
          "Identification": "80200112345678",
          "Name": "Mrs Juniper"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v3.1/aisp/accounts/22289/beneficiaries/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Bulk

Get Beneficiaries Request

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

Get 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": "Towbar Club",
        "CreditorAccount": {
          "SchemeName": "UK.OBIE.SortCodeAccountNumber",
          "Identification": "80200112345678",
          "Name": "Mrs Juniper"
        }
      },
      {
        "AccountId": "31820",
        "BeneficiaryId": "Ben37",
        "Reference": "Golf Club",
        "CreditorAccount": {
          "SchemeName": "UK.OBIE.SortCodeAccountNumber",
          "Identification": "87562298675421",
          "Name": "Mr Large"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v3.1/aisp/beneficiaries/"
  },
  "Meta": {
    "TotalPages": 1
  }
}