...
S. No. | Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Idempotency Key | Parameter | Request Object | Response Object |
2.1 | beneficiaries | GET | GET /accounts/{AccountId}/beneficiaries | Conditional | accounts | Authorisation Code | No |
|
| OBReadBeneficiary |
2.2 | beneficiaries | GET | GET /beneficiaries | ConditionalOptional | accounts | Authorisation Code | No | Pagination |
| OBReadBeneficiary |
...
An AISP may retrieve the account beneficiaries beneficiaries’ information resource for a specific AccountId (which is retrieved in the call to GET /accounts).
...
If a user/customer selects multiple accounts for authorisation, then their beneficiaries apply consistently to all selected accounts (i.e., in the bulk endpoint /beneficiaries).
This is the expected behaviour of the beneficiaries' endpoints, in the case an ASPSP manages beneficiaries at a user/customer level:
The bulk endpoint /beneficiaries will return the unique list of beneficiaries against the user/customer. In this case, the AccountId in the OBReadBeneficiary payload would be set to NULL / empty (even if the user/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 user/customer. In this case, the AccountId will be populated in the payload.
3.1.2 UML Diagram
...
3.1.3 Notes
The CreditorAccount is used consistently throughout the Account Information APIs to identify an account
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)
The beneficiaries may be Trusted Beneficiaries as well as other types of beneficiaries as indicated by the BeneficiaryType property. When the BeneficiaryType property is not specified, the consumer should refer to the ASPSP’s developer portal
Due to internationalisation requirements:
o The CreditorAgent object may be used to represent either (1) the BIC (with BH.OBF.BICFI in the SchemeName field and the BIC in the Identification field), or (2) the NCC (with BH.OBF.NCC in the SchemeName field and the NCC in the Identification field), or (3) the Name and Address details for the financial institution
o The CreditorAccount/Identification field may be used to represent a non-bahrain specific branch and account numbering scheme
3.1.4 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:
o OBReadBeneficiary/Data/Beneficiary/CreditorAgent
o OBReadBeneficiary/Data/Beneficiary/CreditorAccount
If the ReadBeneficiariesDetail is granted by the user/customer:
o OBReadBeneficiary/Data/Beneficiary/CreditorAgent may be returned if applicable to the account and ASPSP (0..1)
o OBReadBeneficiary/Data/Beneficiary/CreditorAccount must be returned (1..1)
If the ReadPAN permission is granted by the user/customer, the ASPSP may choose to populate the OBReadBeneficiary/Data/Beneficiary/CreditorAccount/Identification with the unmasked PAN (if the PAN is being populated in the response).
...