1 Version Control
2 Overview
- 2.1 Document Structure
- 2.2 Scope
- 2.3 Out of Scope
3 Basics
- 3.1 Overview
  - 3.1.1 Overview Diagram
  - 3.1.2 Steps
  - 3.1.3 Sequence Diagram
- 3.2 Restrictions
- 3.3 Release Management
  - 3.3.1 Enduring-Payment-Consents
    - 3.3.1.1 POST
    - 3.3.1.2 GET
    - 3.3.1.3 DELETE
  - 3.3.2 Domestic-Payment-Consents
    - 3.3.2.1 POST
    - 3.3.2.2 GET
  - 3.3.3 Domestic-Payments
    - 3.3.3.1 POST
    - 3.3.3.2 GET
4 Endpoints
- 4.1 Payment Resources
5 Security & Access Control
- 5.1 Scopes
- 5.2 Grants Types
- 5.3 Consent Authorisation
- 5.4 Consent Re-authorisation
- 5.5 Consent Revocation
- 5.6 Consent Updates
6 Data Model
- 6.1 Identifier Fields
  - 6.1.1 Key
  - 6.1.2 Merchant Flow
  - 6.1.3 Person to Person Flow
- 6.2 Enumerations
  - 6.2.1 Common Enumerations
7 Alternative and Error Flows
- 7.1 Idempotent Behaviour
  - 7.1.1 Create Payment Order Consent
  - 7.1.2 Create Payment Order
8 OpenAPI Specifications

Version Control

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a {payment-order} using a staged {payment-order}-consent.

The API endpoints described here allow a Third Party to:

Register an intent to stage a {payment-order}-consent.
Subsequently submit a {payment-order} for processing.
Optionally retrieve the status of a {payment-order}-consent or {payment-order}.

A {payment-order} is defined as "an instruction by a payer or payee to its payment service provider requesting the execution of a payment transaction." This Payment API specification defines a hierarchy of:

{payment-order} is a generic type; in this specification this generic type has one specific resource:
- domestic-payments
{payment-order}-consents is a consent to initiate a {payment-order} and is a generic type; in this specification this generic type has two specific resources:
- domestic-payment-consents
- enduring-payment-consents

This specification should be read in conjunction with NZ Banking Data API Specification which provides a description of the elements that are common across all the NZ Banking Data APIs.

Document Structure

This document consists of the following parts:

Overview: Provides an overview of the scope of the API and the key decisions that contributed to the specification.
Basics: The section identifies the resources, operations that are permitted on those resources, and various special cases.
Endpoints: Provides the list of endpoints for the API specification. The individual endpoints are documented in separate sections along with the data model that they employ.
Security & Access Control: Specifies the means for Third Parties and Customers to authenticate themselves and provide consent.
Data Model: Describes the data model for the API payloads.
Usage Examples: Examples for normal flows, and alternate flows.
OpenAPI Specifications: Provides links to the OpenAPI specifications for the APIs.

Scope

The APIs in this document allow a Third Party to initiate a single, domestic, electronic credit {payment-order} made in NZD, using a previously authorised {payment-order}-consent. While this version of the API specification only allows access to NZ BECS identifiable accounts, the API specification is silent on what account types must be accessible.

Out of Scope

This specification does not cater for:

Payments that involve currencies other than NZD.
Payments that are not single, domestic, electronic credit payments.

Basics

Overview

The figure below provides a general outline of a payment flow using the Payment APIs.

Overview Diagram

Steps

Step 1: Agree Payment-Order Consent

This flow begins with a Customer agreeing a {payment-order}-consent for a Third Party to initiate {payment-order}s on the Customer's behalf.
The consent is between the Customer and the Third Party.
The debtor account details may be optionally specified at this stage.

Step 2: Create Payment-Order Consent

The Third Party connects to the API Provider that services the Customer's payment account and creates a new {payment-order}-consent.
The {payment-order}-consent may either be an enduring-payment-consent or a domestic-payment-consent.
- An enduring-payment-consent is a long-lived {payment-order}-consent.
- A domestic-payment-consent is a short-lived {payment-order}-consent.
The action informs the API Provider that one of its Customers intends to initiate a {payment-order}.
The API Provider responds with an identifier for the {payment-order}-consent (the ConsentId).
This step is carried out by making a POST request to a {payment-order}-consent endpoint.

