Skip to end of banner
Go to start of banner

Accounts 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

Version 1 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

The resource that represents the account to which credit and debit entries are made. Each account will have a unique and immutable AccountId.

Endpoints

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

accounts

GET /accounts

Mandatory

accounts

Redirect Flow; or

Decoupled Flow


Pagination


OBReadAccount2

accounts

GET /accounts/{AccountId}

Mandatory

accounts

Redirect Flow; or

Decoupled Flow




OBReadAccount3

GET /accounts

A common action for a Third Party after an account-access-consent is authorised - is to call the GET /accounts endpoint to identify the accounts linked to the account-access-consent.

The API endpoint allows a Third Party to retrieve, from an API Provider, the full list of accounts (the AccountId(s)) that a Customer has authorised the Third Party to access.

  • The Third Party does this with the GET /accounts action.

  • The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 

  • The AccountId(s) returned from the API call can then be used to retrieve other resources for an account.

  • The Customer is only able to select which of their accounts are linked to the account-access-consent at the API Provider's interface. 

GET /accounts/{AccountId}

The API endpoint allows a Third Party to retrieve, from an API Provider, a specific account (AccountId) that a Customer has authorised the Third Party to access.

  • The Third Party does this with the GET /accounts/{AccountId} action.

  • The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 

Data Model

The OBReadAccount2 object will be used for the call to:

  • GET /accounts

The OBReadAccount3 object will be used for the call to:

  • GET /accounts/{AccountId}

Both OBReadAccount2 and OBReadAccount3 use the OBAccount2 class. However, the OBReadAccount3 has a single OBAccount2 object within the Data object; whereas the OBReadAccount2 object allows for an array of OBAccount2 objects.

UML Diagram

OBAccount2

OBReadAccount2

OBReadAccount3

Notes

  • The Account and Servicer blocks replicate what is used consistently throughout the Account Information APIs.

  • This structure has been designed to:

    • Reflect the DebtorAccount and DebtorAgent (and similarly for CreditorAccount and CreditorAgent) structures in the Third Party use case.

    • Having a SchemeName for the Account and Servicer blocks means we can be flexible to accommodate multiple types of accounts in the future.

  • In the Account identification section:

    • Where BECSElectronicCredit is specified as the SchemeName, the Servicer section must not be populated and the Identification field must be populated with a structured bank account number 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.

    • Where MaskedCardNumber is specified as the SchemeName, the Identification field must be populated with a 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. API Providers must ensure that any card related information returned through the API is compliant with PCI DSS requirements. API Providers must publish, on their developer portal, information on the format of their masked credit card number.

  • The SecondaryIdentification element can be used for the roll number for building societies

Permission Codes

The resource response differs depending on the permissions (ReadAccountsBasic and ReadAccountsDetail) used to access the resource. In the event the resource is accessed with both ReadAccountsBasic and ReadAccountsDetail, the most detailed level (ReadAccountsDetail) must be used.

  • These objects must not be returned without the ReadAccountsDetail permission:

    • OBAccount2/Account

    • OBAccount2/Servicer

  • If the ReadAccountsDetail is granted by the Customer:

    • OBAccount2/Account must be returned (1..1)

    • OBAccount2/Servicer may be returned if applicable to the account and API Provider (0..1)

Data Dictionary

OBAccount2

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

OBAccount2


OBAccount2

Provides the details to identify an account.

OBAccount2



AccountId

1..1

OBAccount2/AccountId

A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.

Max40Text



Currency

1..1

OBAccount2/Currency

Identification of the currency in which the account is held.

Usage: Currency should only be used in case one and the same account number covers several currencies
and the initiating party needs to identify which currency needs to be used for settlement on the account.

ActiveOrHistoricCurrencyCode

[A-Z]{3,3}


AccountType

0..1

OBAccount2/AccountType

Specifies the type of account (personal or business).

OBExternalAccountType1Code

Business
Personal


AccountSubType

0..1

OBAccount2/AccountSubType

Specifies the sub type of account (product family group).

OBExternalAccountSubType1Code

ChargeCard
CreditCard
CurrentAccount
EMoney
Loan
Mortgage
PrePaidCard
Savings


Description

0..1

OBAccount2/Description

Specifies the description of the account type.

Max35Text



Nickname

1..1

OBAccount2/Nickname

