Version Control

Version

Date

Author

Comments

2.0.0

Payments NZ API Working Group

Baseline

2.1-draft1

 

Gavin Wong (Unlicensed)

Updated:

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:

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:

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:

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:

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

Step 2: Create Payment-Order Consent

Step 3: Authorise Consent

Step 4: Create Payment-Order

Step 5: Retrieve Status

Sequence Diagram

participant Customer
participant Third Party
participant API Provider Authorisation Server
participant API Provider Resource Server

note over Customer, API Provider Resource Server
Step 1: Agree Payment-Order Consent
end note
Customer -> Third Party: Agree {payment-order}-consent

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

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

Customer -> API Provider Authorisation Server: Authorise (Consent Id)
Customer <-> API Provider Authorisation Server: Authenticate
Customer <-> API Provider Authorisation Server: Select debtor accounts if required
Customer <-> API Provider Authorisation Server: Authorise consent
note over API Provider Resource Server: Consent Status: Authorised

alt Using callback
API Provider Authorisation Server -> Third Party: Callback (authorization-code)
Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA
Third Party -> API Provider Authorisation Server: Exchange authorization-code for access token
API Provider Authorisation Server -> Third Party: Return access-token
else Using polling
Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA
Third Party -> API Provider Authorisation Server: Poll at /token using auth-req-id
API Provider Authorisation Server -> Third Party: Return access-token
end alt
end alt

note over Customer, API Provider Resource Server
Step 4: Create Payment-Order
end note
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: POST /{payment-order}s
note over API Provider Resource Server: Consent Status: Consumed
note over API Provider Resource Server: Payment Status: Pending
note over API Provider Resource Server: Payment Status: AcceptedSettlementInProcess
note over API Provider Resource Server: Payment Status: AcceptedSettlementCompleted
API Provider Resource Server -> Third Party: HTTP 201 (Created), PaymentOrderId

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

note over Customer, API Provider Resource Server
Step 5: Retrieve Status
end note

opt {payment-order}-consents
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: GET /{payment-order}-consents/{ConsentId}
API Provider Resource Server -> Third Party: HTTP 200 (OK) {payment-order}-consent resource
end opt

opt accounts
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: GET /{payment-order}-consents/{ConsentId}/accounts
API Provider Resource Server -> Third Party: HTTP 200 (OK) accounts resource
end opt

opt {payment-order}s
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: GET /{payment-order}s/{PaymentOrderId}
API Provider Resource Server -> Third Party: HTTP 200 (OK) {payment-order} resource
end opt

opt accounts
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: GET /{payment-order}s/{PaymentOrderId}/accounts
API Provider Resource Server -> Third Party: HTTP 200 (OK) accounts 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.

Release Management

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

Enduring-Payment-Consents

POST

GET

DELETE

Domestic-Payment-Consents

POST

GET

Domestic-Payments

POST

GET

Endpoints

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

Endpoint design considerations:

Document Section

Resource

Endpoint

Mandatory ?

Enduring Payment Consents

enduring-payment-consents

POST /enduring-payment-consents

Optional

Enduring Payment Consents

enduring-payment-consents

GET /enduring-payment-consents/{ConsentId}

Optional

Enduring Payment Consents

enduring-payment-consents

DELETE /enduring-payment-consents/{ConsentId}

Optional

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:

Security & Access Control

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:

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

Consent Authorisation

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:

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:

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:

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

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

EndToEndIdentification


O

=>

=>

=>

RemittanceInformation


O

=>

=>

=>

InstructionIdentification



O

=>


ConsentId



<=

O


PaymentOrderId



<=

O


Person to Person Flow

Identifier

Customer

Merchant

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 

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.

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 4: Create {payment-order}
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /{payment-order}s ConsentId = 1001, x-idempotency-key={third-party-guid-2}
alt Third Party attempts to POST to /{payment-order}s with same ConsentId
3P -> APIProviderRS: POST /{payment-order}s ConsentId = 1001, x-idempotency-key={third-party-guid-2}
APIProviderRS -> 3P: HTTP 201 (Created), PaymentOrderId
note right of APIProviderRS
The resource server recognises that this
is the same request as earlier.

A new resource is not created.
The PaymentOrderId remains the 
same as above. The status of the resource 
May be different if it has changed.

If the status of the resource has changed,
the API Provider will return the up to date
status.

The operation can be retried multiple times
if required.
end note
end

Swagger Specifications

The Swagger Specification for the Payments Initiation APIs can be downloaded from the Payments NZ API Centre GitHub repo:

https://github.com/PaymentsNZ/API-Account-Information/tree/master/dist/v2.1.0