Step 3: Authorise Consent

The Third Party initiates the authorisation flow for the Customer to authorise the consent.
The Third Party chooses either the redirection flow or a decoupled flow to authorise the Customer.
- In a redirection flow:
  - The Third Party redirects the Customer to the API Provider.
  - The redirect includes the ConsentId (generated in Step 2).
  - This allows the API Provider to correlate the {payment-order}-consent that was setup.
  - The API Provider authenticates the Customer.
  - The Customer selects the debtor account at this stage (if not previously specified in Step 1).
  - The Customer authorises the consent with the API Provider. The Customer will only be able to authorise or reject the consent details in its entirety.
  - The API Provider updates the state of the {payment-order}-consent internally to indicate that the consent has been authorised.
  - Once the consent has been authorised, the Customer is redirected back to the Third Party.
- In a decoupled flow:
  - The decoupled flow is initiated by the Third Party calling a back-channel authorisation request endpoint.
  - The back-channel authorisation request contains a 'hint' that identifies the Customer and the consent to be authorised.
  - The API Provider requests the Customer to authorise consent on an authentication device that may be separate from the consumption device on which the Customer is interacting with the Third Party.
  - The API Provider authenticates the Customer.
  - The Customer selects the debtor account at this stage (if not previously specified in Step 1).
  - The Customer authorises the consent with the API Provider. The Customer will only be able to authorise or reject the consent details in its entirety.
  - The API Provider updates the state of the {payment-order}-consent internally to indicate that the consent has been authorised.
  - Once the consent has been authorised, the API Provider may make a callback to the Third Party to notify them of successful authorisation.

Step 4: Create Payment-Order

Once the Customer has authorised the {payment-order}-consent, the Third Party creates a {payment-order} to indicate the {payment-order} should be submitted for processing.
This is carried out by making a POST request to the appropriate {payment-order} endpoint.
- If the Customer has authorised a domestic-payment-consent, the Third Party may create a single domestic-payment
- If the Customer has authorised an enduring-payment-consent, the Third Party may create multiple domestic-payments depending on the parameters of the enduring-payment-consent
The API Provider returns the identifier for the {payment-order} to the Third Party.

Step 5: Retrieve Status

The Third Party may retrieve the status of the {payment-order}-consent (with the ConsentId) or {payment-order} (with the {payment-order} identifier) or debtor-account details (with the {payment-order} identifier).
This is carried out by making a GET request to the relevant endpoint.

Sequence Diagram

participant Customer
participant "Third Party" as TPP
participant "API Provider Authorisation Server" as AS
participant "API Provider Resource Server" as RS

note over Customer, RS
Step 1: Agree Payment-Order Consent
end note
Customer -> TPP: Agree {payment-order}-consent

note over Customer, RS
Step 2: Create Payment-Order Consent
end note
TPP <-> AS: Establish TLS 1.2 MA
TPP -> AS: Initiate Client Credentials Grant
AS -> TPP: Return access-token
TPP <-> RS: Establish TLS 1.2 MA
TPP -> RS: POST /{payment-order}-consents
note over RS: Consent Status: AwaitingAuthorisation
RS -> TPP: HTTP 201 (Created), ConsentId

note over Customer, RS
Step 3: Authorise Consent
end note
alt Redirection (using authorization code grant)
TPP -> Customer: HTTP 302 (Found), Redirect (ConsentId)
Customer -> AS: Follow redirect (ConsentId)
Customer <-> AS: Authenticate
Customer <-> AS: Select debtor account if required
Customer <-> AS: Authorise consent
note over RS: Consent Status: Authorised
AS -> Customer: HTTP 302 (Found), Redirect (authorization-code)
Customer -> TPP: Follow redirect (authorization-code)
TPP <-> AS: Establish TLS 1.2 MA
TPP -> AS: Exchange authorization-code for access token
AS -> TPP: Return access-token
else Decoupled (Using CIBA)
TPP -> AS: POST /bc-authorize (login_hint_token)
AS -> TPP: OK

