Contents

Version Control


VersionDateAuthorComments
1.0.001 March 2019Payments NZ API Working Group

Payment Initiation specifcation.


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: 

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.

EndpointsProvides 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:


Basics

Overview

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

Diagram



Steps

Step 1: Request Payment Initiation

Step 2: Setup Single Payment Initiation

Step 3: Authorise Consent

Step 4: Create Payment Submission

Step 5: Get Payment Submission Status

Sequence Diagram

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 1: Request payment initiation
end note
Cx -> 3P: Send payment initiation request
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments
APIProviderRS -> 3P: HTTP 201 (Created),  PaymentId
3P -> Cx: HTTP 302 (Found), Redirect (PaymentId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (PaymentId)
group Refer to Consent Guidelines
Cx <-> APIProviderAS: Authenticate, may involve multi-factors or other strong authentication mechanisms
Cx <-> APIProviderAS: Select debtor account
end group
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note over Cx, APIProviderRS
Step 5: Get payment submission status
end note
opt
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /payment-submissions/{PaymentSubmissionId}
APIProviderRS -> 3P: HTTP 200 (OK) payment-submissions resource
end opt


Idempotency

POST operations on both the /payments and /payment-submissions endpoint are designed to be idempotentThe 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:


Document SectionResourceEnd-pointMandatory ?
PaymentspaymentsPOST /paymentsMandatory

paymentsGET /payments/{PaymentId}Mandatory
Payment Submissionspayment-submissionsPOST /payment-submissionsMandatory

payment-submissionsGET /payment-submissions/{PaymentSubmissionId}Mandatory


Security & Access Control

Scopes

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

third_party_client_credential
payments


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.


GeneratedIdentifierOptional/MandatoryBusiness Description

Merchant/Third Party

Sent in API Payload

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

Merchant/Third Party

Sent in API Payload

InstructionIdentification

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.

Merchant/Third Party

Sent in API Payload

RemittanceInformation
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 and payment-submission request. 

API Provider / API System

PaymentId
Unique identification as assigned by the API Provider to uniquely identify the payment setup resource.
API Provider / API SystemPaymentSubmissionId
Unique identification as assigned by the API Provider to uniquely identify the payment-submission resource.

API Provider / Payment Scheme

Scheme Payment ID
This is generated by the API Provider to uniquely identify a payment through a processing scheme. In the case of FPS - this is the FPID.


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

Originating Bank

Payment Scheme

Beneficiary

EndToEndIdentification
O=>=>=>=>
RemittanceInformation
O=>=>=>=>
InstructionIdentification

O

=>


PaymentId

<=

O



PaymentSubmissionId

<=O

Scheme Payment ID

(e.g., FPID)




O

=>

=>


Person to Person Flow


Identifier

Customer

Merchant

Third Party

API Provider

Originating Bank

Payment Scheme

Beneficiary

EndToEndIdentification

O=>=>=>
RemittanceInformationO
=>=>=>=>
InstructionIdentification

O

=>


PaymentId

<=

O



PaymentSubmissionId

<=O

Scheme Payment ID

(e.g., FPID)




O

=>

=>


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:


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.


@startuml
skinparam monochrome true
hide empty description


[*] --> Pending

Pending -down-> AcceptedTechnicalValidation : [API call is valid]
state Rejected1 as "Rejected"
AcceptedTechnicalValidation -right-> Rejected1 : [Authorisation has failed, payment has been rejected]
AcceptedTechnicalValidation -down-> AcceptedCustomerProfile : [Authorisation is complete]

AcceptedCustomerProfile-right->AcceptedSettlementInProcess : [Payment has been successfully submitted to API Provider]
AcceptedSettlementInProcess-right->Rejected : [Payment has failed and been rejected]
AcceptedSettlementInProcess-down->AcceptedSettlementComplete : [Final checks complete, money has left the debtor's account]

@enduml



Enumerations

Common Enumerations

This section gives the definitions for enumerations shared by the payments and payment-submissions resources


Code ClassName Definition 
ExternalPaymentContext1CodeBillPaymentThe context of the payment initiation is a bill payment.
ExternalPaymentContext1CodeEcommerceGoodsThe context of the payment initiation is for goods via an ecommerce channel.
ExternalPaymentContext1CodeEcommerceServicesThe context of the payment initiation is for services via an ecommerce channel.
ExternalPaymentContext1CodePartyToPartyThe context of the payment initiation is a party to party payment.
ExternalPaymentContext1CodeOtherThe context of the payment initiation is of an other type.
OBExternalAccountIdentification2CodeBECSElectronicCredit

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.
OBExternalFinancialInstitutionIdentification2CodeBICFIValid BICs for financial institutions are registered by the ISO 9362 Registration Authority in the BIC directory, and consist of eight (8) or eleven (11) contiguous characters.
OBTransactionIndividualStatus1CodeAcceptedCustomerProfilePreceding check of technical validation was successful. Customer profile check was also successful.
OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted

Settlement on the debtor's account has been completed.

Usage : this can be used by the first agent to report to the debtor that the transaction has been completed. Warning : this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

Third Parties must not use this status as confirmation that settlement is complete on the creditor's account.

OBTransactionIndividualStatus1CodeAcceptedSettlementInProcessAll preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
OBTransactionIndividualStatus1CodeAcceptedTechnicalValidationAuthentication and syntactical and semantic validation are successful.
OBTransactionIndividualStatus1CodePendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
OBTransactionIndividualStatus1CodeRejectedPayment initiation or individual transaction included in the payment initiation has been rejected.

ISO Enumerations

These following ISO Enumerations are used in the Payments API


ISO Data TypeFieldsISO Enumerations Values URL
Min3Max4TextMerchantCategoryCodehttps://www.iso.org/standard/33365.html
ActiveOrHistoricCurrencyCodeCurrencyhttps://www.iso20022.org/external_code_list.page
CountryCodeCurrencyhttps://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements

Data Model

Reused Classes

OBInitiation1

This section describes the OBInitiation1 class - which is reused as the Initiation object in the payments and payment-submissions resources.

UML Diagram

Notes

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBInitiation1
OBInitiation1The Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

InstructionIdentification1..1OBInitiation1/InstructionIdentificationUnique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.

Usage: the  instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.

OBNZ: Updated to allow 36 characters to allow for v4 UUID
Max36Text

EndToEndIdentification1..1OBInitiation1/EndToEndIdentificationUnique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.

OBNZ: Updated to allow 36 characters to allow for v4 UUID
Max36Text

InstructedAmount1..1OBInitiation1/InstructedAmountAmount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.
OBActiveOrHistoricCurrencyAndAmount

Amount1..1OBInitiation1/InstructedAmount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.ActiveCurrencyAndAmount_SimpleType
^\d{1,13}\.\d{1,5}$
Currency1..1OBInitiation1/InstructedAmount/CurrencyA code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
DebtorAccount0..1OBInitiation1/DebtorAccountUnambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.OBCashAccountDebtor1

SchemeName1..1OBInitiation1/DebtorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeBECSElectronicCredit
Identification1..1OBInitiation1/DebtorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner. For the NZ market, this will use the hyphen-delimited format: 2-4-7-2 where this is made up of bank-branch-account-suffix and each of the four components is a number, prepended with leading zeros to match the component length requirement.
For example 12-0123-0012345-00
Max34Text

Name0..1OBInitiation1/DebtorAccount/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Max70Text

SecondaryIdentification0..1OBInitiation1/DebtorAccount/SecondaryIdentificationThis is secondary identification of the account, as assigned by the account servicing institution. Max34Text

CreditorAgent0..1OBInitiation1/CreditorAgentFinancial institution servicing an account for the creditor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBInitiation1/CreditorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBInitiation1/CreditorAgent/IdentificationUnique and unambiguous identification of a financial institution or a branch of a financial institution.Max35Text

CreditorAccount1..1OBInitiation1/CreditorAccountUnambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.OBCashAccountCreditor1

SchemeName1..1OBInitiation1/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeBECSElectronicCredit
Identification1..1OBInitiation1/CreditorAccount/IdentificationIdentification assigned by an institution to identify an account. This identification is known by the account owner. For the NZ market, this will use the hyphen-delimited format: 2-4-7-2 where this is made up of bank-branch-account-suffix and each of the four components is a number, prepended with leading zeros to match the component length requirement.
For example 12-0123-0012345-00
Max34Text

Name1..1OBInitiation1/CreditorAccount/NameName of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
API Providers may carry out name validation for Confirmation of Payee, but it is not mandatory.
Max70Text

SecondaryIdentification0..1OBInitiation1/CreditorAccount/SecondaryIdentificationThis is secondary identification of the account, as assigned by the account servicing institution. Max34Text

RemittanceInformation1..1OBInitiation1/RemittanceInformationInformation supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.NZRemittanceInformation1

Reference0..1OBInitiation1/RemittanceInformation/ReferenceRemittance information for use with BECSElectronicCredit payment scheme.NZBECSRemittance1

CreditorName1..1OBInitiation1/RemittanceInformation/Reference/CreditorNameThe Creditor's Name.Max20Text

DebtorName0..1OBInitiation1/RemittanceInformation/Reference/DebtorNameThe Debtor's Name.Max20Text

CreditorReference0..1OBInitiation1/RemittanceInformation/Reference/CreditorReferenceInformation supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.NZBECSReference1

Particulars0..1OBInitiation1/RemittanceInformation/Reference/CreditorReference/ParticularsReference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.Max12Text

Code0..1OBInitiation1/RemittanceInformation/Reference/CreditorReference/CodeReference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.Max12Text

Reference0..1OBInitiation1/RemittanceInformation/Reference/CreditorReference/ReferenceReference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.Max12Text

DebtorReference0..1OBInitiation1/RemittanceInformation/Reference/DebtorReferenceInformation supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.NZBECSReference1

Particulars0..1OBInitiation1/RemittanceInformation/Reference/DebtorReference/ParticularsReference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.Max12Text

Code0..1OBInitiation1/RemittanceInformation/Reference/DebtorReference/CodeReference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.Max12Text

Reference0..1OBInitiation1/RemittanceInformation/Reference/DebtorReference/ReferenceReference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.Max12Text


Payments

ResourceEnd-pointMandatory ?ScopeGrant TypeIdempotentRequest ObjectResponse Object
paymentsPOST /paymentsMandatory

third_party_client_credential

Client CredentialsYesOBPaymentSetup1OBPaymentSetupResponse1
paymentsGET /payments/{PaymentId}Mandatorythird_party_client_credentialClient CredentialsNANAOBPaymentSetupResponse1

Payment Status

The Customer must authenticate with the API Provider and authorise the payment setup for the payment to be successfully setup.When the payments resource is initially created it must have one of the following PaymentStatusCode code-list enumerations:


Status

Payment Status Description

NZ Status Clarification

1

Pending

Payment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.

Initial status.  The request was received but not yet validated. The payment has not yet been authorised.

2

Rejected

Payment initiation or individual transaction included in the payment initiation has been rejected.

Terminal state.  Does not distinguish between failure reasons - e.g. authorisation failed or bank rejected.

3

AcceptedTechnicalValidation

Authentication and syntactical and semantic validation are successful.

Intermediate state. All information supplied in the payment resource is valid, e.g.

  • Adheres to data validation schema

  • Business checks complete such as account is open, account is valid, account has sufficient funds

The payment has not yet been authorised.

When the Customer has authorised consent the status will be updated to "AcceptedCustomerProfile".After authorisation has taken place the payments resource may have these following status:


Status

Payment Status Description

NZ Status Clarification

4

AcceptedCustomerProfile

Preceding check of technical validation was successful. Customer profile check was also successful.

Terminal state.The payment has been authorised by the customer.

This is the state diagram for the status of a payment resource.

@startuml

skinparam monochrome true

hide empty description

[*] --> PendingPending -down-> AcceptedTechnicalValidation : [API call is valid]

state Rejected1 as "Rejected"

AcceptedTechnicalValidation -right-> Rejected1 : [Authorisation has failed, payment has been rejected]

AcceptedTechnicalValidation -down-> AcceptedCustomerProfile : [Authorisation is complete]@enduml

POST /payments

The API allows the Third Party to ask an API Provider to create a new payments resource.

GET /payments/{PaymentId}

A Third Party may optionally retrieve a payments resource that they have created to check its status.

Data Model

This section gives detail on the payload content for the payments resource. 

Payment Setup - Request

The OBPaymentSetup1 object will be used for the call to:

UML Diagram

Notes

The Payment Setup request contains these objects:

Data Dictionary


NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSetup1
OBPaymentSetup1
OBPaymentSetup1

Data1..1OBPaymentSetup1/Data
OBPaymentDataSetup1

Initiation1..1OBPaymentSetup1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSetup1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1

Payment Setup - Response

The OBPaymentSetupResponse1 object will be used for a response to a call to:

UML Diagram

Notes

The Payment Setup response contains the full original payload from the Payment Setup POST request - with these additional elements:

Data Dictionary


NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSetupResponse1
OBPaymentSetupResponse1
OBPaymentSetupResponse1

Data1..1OBPaymentSetupResponse1/Data
OBPaymentDataSetupResponse1

PaymentId1..1OBPaymentSetupResponse1/Data/PaymentIdUnique identification as assigned by the API Provider to uniquely identify the payment setup resource.Max128Text

Status1..1OBPaymentSetupResponse1/Data/StatusSpecifies the status of the payment resource.OBTransactionIndividualStatus1CodeAcceptedCustomerProfile
AcceptedTechnicalValidation
Pending
Rejected

CreationDateTime1..1OBPaymentSetupResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime

Initiation1..1OBPaymentSetupResponse1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSetupResponse1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1

Payment Submissions

Resource

End-Point

Mandatory?

Scope

Grant Type

Idempotent

Request Object

Response Object

payment-submissions

POST /payment-submissions

Mandatory

payments

Authorization Code

Yes

OBPaymentSubmission1

OBPaymentSubmissionResponse1

payment-submissions

GET /payment-submissions/{PaymentSubmissionId}

Mandatory

payments

Authorization Code

NA

NA

OBPaymentSubmissionResponse1

Payment Submission Status

A payment-submission can only be created if its corresponding payments resource has the status of 'AcceptedCustomerProfile'. When payment-submissions resource is initially created it must have  one of the following PaymentStatusCode code-set enumerations:



StatusPayment Status DescriptionNZ Status Clarification
1PendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.Initial State.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.Terminal State.Does not distinguish between failure reasons - e.g. insufficient funds.
3AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.Intermediate State.This state indicates:
  • The Payments Resource has been successfully created, including all necessary business checks such as sufficient funds;
  • The customer has authorised consent for the payment to be processed; and
  • The bank has accepted the customer mandate to make the payment.
A payment submission in this status is generally expected to execute successfully; however subsequent fraud checks and/or errors may still prevent the completion of the payment. 

Once settlement on the debtor's account has been completed, the payments-submissions resource may have one of the following statuses:


StatusPayment Status DescriptionNZ Status Clarification
4AcceptedSettlementCompletedSettlement on the debtor's account has been completed. Terminal State.Funds have left the debtors account.  The status of the creditor's account is not known or guaranteed.Settlement on the debtor's account has been completed, but:
  • the inter-bank clearing and settlement process may not have completed and
  • the funds may not have been received in the creditor's account.

Notes

This is the state diagram for the payments-submission resource.


@startuml
skinparam monochrome true
hide empty description


[*] --> Pending

Pending -down-> AcceptedSettlementInProcess : [API call is valid]
AcceptedSettlementInProcess-right->Rejected : [Payment has failed and been rejected]
AcceptedSettlementInProcess-down->AcceptedSettlementComplete : [Final checks complete, money has left the debtor's account]

@enduml



POST /payment-submissions

Once the payment has been authorised by the Customer, the Third Party can proceed to submit the payment for processing:

GET /payment-submissions/{PaymentSubmissionId}

A Third Party can retrieve the payment-submission to check its status.

Notes

Data Model

This section gives detail on the payload content for the payment-submissions resource. 

Payment Submission - Request

The OBPaymentSubmission1 object will be used for a call to:

UML Diagram

Notes

The payment-submission request object contains the: 

The Initiation and Risk sections of the payment-submission request must match the Initiation and Risk sections of the corresponding payment setup request.

Data Dictionary


NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSubmission1
OBPaymentSubmission1
OBPaymentSubmission1

Data1..1OBPaymentSubmission1/Data
OBPaymentDataSubmission1

PaymentId1..1OBPaymentSubmission1/Data/PaymentIdUnique identification as assigned by the API Provider to uniquely identify the payment setup resource.Max128Text

Initiation1..1OBPaymentSubmission1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSubmission1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1


Payment Submission - Response

The OBPaymentSubmissionResponse1 object will be used for a response to a call to:

UML Diagram

Notes

The Payment Submission POST response contains the: 

Data Dictionary


NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSubmissionResponse1
OBPaymentSubmissionResponse1
OBPaymentSubmissionResponse1

Data1..1OBPaymentSubmissionResponse1/Data
OBPaymentDataSubmissionResponse1

PaymentSubmissionId1..1OBPaymentSubmissionResponse1/Data/PaymentSubmissionIdUnique identification as assigned by the API Provider to uniquely identify the payment submission resource.Max40Text

PaymentId1..1OBPaymentSubmissionResponse1/Data/PaymentIdUnique identification as assigned by the API Provider to uniquely identify the payment setup resource.Max128Text

Status1..1OBPaymentSubmissionResponse1/Data/StatusSpecifies the status of the payment submission resource.OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted
AcceptedSettlementInProcess
Pending
Rejected

CreationDateTime1..1OBPaymentSubmissionResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime

Initiation1..1OBPaymentSubmissionResponse1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSubmissionResponse1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1



Usage Examples

Merchant

This example set of flows and payload examples are for a payment initiated by a merchant via a Third Party.

In this scenario:

  • The merchant has not specified the Debtor Account details for the Customer - the Customer will select their account during the authorisation of consent
  • The merchant's account is a building society account - with a roll number specified in the SecondaryIdentification field

Sequence Diagram


participant "Customer" as Cx
participant "Merchant" as MER
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request payment initiation
end note
Cx -> MER: Check-out and pay
MER -> 3P: Send request to setup single immediate payment initiation
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments
APIProviderRS -> 3P: HTTP 201 (Created), PaymentId
3P -> MER: HTTP 302 (Found), Redirect (PaymentId)
MER -> Cx: HTTP 302 (Found), Redirect (PaymentId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (PaymentId)
Cx <-> APIProviderAS: authenticate
Cx <-> APIProviderAS: SCA if required
Cx <-> APIProviderAS: Select debtor account
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
3P -> Cx: HTTP 302 (Found), Redirect back to merchant
Cx -> MER: Follow redirect
MER --> 3P: Check payment status
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note over Cx, APIProviderRS
Step 5: Get payment submission status
end note
opt
MER -> 3P: Check payment status
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /payment-submissions/{PaymentSubmissionId}
APIProviderRS -> 3P: HTTP 200 (OK), payment-submissions resource
3P -> MER: HTTP 200 (OK), Return payment-submission Status
end opt


Illustrative Interactions

Notes:

  • As per the Security & Access Control section - examples are given where the call to GET may use either a client credentials grant or an authorization code grant to obtain a token to make GET requests.


POST /payments request


POST /payments HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{
	"Data": {
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	}
}

POST /payments response


HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentId": "58923",
		"Status": "AcceptedTechnicalValidation",
		"CreationDateTime": "2017-06-05T15:15:13+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/58923"
	},
	"Meta": {
		"TotalPages": 0
	}
}


POST /payment-submissions request


POST /payment-submissions HTTP/1.1
Authorization: Bearer Jhingapulaav
x-idempotency-key: FRESNO.1317.GFX.22
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
	"Data": {
		"PaymentId": "58923",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	}
}


POST /payment-submissions response


HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
	"Data": {
		"PaymentSubmissionId": "58923-001",
		"PaymentId": "58923",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/58923-001"
	},
	"Meta": {
		"TotalPages": 0
	}
}


