Version Control

Version	Date	Author	Comments
1.0.0	01 March 2019	Payments 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:

Register an intent to setup a payment instruction
Subsequently submit the payment instruction for processing
Optionally retrieve the status of a payment setup or submission.

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

Document Structure

This document consists of the following parts:

Overview: Provides an overview of the scope of the API and the key decisions that contributed to the specification.

Basics: The section identifies the resources, operations that are permitted on those resources, and various special cases.

Endpoints: Provides the list of endpoints for the API specification. The individual end-points are documented in separate sections along with the data model that they employ.

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

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

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

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

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

Scope

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

Out of Scope

This specification does not cater for:

Payments that involve currency exchange.
Payments that involve currencies other than NZD
Payments that are not single, domestic, electronic credit payments made in NZD - i.e., payments that are:
- In bulk - single debit, multiple credit
- Future dated or deferred
- Recurring.
Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are not included in this version.
Non-functional requirements and specification of caching and throttling.

...

ISO 20022

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

Deviations from the pain.001 XML standard are:

The pain.001 header section and trailer sections have been removed - as these are not required for a RESTful API
Only fields required for the v1.0 scope of single-debit single-credit NZD payments, immediately executed are included in the payload. This has meant:
- The separate CreditTransferTransactionInformation section in pain.001 - which is a repeating group for multi-credit payments has been removed and flattened
- PaymentInformationIdentification not required - we also have a InstructionIdentification
- PaymentMethod not required - as this is always immediate execution for the API Provider
- RequestedExecutionDate not required - as this is always as soon as possible - which may differ between FPS and Bacs payments
- Debtor / DebtorAccount are optional - as the debtor details are not always known to the Third Party submitting the payment setup or submit
The Payment Initiation team has requested a flatter structure for the payload:
- InstructionIdentification and EndToEndIdentification moved to the top level (instead of embedding within PaymentIdentification)
- CreditorAgent is simplified to only include the SchemeName and Identification
- DebtorAccount and CreditorAccount are simplified to only include the SchemeName and Identification

Transaction Status

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

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

Expand

title	Click here to expand source for state diagram...

@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 Class	Name	Definition
ExternalPaymentContext1Code	BillPayment	The context of the payment initiation is a bill payment.
ExternalPaymentContext1Code	EcommerceGoods	The context of the payment initiation is for goods via an ecommerce channel.
ExternalPaymentContext1Code	EcommerceServices	The context of the payment initiation is for services via an ecommerce channel.
ExternalPaymentContext1Code	PartyToParty	The context of the payment initiation is a party to party payment.
ExternalPaymentContext1Code	Other	The context of the payment initiation is of an other type.
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.
OBExternalFinancialInstitutionIdentification2Code	BICFI	Valid 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.
OBTransactionIndividualStatus1Code	AcceptedCustomerProfile	Preceding check of technical validation was successful. Customer profile check was also successful.
OBTransactionIndividualStatus1Code	AcceptedSettlementCompleted	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.
OBTransactionIndividualStatus1Code	AcceptedSettlementInProcess	All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
OBTransactionIndividualStatus1Code	AcceptedTechnicalValidation	Authentication and syntactical and semantic validation are successful.
OBTransactionIndividualStatus1Code	Pending	Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
OBTransactionIndividualStatus1Code	Rejected	Payment 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 Type	Fields	ISO Enumerations Values URL
Min3Max4Text	MerchantCategoryCode	https://www.iso.org/standard/33365.html
ActiveOrHistoricCurrencyCode	Currency	https://www.iso20022.org/external_code_list.page
CountryCode	Currency	https://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

The DebtorAccount and DebtorReference are optional - as the Third Party may not know the account identification details for the Customer.
If the DebtorAccount is specified by the Third Party - then the account identification details of the Payment resource cannot be changed - as this is part of formal consent from the Customer.
If the DebtorAccount is not valid - then the payment will be rejected.
If the DebtorAccount is not specified by the Third Party - then the DebtorReference must not be specified, doing so will result in the payment being rejected.
If the DebtorReference is specified by the Third Party - then it cannot be changed - as this is part of formal consent from the Customer.
SchemeName for PNZ is "BECSElectronicCredit"
Where "BECSElectronicCredit" is specified as the SchemeName in the Account identification section, the Servicer section must not be populated and the identification field must be populated with a structured bank account number 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.
If a Third Party request contains an unsupported account SchemeName, API Provider must return a status code of 400 (Bad Request)
If a Third Party request contains an unsupported currency, API Provider must return a status code of 400 (Bad Request)
The PNZ API specification includes a specific RemittanceInformation model, called BECSRemittance, which redefines the RemittanceInformation structure for the PaymentSetup object.
DebtorReference and CreditorReference - the Particulars, Code and Reference fields are currently constrained to 12 characters. The design choice has been made not to constrain through schema restrictions, to allow for future changes that remove the constraint. Note that not all banks will accept all valid characters. Constraining to a-z, A-Z, - (dash) and 0-9 is advised. One example is abc-XYZ-123.
Where the DebtorReference or CreditorReference Particulars, Code and Reference fields contain invalid characters, the API Provider must return a descriptive 400 (Bad Request).
As a merchant may be initiating a payment via a Third Party - two identifiers are included in the payload:
- InstructionIdentification is uniquely generated by the Third Party - 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.
- EndToEndIdentification is uniquely generated by the merchant.
Neither the InstructionIdentification nor EndToEndIdentification will be used as the payment resource identifier (PaymentId) - as the PaymentId must be uniquely generated by the API Provider.
Design decisions for the Initiation section of the payload - and how this maps to the ISO 20022 messaging standard are articulated in the Mapping to Schemes and Standards section.