Customer -> AS: Authorise (Consent Id)
Customer <-> AS: Authenticate
Customer <-> AS: Select debtor accounts if required
Customer <-> AS: Authorise consent
note over RS: Consent Status: Authorised

alt Using callback
AS -> TPP: Callback (authorization-code)
TPP <-> AS: Establish TLS 1.2 MA
TPP -> AS: Exchange authorization-code for access token
AS -> TPP: Return access-token
else Using polling
TPP <-> AS: Establish TLS 1.2 MA
TPP -> AS: Poll at /token using auth-req-id
AS -> TPP: Return access-token
end alt
end alt

note over Customer, RS
Step 4: Create Payment-Order
end note
TPP <-> RS: Establish TLS 1.2 MA
TPP -> RS: POST /{payment-order}s
alt Domestic Payment Consent
note over RS: Consent Status: Consumed
end
note over RS: Payment Status: Pending
note over RS: Payment Status: AcceptedSettlementInProcess
note over RS: Payment Status: AcceptedSettlementCompleted
RS -> TPP: HTTP 201 (Created), PaymentOrderId

opt If Customer has authorised a long lived payment-consent
loop
TPP <-> RS: Establish TLS 1.2 MA
TPP -> RS: POST /{payment-order}s
RS -> TPP: HTTP 201 (Created), PaymentOrderId
end
end

note over Customer, RS
Step 5: Retrieve Status
end note

opt {payment-order}-consents
TPP <-> RS: Establish TLS 1.2 MA
TPP -> RS: GET /{payment-order}-consents/{ConsentId}
RS -> TPP: HTTP 200 (OK) {payment-order}-consent resource
end opt

opt {payment-order}s
TPP <-> RS: Establish TLS 1.2 MA
TPP -> RS: GET /{payment-order}s/{PaymentOrderId}
RS -> TPP: HTTP 200 (OK) {payment-order} resource
end opt

opt accounts
TPP <-> RS: Establish TLS 1.2 MA
TPP -> RS: GET /{payment-order}s/{PaymentOrderId}/debtor-account
RS -> TPP: HTTP 200 (OK) debtor account resource
end opt

Restrictions

The specification does not provide a uniform set of restrictions for {payment-order} support through this API. E.g., the maximum payment amount allowable.

An API Provider must determine appropriate restrictions that they support based on their individual practices, standards and limitations. These restrictions must be documented on API Provider developer portals.
An API Provider must reject the {payment-order}-consent if the API Provider is unable to handle the request.
An API Provider must reject the {payment-order} if the API Provider is unable to handle the request.

Release Management

This section overviews the release management and versioning strategy for the Payment Initiation APIs.

Enduring-Payment-Consents

POST

An API Provider must allow an enduring-payment-consent created on a lower version, to be used to create a {payment-order} in a higher version.
- E.g., a ConsentId created in v2, must be allowed be used to create a v3 DomesticPaymentId.
An API Provider must allow a token that is bound to a Consent in a lower version, to be used to create a {payment-order} in a higher version.
- E.g., a token issued from an authorization code grant using an enduring-payment-consent ConsentId from v2 must be allowed to be used to create a v3 DomesticPaymentId.
An API Provider must not allow an enduring-payment-consent created on a higher version, to be used to create a {payment-order} in a lower version.
- E.g., a ConsentId created in v2, must not be used to create a v1 PaymentSubmissionId.

GET

An API Provider must allow an enduring-payment-consent created on a lower version, to be accessed via a higher version.
- E.g., a ConsentId created in v2 must be allowed be accessed via v3, as this is a long lived consent.
An API Provider must not allow an enduring-payment-consent created on a higher version, to be accessed via a lower version.
- E.g., a ConsentId created in v3 must not be accessed via v2.
An API Provider must ensure the Consent object in an enduring-payment-consent is unchanged when accessed in a different version.
- E.g., an enduring-payment-consent created in v2 will have the same Consent object when accessed via v2 and v3.
An API Provider may allow an expired enduring-payment-consent created on a lower version, to be accessed via a higher version.
- E.g., an expired ConsentId created in v2 may be accessed via v3.