The nickname of the account, assigned by the account owner in order to provide an additional means of identification of the account.

Max70Text



Account

0..1

OBAccount2/Account

Provides the details to identify an account.

OBCashAccount2



SchemeName

1..1

OBAccount2/Account/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

OBExternalAccountIdentification3Code

BECSElectronicCredit

MaskedCardNumber


Identification

1..1

OBAccount2/Account/Identification

Identification assigned by an institution to identify an account. This identification is known by the account owner.

Max34Text



Name

0..1

OBAccount2/Account/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

OBAccount2/Account/SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution. 

Max34Text



Servicer

0..1

OBAccount2/Servicer

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.

OBBranchAndFinancialInstitutionIdentification2



SchemeName

1..1

OBAccount2/Servicer/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

OBExternalFinancialInstitutionIdentification2Code

BICFI


Identification

1..1

OBAccount2/Servicer/Identification

Unique and unambiguous identification of the servicing institution.

Max35Text



OBReadAccount2

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

OBReadAccount2


OBReadAccount2


OBReadAccount2



Data

1..1

OBReadAccount2/Data


OBReadDataAccount2



Account

0..n

OBReadAccount2/Data/Account

Unambiguous identification of the account to which credit and debit entries are made.

OBAccount2



OBReadAccount3

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

OBReadAccount3


OBReadAccount3


OBReadAccount3



Data

1..1

OBReadAccount3/Data


OBReadDataAccount3



Account

1..1

OBReadAccount3/Data/Account

Unambiguous identification of the account to which credit and debit entries are made.

OBAccount2



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.

OBExternalAccountSubType1Code

ChargeCard

Account sub-type is a Charge Card.

OBExternalAccountSubType1Code

CreditCard

Account sub-type is a Credit Card.

OBExternalAccountSubType1Code

CurrentAccount

Account sub-type is a Current Account.

OBExternalAccountSubType1Code

EMoney

Account sub-type is an EMoney.

OBExternalAccountSubType1Code

Loan

Account sub-type is a Loan.

OBExternalAccountSubType1Code

Mortgage

Account sub-type is a Mortgage.

OBExternalAccountSubType1Code

PrePaidCard

Account sub-type is a PrePaid Card.

OBExternalAccountSubType1Code

Savings

Account sub-type is a Savings.

OBExternalAccountType1Code

Business

Account type is for business.

OBExternalAccountType1Code

Personal

Account type is for personal.

Usage Examples

Accounts - Bulk - Detail Permission

In this scenario, the ReadAccountsDetail permission has been granted.

The call to GET /accounts is the first step after an account-access-consent is authorised. This will allow the Third Party to discover which accounts (and AccountId values) are linked with the authorisation of consent. 

In this scenario, the ReadAccountsDetail permission has been granted.

Request

GET Accounts Request

GET /accounts HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
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 Accounts Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Bills",
        "Account": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "12-1234-1234567-00",
          "Name": "Mr Kevin"
        }
      },
      {
        "AccountId": "31820",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Household",
        "Account": {
          "SchemeName": "BECSElectronicCredit",
          "Identification": "12-1234-1234567-25",
          "Name": "Mr Kevin"
        }
      }
    ]
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v2.1/accounts"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Accounts - Specific Account - Detail Permission

A Third Party can also retrieve the account details specifically for AccountId 22289.

In this scenario, the ReadAccountsDetail permission has been granted.

Request

GET Accounts Request

GET /accounts/22289 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
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 Accounts Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Account": {
      "AccountId": "22289",
      "Currency": "NZD",
      "AccountType": "Personal",
      "AccountSubType": "CurrentAccount",
      "Nickname": "Bills",
      "Account": {
        "SchemeName": "BECSElectronicCredit",
        "Identification": "12-1234-1234567-00",
        "Name": "Mr Kevin"
      }
    }
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v2.1/accounts/22289"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Accounts - Bulk - Basic Permission

In this scenario, the ReadAccountsBasic permission has been granted.

Request

GET Accounts Request

GET /accounts HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
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 Accounts Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Account": [
      {
        "AccountId": "22289",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Bills"
      },
      {
        "AccountId": "31820",
        "Currency": "NZD",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Household"
      }
    ]
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v2.1/accounts"
  },
  "Meta": {
    "TotalPages": 1
  }
}

  • No labels