1 Version Control
2 Definition
3 Endpoints
- 3.1 POST /domestic-payments
  - 3.1.1 Status
- 3.2 GET /domestic-payments/{DomesticPaymentId}
  - 3.2.1 Status
- 3.3 GET /domestic-payments/{DomesticPaymentId}/debtor-account
4 State Model
- 4.1 Diagram
- 4.2 Definitions
5 Data Model
- 5.1 Domestic Payment - Request
  - 5.1.1 UML Diagram
  - 5.1.2 Notes
  - 5.1.3 Data Dictionary
- 5.2 Domestic Payment - Response
  - 5.2.1 UML Diagram
  - 5.2.2 Notes
  - 5.2.3 Data Dictionary
- 5.3 Debtor Account - Response
  - 5.3.1 UML Diagram
  - 5.3.2 Notes
  - 5.3.3 Data Dictionary
6 Usage Examples
- 6.1 Generic Flow
  - 6.1.1 Sequence Diagram
  - 6.1.2 Illustrative Interactions
- 6.2 Merchant
  - 6.2.1 Illustrative Interactions
- 6.3 Person To Person
  - 6.3.1 Illustrative Interactions

Version Control

Version	Date	Author	Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020

@Gavin Wong (Unlicensed)

Updated:

Usage Example version from v2.0 to v2.1
Usage Example clarification that “The flow begins at step 4 of the 5 step Payment Initiation flow.” as per https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/139788339

Definition

The domestic-payments resource represents single, domestic, electronic credit payment-orders made in NZD that has been initiated by a Third Party on behalf of a Customer. A domestic-payment must be initiated using a payment-order consent which has been previously authorised by a Customer with an API Provider. This payment-order consent may either be a short-lived (domestic-payment-consent) or long-lived (enduring-payment-consent) payment-order consent.

The Status of a domestic-payment represents the status of the payment initiation with the API Provider.

Endpoints

Resource	HTTP Operation	End-point	Mandatory ?	Scope	Grant Type	Idempotency Key	Request Object	Response Object

Resource

HTTP Operation

End-point

Mandatory ?

Scope

Grant Type

Idempotency Key

Request Object

Response Object

domestic-payments

POST

POST /domestic-payments

Mandatory

payments

Redirect Flow; or

Decoupled Flow

Yes

NZWriteDomestic1

NZWriteDomesticResponse1

domestic-payments

GET

GET /domestic-payments/{DomesticPaymentId}

Mandatory

payments

Client Credentials

NA

NZWriteDomesticResponse1

debtor-account

GET

GET /domestic-payments/{DomesticPaymentId}/debtor-account

Mandatory

payments

Client Credentials

NA

OBReadAccount2

POST /domestic-payments

The API endpoint allows a Third Party with an authorised payment-order consent to initiate a domestic-payment for processing:

The Third Party does this with the POST /domestic-payments action.
The Third Party must have an access token issued by the API Provider using an authorisation flow (either redirect flow or decoupled flow). This access token must be issued using one of the following consent requests:
- domestic-payment-consent; or
- enduring-payment-consent
The POST /domestic-payments request is an instruction to the API Provider to begin the single electronic credit payment journey. The API Provider will attempt to initiated the domestic-payment immediately, however, there are some scenarios where the domestic-payment may not be initiated immediately (e.g., busy periods at the API Provider).
If the Third Party is using an authorisation flow from a domestic-payment-consent:
- The Third Party must ensure that the Initiation and Risk objects of the domestic-payment match the corresponding Consent and Risk sections of the domestic-payment-consent. If the two do not match, the API Provider must reject the domestic-payment.
If the Third Party is using an authorisation flow from an enduring-payment-consent:
- The Third Party must ensure that the Initiation object in the domestic-payment is within the Consent parameters for the enduring-payment-consent. If the domestic-payment is not within the Consent parameters of the enduring-payment-consent, the API Provider must reject the domestic-payment.

Status

The Status is Pending immediately after the domestic-payment has been created.

GET /domestic-payments/{DomesticPaymentId}

The API endpoint allows a Third Party to optionally retrieve the domestic-payment that they have created with an API Provider, to check its status.

The Third Party does this with the GET /domestic-payments/{DomesticPaymentId} action - where the DomesticPaymentId relates to the domestic-payment to be retrieved.
The Third Party must have an access token issued by the API Provider using a client credentials grant.