DELETE

An API Provider must not allow an enduring-payment-consent created in a higher version, to be deleted in a lower version.
- E.g., a ConsentId created in v3 must not allowed to be deleted via v2.
An API Provider must allow an enduring-payment-consent created in a lower version, to be deleted in a higher version.
- E.g., a ConsentId created in v1 must be allowed to be deleted via v2.

Domestic-Payment-Consents

POST

An API Provider must not allow a domestic-payment-consent created on a lower version, to be used to create a {payment-order} in a higher version.
- E.g., a PaymentId created in v1, must not be used to create a v2 DomesticPaymentId
An API Provider must not allow a domestic-payment-consent created on a higher version, to be used to create a {payment-order} in a lower version.
- E.g., a ConsentId created in v2, must not be used to create a v1 PaymentSubmissionId

GET

An API Provider may allow a domestic-payment-consent created on a lower version, to be accessed via a higher version.
- E.g., a PaymentId created in v1 may be allowed to be accessed via v2, as this is a short-lived consent.
An API Provider must not allow a domestic-payment-consent created on a higher version, to be accessed via a lower version.
- E.g., a ConsentId created in v2 must not be accessed via a v1 PaymentId.

Domestic-Payments

POST

An API Provider must only allow a domestic-payment-consent to be used create a domestic-payment in the same version.
- E.g., a ConsentId created in v3 must only be used to create a domestic-payment in v3.
An API Provider must allow an enduring-payment-consent to be used create a domestic-payment in the same version.
- E.g., a ConsentId created in v3 must be allowed to be used to create a domestic-payment in v3.
An API Provider must allow an enduring-payment-consent created on a lower version, to be used to create a domestic-payment in a higher version.
- E.g., a ConsentId created in v3 must be allowed to be used to create a domestic-payment in v4.
An API Provider must not allow an enduring-payment-consent created on a higher version, to be used to create a domestic-payment in a lower version.
- E.g., a ConsentId created in v4 must not be allowed to be used to create a domestic-payment in v3.

GET

An API Provider must allow a domestic-payment created on a lower version, to be accessed via a higher version. Retention will depend on an API Provider's legal requirement for data retention. In the case where a {payment-order} type is the same, but the structure has changed in a higher version, sensible defaults must be used, with the API Provider's developer portal clearly specifying the behaviour.
- E.g., a PaymentSubmissionId created in v1, must be accessible as a v2 domestic-payment (e.g., if an API Provider must make {payment-order}s available for 7 years).
- E.g., a new field StatusUpdateDateTime was introduced in v2, an API Provider must populate this with the last status update time (as the StatusUpdateDateTime is a mandatory field).
An API Provider must not allow a domestic-payment created on a higher version, to be accessed via a lower version.
- E.g., a DomesticPaymentId created in v2 must not be allowed to be accessed via the v1 payment-submissions endpoint.
An API Provider must document the behaviour on the accessibility of a {payment-order} in a higher version on the API Provider's developer portal.

Endpoints

This section looks at the list of available API endpoints for Payments and optionality.

The API Provider must implement the API endpoints in the table below that are marked as mandatory.
The API Provider may optionally implement the API endpoints that are marked as non-mandatory.

Endpoint design considerations:

Having a separate resource for the {payment-order}-consent and {payment-order} means we can extend the flows in the future.
Separation in the {payment-order}-consent and the {payment-order} also allows for cleaner separation in updating the status of resources.

Document Section	Resource	Endpoint	Mandatory ?

Document Section	Resource	Endpoint	Mandatory ?
Enduring Payment Consents	enduring-payment-consents	POST /enduring-payment-consents	Mandatory
Enduring Payment Consents	enduring-payment-consents	GET /enduring-payment-consents/{ConsentId}	Mandatory
Enduring Payment Consents	enduring-payment-consents	DELETE /enduring-payment-consents/{ConsentId}	Mandatory
Domestic Payment Consents	domestic-payment-consents	POST /domestic-payment-consents	Mandatory
Domestic Payment Consents	domestic-payment-consents	GET /domestic-payment-consents/{ConsentId}	Mandatory
Domestic Payments	domestic-payments	POST /domestic-payments	Mandatory
Domestic Payments	domestic-payments	GET /domestic-payments/{DomesticPaymentId}	Mandatory
Domestic Payments	debtor-account	GET /domestic-payments/{DomesticPaymentId}/debtor-account	Mandatory

