Overview of the v2.0 standard

Owned by Matthew Bell
Last updated: Nov 17, 2020 by Katie Wilson (Unlicensed)
4 min read

Contents

 

Purpose

This scope summary provides a high level overview and non-technical description of the v2.0 Account Information and Payment Initiation API specifications.

Description of the v2.0 standard

The v2.0 API standard is comprised of two main API specifications:

  • The Payments Initiation API: This enables a customer to make payment(s) via a Third Party connecting directly and safely to the customer’s bank (API Provider).

  • Account Information API: This enables a customer to grant a Third Party access to the customer’s account information held with the customer’s bank (API Provider).

Payments Initiation

The v1.0 Payments Initiation standard redirects the customer from the merchant’s website or app, to their bank (API Provider) for authentication and payment authorisation. The v2.0 standard retains this redirect flow, but also adds a decoupled flow as another option for customer interactions and authentication. The v2.0 Payments Initiation standard also introduces enduring payment consent, which provides a long-lived authority for payment(s) to be initiated from a customer’s account, with the customer's consent. Other improvements to the v2.0 Payments Initiation standard have also be made.

Enduring payment consent

The v2.0 API standard introduces enduring payment consent, which forms a part of the Payments Initiation specification. Enduring payment consent opens up use cases where the customer does not need to be present for a payment to be initiated.

  • The Third Party agrees the terms or attributes of the enduring payment consent with the Customer. The enduring payment content attributes set the parameters for when a one-off payment may be made. These include, for example: maximum transaction value; maximum payments frequency per time period; duration of the consent; etc.

  • The Third Party uses one of the authentication models, either redirect or decoupled, to authenticate the customer with the API Provider and lodge the consent with with the API Provider (customer’s bank).

  • The Third Party initiates a one-off payment on behalf of the customer when required, as per the agreement between the customer and the Third Party. The API Provider processes the payment as long as it is within the attributes or parameters of that enduring payment consent.

Implications for the enduring payment consent are:

  • Customer will need to be present to authenticate themselves to set up the enduring payment consent.

  • Customer does not need to be present to authenticate future one-off payments.

More information can be read about enduring payment consent here:

Account Information

The functional scope of the v2.0 Account Information specification does not significantly change from the v1.0 specification. The same account resources will be included in v2.0.

The Account Information specification also adds the decoupled flow to customer authentication interactions, and benefits from the general and technical improvements made to the v2.0 API standard.

The resources that the Account Information API supports include:

  • Account access consents: Allows a third party to check on the status of a customer’s account access request with an API Provider.

  • Accounts: Allows a Third Party to retrieve the full list of accounts the customer has authorised the Third Party to access.

  • Balances: Allows a Third Party to retrieve the balance of a specified account(s) the customer has authorised the Third Party to access.

  • Transactions: Allows a Third Party to retrieve a list of transactions posted to an account that results in an increase or decrease to a balance within a defined date range.

  • Beneficiaries: Allows a Third Party to retrieve a list of trusted beneficiaries linked to a specific account.

  • Direct debits: Allows a Third Party to retrieve the list of direct debits that have been set up on a specific account.

  • Offers: Allows the Third Party to retrieve the offers available (product features) on a customer account, for example, interest rates, benefits, cash back, etc.

  • Standing orders (automatic payments): Allows a Third Party to retrieve the list of standing orders (New Zealand terminology is automatic payments) that have been set up on a specific account.

  • Party: Allows a Third Party to retrieve information about the party (customer or owner) linked to a specific account. This can include name, email address, phone, mobile, address, etc.

  • Scheduled payments: Allows a Third Party to see the list of scheduled payments set up against a specific account. A scheduled payment is a single one-off payment that has been scheduled for a future date.

  • Statements: Allows a Third Party to request all statements associated with a specific account within a specified date range.

Authentication flows

The v2.0 standard introduces the decoupled authorisation flow, which provides a more customer and mobile friendly option for the customer to authorise consent (that has already been agreed between a customer and Third Party) with the API Provider. This does not replace the existing redirect model summarised below, but instead adds an additional implementation option.

You can read more about the redirect and decoupled flows below:

Decoupled authentication flow

The v2.0 standard introduces the decoupled authentication flow, which provides a better experience and more mobile friendly option for how customers can interact with the Third Party and API Provider. The redirect authentication flow model features in both the v1.0 and v2.0 API standard.

The decoupled flow separates the API Provider’s and third party’s respective interactions with a customer, making it possible for the API Provider to send the customer authorisation request notifications. It also makes it possible for the customer to interact with the third party and their bank (API Provider) on different devices for the same action.

The redirect and decoupled flows can both be used in the Account Information and the Payments Initiation APIs.