GET /payments/{PaymentId} request


GET /payments/58923 HTTP/1.1
Authorization: Bearer Jhingapulaav
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


GET /payments/{PaymentId} response


HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentId": "58923",
		"Status": "AcceptedCustomerProfile",
		"CreationDateTime": "2017-06-05T15:15:13+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/58923"
	},
	"Meta": {
		"TotalPages": 0
	}
}


GET /payment-submissions/{PaymentSubmissionId} request


GET /payment-submissions/58923-001 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


GET /payment-submissions/{PaymentSubmissionId} response


HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
	"Data": {
		"PaymentSubmissionId": "58923-001",
		"PaymentId": "58923",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/58923-001"
	},
	"Meta": {
		"TotalPages": 0
	}
}


Person To Person

This example set of flows and payload examples are for a payment initiated by a person to another person via a Third Party.

In this scenario:

  • The Customer has pre-specified the account from which funds will be transferred (i.e., the Debtor Account details)
  • No building society accounts are involved in this interaction - so only the sort code and account number are specified in the DebtorAccount and CreditorAccount sections

Sequence Diagram


participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Servcer" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request payment initiation
end note
Cx <-> 3P: Initiate a funds transfer
Cx -> 3P: Select debtor and creditor accounts
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments
APIProviderRS -> 3P: HTTP 201 (Created), PaymentId
3P -> Cx: HTTP 302 (Found), Redirect (PaymentId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (PaymentId)
Cx <-> APIProviderAS: authenticate
Cx <-> APIProviderAS: SCA if required
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note over Cx, APIProviderRS
Step 5: Get payment submission status
end note
opt
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /payment-submissions/{PaymentSubmissionId}
APIProviderRS -> 3P: HTTP 200 (OK), payment-submissions resource
end opt


Illustrative Interactions

POST /payments request


POST /payments HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{
	"Data": {
		"Initiation": {
			"InstructionIdentification": "ANSM023",
			"EndToEndIdentification": "FRESCO.21302.GFX.37",
			"InstructedAmount": {
				"Amount": "20.00",
				"Currency": "NZD"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Andrea Smith"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "21-4321-7654321-12",
				"Name": "Bob Clements"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "PersonToPerson"
	}
}


POST /payment response


HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentId": "7290",
		"Status": "AcceptedTechnicalValidation",
		"CreationDateTime": "2017-06-05T15:15:13+00:00",
		"Initiation": {
			"InstructionIdentification": "ANSM023",
			"EndToEndIdentification": "FRESCO.21302.GFX.37",
			"InstructedAmount": {
				"Amount": "20.00",
				"Currency": "NZD"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Andrea Smith"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Bob Clements"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "PersonToPerson"
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/7290"
	},
	"Meta": {}
}


POST /payment-submissions request


POST /payment-submissions HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESNO.1317.GFX.22
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{
	"Data": {
		"PaymentId": "7290",
		"Initiation": {
			"InstructionIdentification": "ANSM023",
			"EndToEndIdentification": "FRESCO.21302.GFX.37",
			"InstructedAmount": {
				"Amount": "20.00",
				"Currency": "NZD"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Andrea Smith"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Bob Clements"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "PersonToPerson"
	}
}


POST /payment-submissions response


HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentSubmissionId": "7290-003",
		"PaymentId": "7290",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "02-0923-0044480-00",
				"Name": "Checking"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/7290-003"
	},
	"Meta": {}
}


GET /payments/{PaymentId} request


GET /payments/7290 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


GET /payments/{PaymentId} response


HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentId": "7290",
    "Status": "AcceptedCustomerProfile",
    "CreationDateTime": "2017-06-05T15:15:13+00:00",
    "Initiation": {
      "InstructionIdentification": "ACME412",
      "EndToEndIdentification": "FRESCO.21302.GFX.20",
      "InstructedAmount": {
        "Amount": "165.88",
        "Currency": "NZD"
      },
      "CreditorAccount": {
        "SchemeName": "BECSElectronicCredit",
        "Identification": "12-1234-1234567-12",
        "Name": "ACME Inc",
        "SecondaryIdentification": "0002"
      },
      "DebtorAccount": {
        "SchemeName": "BECSElectronicCredit",
        "Identification": "02-0923-0044480-00",
        "Name": "Checking"
      },
      "RemittanceInformation": {
        "Reference": {
          "CreditorName": "The Creditor",
          "CreditorReference": {
            "Particulars": "CreditorPart",
            "Code": "CreditorCode",
            "Reference": "CreditorRef"
          },
          "DebtorName": "The Debtor",
          "DebtorReference": {
            "Particulars": "DebtorPart",
            "Code": "DebtorCode",
            "Reference": "DebtorRef"
          }
        }
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PersonToPerson"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/58923"
  },
  "Meta": {}
}


GET /payment-submissions/{PaymentSubmissionId} request


GET /payment-submissions/7290-003 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json


GET /payment-submissions/{PaymentSubmissionId} response


HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentSubmissionId": "7290-003",
		"PaymentId": "7290",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "02-0923-0044480-00",
				"Name": "Checking"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/7290-003"
	},
	"Meta": {}
}


Alternative and Error Flows

Idempotent Payment Setup


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 single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments (x-idempotency-key={Third Party-guid-1})
APIProviderRS -> APIProviderRS: Create new resource (PaymentId=1001)
alt unexpected failure
3P -> APIProviderRS: POST /payments (x-idempotency-key={Third Party-guid-1})
note right of APIProviderRS
The resource server recognizes that
this is the same request as earlier.
A new resource is not created.
The payment id 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), PaymentId=1001
3P -> Cx: Redirect (PaymentId}

Idempotent Payment Submission

Payment Submission Conflict - Sequence Diagram


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 submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions PaymentId = 1001, x-idempotency-key={Third Party-guid-2}
alt Third Party attempts to POST to /payment-submissions with same PaymentId
3P -> APIProviderRS: POST /payment-submissions PaymentId = 1001, x-idempotency-key={Third Party-guid-2}
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note right of APIProviderRS
The resource server recognizes that this
is the same request as earlier.
A new resource is not created.
The PaymentSubmissionId remains the
same as above. The status of the resource
May be different if it has changed.

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


Swagger Specification

Use the below link to download the specifications from the Payments NZ API Centre GitHub repo:

https://github.com/PaymentsNZ/API-Payments-Initiation/tree/master/dist/v1.0.0