Payment Resources

Each of the high level resources are documented in sub-pages of the Payment API specification with these sections:

Definition
Endpoints
Data Model
- UML diagram
- Data dictionary
Usage Examples

Security & Access Control

This should be read in conjunction with the Security Profile, which is the canonical reference for the standards security.

Scopes

The access tokens required for accessing the Payment APIs must have one of the following scopes:

Scopes

payments

Grants Types

Third Parties must use a client credentials grant to obtain a token with the scope payments to make:

POST requests to the enduring-payment-consents resource.
GET requests to the enduring-payment-consents resource.
DELETE requests to the enduring-payment-consents resource.
POST requests to the domestic-payment-consents resource.
GET requests to the domestic-payment-consents resource.
GET requests to the domestic-payments resource.
GET requests to the debtor-account sub-resource of a domestic-payment.

Third Parties must use an authorisation flow using a redirect flow or decoupled flow to obtain a token with the scope payments to make:

POST requests to the domestic-payments resource.

Consent Authorisation

A consent authorisation is used to define the fine-grained scope that is granted by the Customer to the Third Party.

The Third Party must begin a single electronic credit payment request by creating a {payment-order}-consent through a POST operation. This consent contains the consent that the Third Party claims it has been given by the Customer. At this stage, the consent is not yet authorised as the API Provider has not yet verified this claim with the Customer.

The API Provider responds with a ConsentId. This is the ConsentId that is used when initiating the authorisation flow (as described in the NZ Banking Data Security Profile).

As part of the authorisation flow:

The API Provider authenticates the Customer.
The API Provider plays back the consent (registered by the Third Party) back to the Customer - to get consent authorisation.
- If the consent did not indicate a debtor account, the API Provider presents the Customer a list of accounts from which the Customer may select an account or accounts that apply to the consent.
The Customer may accept or reject the consent in its entirety (but not selectively).

Once these steps are complete, the consent is considered to have been authorised by the Customer.

Consent Re-authorisation

An API Provider may allow a Customer to re-authorise an enduring-payment-consent (as it is a long-lived consent) if:

The enduring-payment-consent has a status of Authorised; and
The ToDateTime of the enduring-payment-consent has not elapsed.

An API Provider must not allow a Customer to re-authorise a domestic payment consent (as it is a short-lived consent).

Consent Revocation

An API Provider must not allow a Customer to revoke a short-lived (a domestic-payment-consent) {payment-order}-consent once it has been authorised.

An API Provider must allow a Customer to revoke a long-lived (an enduring-payment-consent) {payment-order}-consent:

If the {payment-order}-consent is valid and has not expired

Consent Updates

A design principle for NZ Banking Data APIs is that consent must not be changed once the consent has been authorised.

An API Provider must not allow a Customer to update the parameters of a short-lived (a domestic-payment-consent) {payment-order}-consent once it has been authorised. This includes debtor account details.

An API Provider must not allow a Customer to update the parameters of a long-lived (an enduring-payment-consent) {payment-order}-consent. This includes debtor account details.

Data Model

Identifier Fields

This section describes the identifiers used through the Payment API flows - the direction of flow through the system, and how they are used.

The standard definitions for the elements in the API payloads are described in the Data Model section for each resource. However, this table gives further detail on the business meaning, and how they are used.

Identifier	Generated	Business Description

