Beneficiaries v2.1.1
- Matthew Bell
- 1 Version Control
- 2 Definition
- 3 Endpoints
- 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.2 Bulk
- 5.2.1 Request
- 5.2.1.1 Get Beneficiaries Request
- 5.2.2 Response
- 5.2.2.1 Get Beneficiaries Response
- 5.2.1 Request
Version Control
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 |
|---|---|---|---|---|---|---|---|---|
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 |
|---|---|---|---|---|---|
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. | 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 |
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. | 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 |
|---|---|---|
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:
|
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