Contents

Version Control

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a single, domestic, electronic credit payment.

The API endpoints described here allow a Third Party  to: 

• Register an intent to setup a payment instruction 

• Subsequently submit the payment instruction for processing

• Optionally retrieve the status of a payment setup or submission.

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 end-points are documented in separate sections along with the data model that they employ.

Security & Access Control: Specifies the means for Third Parties (or TPP) and Customers (or PSU) to authenticate themselves and provide consent.

Payments: Describes the specifics of the endpoints for the payments resource.

Payment Submissions: Describes the specifics of the endpoints for the payment-submissions resource.

Usage Examples: Examples for normal flows, and alternate flows.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Scope

The APIs in this document allow a Third Party to initiate a single, domestic, electronic credit payment made in NZD.

Out of Scope

This specification does not cater for:

• Payments that involve currency exchange.

• Payments that involve currencies other than NZD

• Payments that are not single, domestic, electronic credit payments made in NZD - i.e., payments that are:

  • In bulk - single debit, multiple credit

  • Future dated or deferred

  • Recurring.

• Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are not included in this version.

• Non-functional requirements and specification of caching and throttling.

Basics

Overview

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

Diagram

Open

Steps

Step 1: Request Payment Initiation

• This flow begins with a Customer requesting to initiate a payment being made by a Third Party on their behalf.

• The debtor account and payment details can optionally be specified at this stage.

Step 2: Setup Single Payment Initiation

• The Third Party  connects to the Bank  that services the Customer's (or Customer's) payment account and creates a new payments resource. This informs the Bank that one of its Customers intends to make a payment. The Bank responds with an identifier for the resource (the PaymentId - which is the intent identifier).

• This step is carried out by making a POST request to the payments resource.

Step 3: Authorise Consent

• The Third Party redirects the Customer to the Bank. The redirect includes the PaymentId generated in the previous step. This allows the Bank to correlate the payment that was setup. The Bank authenticates the Customer. This could use a form of strong authentication, such as multi-factor authentication, if the Bank desires. The Bank  updates the state of the payments resource internally to indicate that the payment has been authorized.

• The Customer selects the debtor account at this stage - if it has not been previously specified in Step 1.

• The Customer is redirected back to the Third Party.

Step 4: Create Payment Submission

• Once the Customer is redirected to the Third Party, the Third Party creates a payment-submissions resource to indicate that the payment created in the steps above should be submitted for processing.

• This is carried out by making a POST request to the payment-submissions resource.

• Bank returns the PaymentSubmissionId to the Third Party.

Step 5: Get Payment Submission Status

• If the Bank provides a status API, the Third Party can check the status of the payment (with the PaymentId) or payment-submission (with the PaymentSubmissionId).

• This is carried out by making a GET request to the payments or payment-subsmissions resource.

Sequence Diagram

Open

Idempotency

POST operations on both the /payments and /payment-submissions endpoint are designed to be idempotent. The intent of this capability is to allow Third Party to retry API requests that failed with a timeout or an unexpected error.

If the Third Party re-uses an x-Idempotency-key that they previously used within the last 24 hours, but with a different payment Id on the request the API Provider must reject the request with a status code of 400 (Bad Request) 

Payment Limits

The standard does not provide a uniform limit for payments that can be supported through this API.

Each API Provider must determine an appropriate limit that they support based on their individual practices, standards and limitations.

Endpoints

This section looks at the list of available API endpoints to access Account Information and optionality (definitions of mandatory, conditional or optional are defined in the Principles section of the NZ Banking Data API Specification).

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.

If an API Provider has not implemented an optional API endpoint, it must respond with a 501 (Not Implemented) for requests to that URL. As all Payment API endpoints are mandatory in this version of the standard, API Providers must not respond with a 501 (Not Implemented) for the Payment APIs.

Endpoint design considerations:

• Having a separate resource for the payment setup and payment submission means we can extend the flows in the future more easily for bulk and recurring payments. 

• Separation in setup and submission also allows for cleaner separation in updating the status of resources - for API Providers that chose to implement the functionally

Security & Access Control

Scopes

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

Scopes

Grants Types

Third Parties must use a client credentials grant to obtain a token with the scope third_party_client_credential to make POST requests to the payments resource.

Third Parties must use an authorization code grant to obtain a token with the scope payments to make POST requests to the payment-submissions resource.

Third Parties must use a client credentials grant to obtain a token with the scope third_party_client_credential to make GET requests to the payments resource.

Third Parties must use an authorization code grant to obtain a token with the scope payments to make GET requests to the payments-submission resource. The grant type for GET requests to the payment-submission resource is likely to be reviewed for a future version of the standard.

Consent Authorisation

The Third Party must begin a single electronic credit payment request by creating a payments resource through a POST operation. This resource indicates 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 PaymentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

As part of the authorization code grant:

• 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. The Customer may accept or reject the consent in its entirety (but not selectively).

• 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 one.

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

Consent Revocation

A Customer cannot revoke consent for a single electronic credit payment - once it has been authorised.

Changes to Selected Account

For a single electronic credit payment, the selected debtor account cannot be changed once the consent has been authorised.

Handling Expired Tokens

Due to the nature of single electronic credit payments, an access token is unlikely to expire before it is used for creating the payment-submission. Consequently, issuing a refresh token along with the access token is probably not useful in this situation.

However, to simplify their implementation, an API Provider may issue a refresh token along with an access token at the end of an authorisation code grant. 

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.

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

Person to Person Flow

Mapping to Schemes & Standards

ISO 20022

The Initiation section of the Payment API payloads is based on the ISO 20022 pain.001 XML standard - and we have used ISO 20022 message elements or components - where possible. However - has been adapted for APIs based as per our design principles. 

Deviations from the pain.001 XML standard are:

• The pain.001 header section and trailer sections have been removed - as these are not required for a RESTful API

• Only fields required for the v1.0 scope of single-debit single-credit NZD payments, immediately executed are included in the payload. This has meant:

  • The separate CreditTransferTransactionInformation section in pain.001 - which is a repeating group for multi-credit payments has been removed and flattened

  • PaymentInformationIdentification not required - we also have a InstructionIdentification

  • PaymentMethod not required - as this is always immediate execution for the API Provider

  • RequestedExecutionDate not required - as this is always as soon as possible - which may differ between FPS and Bacs payments

  • Debtor / DebtorAccount are optional - as the debtor details are not always known to the Third Party submitting the payment setup or submit

• The Payment Initiation team has requested a flatter structure for the payload:

  • InstructionIdentification and EndToEndIdentification moved to the top level (instead of embedding within PaymentIdentification) 

  • CreditorAgent is simplified to only include the SchemeName and Identification

  • DebtorAccount and CreditorAccount are simplified to only include the SchemeName and Identification

Transaction Status

A principle has been agreed to adhere to the ISO Transaction Status codes.

The ISO Transaction Status has been split into statuses for the payments setup resource, and the payment-submissions resource. Refer to the resource sections for specifics on which states relate to which resource.

Open