Skip to end of banner
Go to start of banner

Beneficiaries v2.1.3

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Current »

Version Control

Version

Date

Author

Comments

2.0.0

Payments NZ API Working Group

Baseline

2.1-draft1

 

Gavin Wong (Unlicensed)

Updated:

Removed:

2.1-rc2

Gavin Wong (Unlicensed)

Updated:

  • Scope definition based on Business WG feedback

2.1.1

Nigel Somerfield

Patch update to Swagger specification to BECSRemittance - DebtorReference and CreditorReference - specify additionalProperties: false

2.1.2

Nigel Somerfield

Patch update to Swagger to reflect /wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1455358006, which determined that the standard error response body should be included in all non-success HTTP responses.

2.1.3

Nigel Somerfield

Patch update to clarify the explanation of BookingDateTime:

  • The BookingDateTime is the date the transaction is booked (or posted)
    and becomes immutable - which is not the date the transaction took place

was replaced with:

  • The BookingDateTime is the date the transaction is booked (or posted)
    and becomes immutable - which is not necessarily the date the transaction
    took place

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.
This is the servicer of the beneficiary 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
Correspondence
DeliveryTo
MailTo
POBox
Postal
Residential
Statement

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.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.

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:

  • the first two digits are the bank number, which tells us which bank the account resides with;

  • the next four digits indicate the branch number, which tells us which branch of that bank the account is domiciled;

  • the next seven digits indicate the account number; and

  • the last two digits indicate the account number suffix.

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


Response

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": {
          "CreditorName": "Towbar",
          "CreditorReference": {
            "Particulars": "CreditorPart",
            "Code": "CreditorCode",
            "Reference": "CreditorRef"
          },
          "DebtorName": "The Debtor",
          "DebtorReference": {
            "Particulars": "DebtorPart",
            "Code": "DebtorCode",
            "Reference": "DebtorRef"
          }
        },
        "CreditorAccount": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "12-0234-0013231-00",
          "Name": "Mrs Juniper"
        }
      },
      {
        "AccountId": "31820",
        "BeneficiaryId": "Ben37",
        "Reference": {
          "CreditorName": "Golf",
          "CreditorReference": {
            "Particulars": "CreditorPart",
            "Code": "CreditorCode",
            "Reference": "CreditorRef"
          },
          "DebtorName": "The Debtor",
          "DebtorReference": {
            "Particulars": "DebtorPart",
            "Code": "DebtorCode",
            "Reference": "DebtorRef"
          }
        },
        "CreditorAccount": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "02-0500-0204051-00",
          "Name": "Mr Large"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking-nz/v2.1/beneficiaries"
  },
  "Meta": {
    "TotalPages": 1
  }
}


  • No labels