Identifier	Generated	Business Description
EndToEndIdentification	Third Party (or Merchant)	The EndToEndIdentification reference is a reference that can be populated by the debtor (or merchant in the ecommerce space). This reference is important to the debtor (could be an internal reference Id against the transaction), it is NOT the reference information that will be primarily populated on the statement of the creditor (beneficiary).
InstructionIdentification	Third Party (or Merchant)	Third Party generates the InstructionIdentification which is a unique transaction Id and passes it to the API Provider (this is mandatory), but this doesn’t have to go any further in the payment flow. The flow of this identifier needs to align with payment scheme rules. The expectation is that this is unique indefinitely across all time periods. The Third Party can ensure this is indefinitely unique by including a date or date time element to the field, or by inserting a unique Id.
RemittanceInformation	Third Party (or Merchant)	RemittanceInformation contains Particulars, Code and Reference for both Debtor and Creditor, along with names for both parties. This information is populated by the Third Party in the {payment-order}-consent and {payment-order}.
ConsentId	API Provider	Unique identification as assigned by the API Provider to uniquely identify the {payment-order}-consent resource.
PaymentOrderId	API Provider	Unique identification as assigned by the API Provider to uniquely identify the {payment-order} resource.

The tables below identify the actor that initially creates each of the message identifiers and their transmission and visibility to other actors.

These flows are indicative - and will be dependent on what payment schemes or agencies are able to support.

Key

O indicates the actor that creates the identifier.

=> downstream direction of flow

<= upstream direction of flow

Merchant Flow

Identifier	Customer	Merchant	Third Party	API Provider	Beneficiary

Identifier	Merchant	Third Party	API Provider	Beneficiary
EndToEndIdentification	O	=>	=>	=>
RemittanceInformation	O	=>	=>	=>
InstructionIdentification		O	=>
ConsentId		<=	O
PaymentOrderId		<=	O

Person to Person Flow

Identifier	Customer	Merchant	Third Party	API Provider	Beneficiary

Identifier	Customer	Third Party	API Provider	Beneficiary
EndToEndIdentification		O	=>	=>
RemittanceInformation	O	=>	=>	=>
InstructionIdentification		O	=>
ConsentId		<=	O
PaymentOrderId		<=	O

Enumerations

Common Enumerations

This section gives the definitions for enumerations shared by the Payment API resources.

Code Class	Name	Definition

Code Class

Name

Definition

OBExternalAccountIdentification2Code

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.

Alternative and Error Flows

Idempotent Behaviour

Create Payment Order Consent

In this scenario a failure has meant the Third Party needs to retry creating a {payment-order}-consent, and does so with the same idempotency key.

This has been generalised for all {payment-order}-consents.

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 2: Setup {payment-order}-consent
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: Return access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /{payment-order}-consents (x-idempotency-key={third-party-guid-1})
APIProviderRS -> APIProviderRS: Create new resource (ConsentId=1001)
alt unexpected failure
3P -> APIProviderRS: POST /{payment-order}-consents (x-idempotency-key={third-party-guid-1})
note right of APIProviderRS
The resource server recognises that
this is the same request as earlier.
A new resource is not created.
The ConsentId remains the same 
(e.g. 1001) as above.

The status of the resource may be 
different if it has changed.

This operation can be retried multiple 
times if required.
end note
end
APIProviderRS -> 3P: HTTP 201 (Created), ConsentId=1001
3P -> Cx: Redirect (ConsentId}

Create Payment Order

In this scenario a failure has meant the Third Party needs to retry creating a {payment-order}, and does so with the same idempotency key.

This has been generalised for all {payment-order}s.

OpenAPI Specifications

The OpenAPI Specification for the Payments Initiation APIs can be downloaded from https://github.com/PaymentsDirection/API-Payments-Initiation

Payments Initiation API Specification - v3.0.1

Version Control

Overview

Document Structure

Scope

Out of Scope

Basics

Overview

Overview Diagram

Steps

Sequence Diagram

Restrictions

Release Management

Enduring-Payment-Consents

POST

GET

DELETE

Domestic-Payment-Consents

POST

GET

Domestic-Payments

POST

GET

Endpoints

Payment Resources

Security & Access Control

Scopes

Scopes

Grants Types

Consent Authorisation

Consent Re-authorisation

Consent Revocation

Consent Updates

Data Model

Identifier Fields

Key

Merchant Flow

Person to Person Flow

Enumerations

Common Enumerations

Alternative and Error Flows

Idempotent Behaviour

Create Payment Order Consent

Create Payment Order

OpenAPI Specifications