Status

The available status codes for a domestic-payment are:

Pending
Rejected
AcceptedSettlementInProcess
AcceptedSettlementCompleted

GET /domestic-payments/{DomesticPaymentId}/debtor-account

The API endpoint allows a Third Party to optionally retrieve the debtor account linked to the domestic-payment.

The Third Party does this with the GET /domestic-payments/{DomesticPaymentId}/debtor-account action - where the DomesticPaymentId relates to the domestic-payment to be retrieved.
The Third Party must have an access token issued by the API Provider using a client credentials grant.
The consent object linked to the domestic-payment must have a DebtorAccountRelease flag set to true

State Model

A domestic-payment may only be created if its corresponding consent has the status of Authorised.

The state model for a domestic-payment has this state model.

When the Third Party creates the domestic-payment with the API Provider - the Status of the domestic-payment will be set to Pending.
When the API Provider completes necessary validation and business checks, and the payment initiation has been accepted for execution, the Status of the domestic-payment will be set to AcceptedSettlementInProcess.
When the funds have left the debtor's account, the Status of the domestic-payment will be set to AcceptedSettlementCompleted.
If the API Provider rejects the domestic-payment or the domestic-payment has failed some other reason, the Status of the domestic-payment will be set to Rejected.

Diagram

This is the state diagram for the status of a domestic-payment.

Definitions

	Status	Status Description

	Status	Status Description
1	Pending	Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed. This is the initial state.
2	Rejected	Payment initiation or individual transaction included in the payment initiation has been rejected. This is a 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. This is an intermediate state. A payment in this state is generally expected to execute successfully; however may not be completed end-to-end in some scenarios. These scenarios may include: Fraud Bank failure The creditor account is closed/invalid/unable to receive credits Failure scenarios are best managed in the bilateral agreements between the Third Party and API Provider.
4	AcceptedSettlementCompleted	Settlement on the debtor's account has been completed. This is a terminal state. 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.

Data Model

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

Domestic Payment - Request

The NZWriteDomestic1 object will be used for a call to:

POST /domestic-payments

UML Diagram

Notes

The domestic-payment request object contains the:

Initiation object which contains the payment initiation details of the domestic-payment
ConsentId relating to the payment initiation. This consent must either be a domestic-payment-consent or an enduring-payment-consent.
- If the ConsentId relates to a domestic-payment-consent:
  - The Initiation and Risk objects of the domestic-payment request must match the Consent and Risk objects of the corresponding domestic-payment-consent.
- If the ConsentId relates to an enduring-payment-consent:
  - The Initiation object of the domestic-payment request must be within the parameters of the Consent object of the corresponding enduring-payment-consent.
  - The Risk object must be populated for the domestic-payment instance.
API Providers must reject a domestic-payment under these scenarios:
- If the DebtorAccount is not valid.
- If the SchemeName is not valid.
- If the Currency is not supported.
- If the Particulars, Code or Reference fields in either DebtorReference or CreditorReference objects contain invalid characters.
- If the DebtorReference is specified when the DebtorAccount is not specified.
API Providers may reject a domestic-payment depending on their own implementations:
- If the CreditorAccount is not valid.

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes

Name	Occurrence	XPath	EnhancedDefinition	Class
NZWriteDomestic1		NZWriteDomestic1	NZWriteDomestic1
Data	1..1	NZWriteDomestic1/Data	NZWriteDataDomestic1
ConsentId	1..1	NZWriteDomestic1/Data/ConsentId	Unique identification as assigned by the API Provider to uniquely identify the consent.	Max128Text
Initiation	1..1	NZWriteDomestic1/Data/Initiation	The Consent payload is sent by the Third Party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.	NZDomesticConsent1
Risk	1..1	NZWriteDomestic1/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

Domestic Payment - Response

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

POST /domestic-payments
GET /domestic-payments/{DomesticPaymentId}

UML Diagram

Notes

The domestic-payment response object contains the:

DomesticPaymentId
ConsentId
Date time the domestic-payment was created
Status of the domestic-payment
Status update date time of the domestic-payment
The full payload from the domestic-payment request (including the Initiation and Risk sections)

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
NZWriteDomesticResponse1		NZWriteDomesticResponse1	NZWriteDomesticResponse1
Data	1..1	NZWriteDomesticResponse1/Data	NZWriteDataDomesticResponse1
DomesticPaymentId	1..1	NZWriteDomesticResponse1/Data/DomesticPaymentId	Unique identification as assigned by the API Provider to uniquely identify the domestic payment.	Max40Text
ConsentId	1..1	NZWriteDomesticResponse1/Data/ConsentId	Unique identification as assigned by the API Provider to uniquely identify the consent.	Max128Text
CreationDateTime	1..1	NZWriteDomesticResponse1/Data/CreationDateTime	Date and time at which the domestic payment was created.	ISODateTime
Status	1..1	NZWriteDomesticResponse1/Data/Status	Specifies the status of the payment information group.	OBTransactionIndividualStatus1Code	AcceptedSettlementCompleted AcceptedSettlementInProcess Pending Rejected
StatusUpdateDateTime	1..1	NZWriteDomesticResponse1/Data/StatusUpdateDateTime	Date and time at which the domestic payment status was updated.	ISODateTime
Initiation	1..1	NZWriteDomesticResponse1/Data/Initiation	The Consent payload is sent by the Third Party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.	NZDomesticConsent1
Risk	1..1	NZWriteDomesticResponse1/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

Debtor Account - Response

The NZWriteDomesticAccountResponse1 object will be used for a call to:

GET /domestic-payments/{DomesticPaymentId}/debtor-account

UML Diagram

Notes

The NZWriteDomesticAccountResponse1 response object contains the DebtorAccount that is linked to the domestic-payment
As such, the DebtorAccount details are immutable

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
NZWriteDomesticAccountResponse1		NZWriteDomesticAccountResponse1	NZWriteDomesticAccountResponse1
Data	1..1	NZWriteDomesticAccountResponse1/Data	NZWriteDataDomesticAccountResponse1
DebtorAccount	1..1	NZWriteDomesticAccountResponse1/Data/DebtorAccount	Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.	OBCashAccountDebtor1
SchemeName	1..1	NZWriteDomesticAccountResponse1/Data/DebtorAccount/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification2Code	BECSElectronicCredit
Identification	1..1	NZWriteDomesticAccountResponse1/Data/DebtorAccount/Identification	Identification 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
Name	0..1	NZWriteDomesticAccountResponse1/Data/DebtorAccount/Name	Name 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
SecondaryIdentification	0..1	NZWriteDomesticAccountResponse1/Data/DebtorAccount/SecondaryIdentification	This is secondary identification of the account, as assigned by the account servicing institution.	Max34Text

Usage Examples

Generic Flow

This example flows and payload examples are for a Third Party staging a domestic-payment-consent with an API Provider on behalf of a Customer.

The flow begins at step 4 of the 5 step Payment Initiation flow.

Sequence Diagram

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

note over Customer, API Provider Resource Server
Step 4: Create Domestic Payment
end note
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: POST /domestic-payments
note over API Provider Resource Server: Consent Status: Consumed
note over API Provider Resource Server: Payment Status: Pending
note over API Provider Resource Server: Payment Status: AcceptedSettlementInProcess
note over API Provider Resource Server: Payment Status: AcceptedSettlementCompleted
API Provider Resource Server -> Third Party: HTTP 201 (Created), DomesticPaymentId

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

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

opt debtor-account
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: GET /domestic-payments/{DomesticPaymentId}/debtor-account
API Provider Resource Server -> Third Party: HTTP 200 (OK) debtor-account resource
end opt

Illustrative Interactions

Create Domestic Payment

Request

POST /domestic-payments HTTP/1.1
Authorization: Bearer Jhingapulaav
x-idempotency-key: FRESNO.1317.GFX.22
x-fapi-auth-date: 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": {
		"ConsentId": "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": {
            "AddressType": "DeliveryTo",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
	}
}

Response

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

{
	"Data": {
		"DomesticPaymentId": "58923-001",
		"ConsentId": "58923",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"Status": "AcceptedSettlementInProcess",
		"StatusUpdateDateTime": "2019-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": {
            "AddressType": "DeliveryTo",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v2.1/domestic-payments/58923-001"
	},
	"Meta": {
		"TotalPages": 0
	}
}

Retrieve Domestic Payment

Request

Response

Retrieve Account

Request

Response

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

Illustrative Interactions

Create Domestic Payment

Request

Response

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