...

Payments

Resource	End-point	Mandatory ?	Scope	Grant Type	Idempotent	Request Object	Response Object
payments	POST /payments	Mandatory	third_party_client_credential	Client Credentials	Yes	OBPaymentSetup1	OBPaymentSetupResponse1
payments	GET /payments/{PaymentId}	Mandatory	third_party_client_credential	Client Credentials	NA	NA	OBPaymentSetupResponse1

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.

Expand

title	Click here to expand state diagram source...

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

The POST indicates to the API Provider that a payment should be initiated. At this stage, the Customer may not have been identified by the API Provider, and the request payload may not contain any information of the account that should be debited.
This API effectively allows the Third Party to send a copy of the consent (between the Customer and the Third Party) to the API Provider for the Customer to authorise.
The API Provider creates the payments resource and responds with a unique PaymentId to refer to the resource.
Note: The payments resource is only valid for 24 hours if not authorised by the Customer.

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:

POST /payments

UML Diagram

Notes

The Payment Setup request contains these objects:

Initiation
Risk

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class
OBPaymentSetup1		OBPaymentSetup1		OBPaymentSetup1
Data	1..1	OBPaymentSetup1/Data		OBPaymentDataSetup1
Initiation	1..1	OBPaymentSetup1/Data/Initiation	The 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
Risk	1..1	OBPaymentSetup1/Risk	The 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:

POST /payments
GET /payments/{PaymentId}

UML Diagram

Notes

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

PaymentId.
Status of the payment resource.
Date time the payment resource was created.

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBPaymentSetupResponse1		OBPaymentSetupResponse1		OBPaymentSetupResponse1
Data	1..1	OBPaymentSetupResponse1/Data		OBPaymentDataSetupResponse1
PaymentId	1..1	OBPaymentSetupResponse1/Data/PaymentId	Unique identification as assigned by the API Provider to uniquely identify the payment setup resource.	Max128Text
Status	1..1	OBPaymentSetupResponse1/Data/Status	Specifies the status of the payment resource.	OBTransactionIndividualStatus1Code	AcceptedCustomerProfile AcceptedTechnicalValidation Pending Rejected
CreationDateTime	1..1	OBPaymentSetupResponse1/Data/CreationDateTime	Date and time at which the resource was created.	ISODateTime
Initiation	1..1	OBPaymentSetupResponse1/Data/Initiation	The 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
Risk	1..1	OBPaymentSetupResponse1/Risk	The 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:

	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 State.
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. insufficient funds.
3	AcceptedSettlementInProcess	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:

	Status	Payment Status Description	NZ Status Clarification
4	AcceptedSettlementCompleted	Settlement 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

In very rare circumstances, a payment submission with a status of AcceptedSettlementCompleted may not be completed end-to-end. These scenarios include:
- Fraud
- Bank failure
- The creditor account is closed/invalid/unable to receive credits
These scenarios are best managed in the bilateral agreements between the Third Party and API Provider.

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

Expand

title	Click here to expand state diagram source...

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

This is done by making a POST request to the payment-submissions resource.
This request is an instruction to the API Provider to begin the single electronic credit payment journey. The payment will be submitted immediately, however, there are some scenarios where the payment may not happen immediately (e.g. busy periods at the API Provider or the payment requires settlement with another Bank).
The Third Party must ensure that the Initiation and Risk sections of the payment submission match the corresponding Initiation and Risk sections of the original payment resource. If the two do not match, the API Provider must not process the request and must respond with a 400 (Bad Request).
Any operations on the payment-submission resource will not result in a Status change for the payment resource.

GET /payment-submissions/{PaymentSubmissionId}

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

Notes

In very rare circumstances, a payment submission with a status of AcceptedSettlementCompleted may not be completed end-to-end. These scenarios include:
- Fraud
- Bank failure
- The creditor account is closed/invalid/unable to receive credits
These scenarios are best managed in the bilateral agreements between the Third Party and API Provider.

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:

POST /payment-submissions

UML Diagram

Notes

The payment-submission request object contains the:

PaymentId
The full payload from the payment setup request (including the Initiation and Risk sections)

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

