Version Control

Overview

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

...

• 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-orders (generic type)

  • domestic-payments

• payment-order consents (generic type) - a consent to initiate payment-orders

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

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

• Payments that require multiple authorisers.

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
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-orders
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), Payment-Order Id

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-orders
API Provider Resource Server -> Third Party: HTTP 201 (Created), Payment-Order Id
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-orders
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: GET /payment-orders/{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-orders/{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.

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

...

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

Payment Resources

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

...

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

...

<= upstream direction of flow

Merchant Flow

Person to Person Flow

Enumerations

Common Enumerations

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

Alternative and Error Flows

...

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.

...

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-orders ConsentId = 1001, x-idempotency-key={third-party-guid-2}
alt Third Party attempts to POST to /payment-orders with same ConsentId
3P -> APIProviderRS: POST /payment-orders 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 from the Payments NZ API Centre GitHub repo:

...

https://github.com/PaymentsDirectionPaymentsNZ/API-Payments-Initiation

...

/tree/master/dist/v2.0.0