Name	Occurrence	XPath	EnhancedDefinition	Class
OBPaymentSubmission1		OBPaymentSubmission1		OBPaymentSubmission1
Data	1..1	OBPaymentSubmission1/Data		OBPaymentDataSubmission1
PaymentId	1..1	OBPaymentSubmission1/Data/PaymentId	Unique identification as assigned by the API Provider to uniquely identify the payment setup resource.	Max128Text
Initiation	1..1	OBPaymentSubmission1/Data/Initiation	The 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
Risk	1..1	OBPaymentSubmission1/Risk	The 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:

POST /payment-submissions
GET /payment-submissions/{PaymentSubmissionId}

UML Diagram

Notes

The Payment Submission POST response contains the:

PaymentSubmissionId
PaymentId
Status of the payment-submission resource
Date time the payment-submission resource was created
The full payload from the PaymentSubmission request (including the Initiation and Risk sections)

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBPaymentSubmissionResponse1		OBPaymentSubmissionResponse1		OBPaymentSubmissionResponse1
Data	1..1	OBPaymentSubmissionResponse1/Data		OBPaymentDataSubmissionResponse1
PaymentSubmissionId	1..1	OBPaymentSubmissionResponse1/Data/PaymentSubmissionId	Unique identification as assigned by the API Provider to uniquely identify the payment submission resource.	Max40Text
PaymentId	1..1	OBPaymentSubmissionResponse1/Data/PaymentId	Unique identification as assigned by the API Provider to uniquely identify the payment setup resource.	Max128Text
Status	1..1	OBPaymentSubmissionResponse1/Data/Status	Specifies the status of the payment submission resource.	OBTransactionIndividualStatus1Code	AcceptedSettlementCompleted AcceptedSettlementInProcess Pending Rejected
CreationDateTime	1..1	OBPaymentSubmissionResponse1/Data/CreationDateTime	Date and time at which the resource was created.	ISODateTime
Initiation	1..1	OBPaymentSubmissionResponse1/Data/Initiation	The 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
Risk	1..1	OBPaymentSubmissionResponse1/Risk	The 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

Expand

title	Click here to expand UML source...

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

Code Block

language	js
theme	Midnight
linenumbers	true

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

Code Block

language	js
theme	Midnight
linenumbers	true

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

Code Block

language	js
theme	Midnight
linenumbers	true

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

Code Block

language	js
theme	Midnight
linenumbers	true

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

...

Code Block

language	js
theme	Midnight
linenumbers	true

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

Code Block

language	js
theme	Midnight
linenumbers	true

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

Code Block

language	js
theme	Midnight
linenumbers	true

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

Expand

title	Click here to expand UML source...

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

Code Block

language	js
theme	Midnight
title	POST payments REQUEST
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	POST payments RESPONSE
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	POST payment-submissions REQUEST
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	POST payment-submissions RESPONSE
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	GET payments REQUEST
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	GET payments Response
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	GET payment-submissions REQUEST
linenumbers	true

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

Code Block

language	js
theme	Midnight
title	GET payment-submissions RESPONSE
linenumbers	true

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

Expand

title	Click here to expand UML diagram source...

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

Expand

title	Click here to expand UML diagram source...

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 and access the raw YAML swagger specifications :

YAML

in .txt format.

payment-initiation-nz-swagger.txt

Page Comparison

Versions Compared

Old Version 5

New Version 6

Key

Contents

Version Control

Document Structure

Scope

Out of Scope

ISO 20022

Transaction Status

Enumerations

Common Enumerations

ISO Enumerations

Data Model

Reused Classes

OBInitiation1

UML Diagram

Notes

Payments

Payment Status

POST /payments

GET /payments/{PaymentId}

Data Model

Payment Setup - Request

UML Diagram

Notes

Data Dictionary

Payment Setup - Response

UML Diagram

Notes

Data Dictionary

Payment Submissions

Payment Submission Status

Notes

POST /payment-submissions

GET /payment-submissions/{PaymentSubmissionId}

Notes

Data Model

Payment Submission - Request

UML Diagram

Notes

Data Dictionary

Payment Submission - Response

UML Diagram

Notes

Data Dictionary

Usage Examples

Merchant

Sequence Diagram

Illustrative Interactions

POST /payments request

POST /payments response

POST /payment-submissions request

POST /payment-submissions response

GET /payments/{PaymentId} request

GET /payment-submissions/{PaymentSubmissionId} request

GET /payment-submissions/{PaymentSubmissionId} response

Person To Person

Sequence Diagram

Illustrative Interactions

POST /payments request

POST /payment response

POST /payment-submissions request

POST /payment-submissions response

GET /payments/{PaymentId} request

GET /payments/{PaymentId} response

GET /payment-submissions/{PaymentSubmissionId} request

GET /payment-submissions/{PaymentSubmissionId} response

Alternative and Error Flows

Idempotent Payment Setup

Idempotent Payment Submission

Swagger Specification