Domestic Payments v2.3.0
- 1 Version Control
- 2 Definition
- 3 Endpoints
- 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
- 5.1 Domestic Payment - Request
- 6 Usage Examples
- 6.1 Generic Flow
- 6.1.1 Sequence Diagram
- 6.1.2 Illustrative Interactions
- 6.2 Merchant
- 6.3 Person To Person
- 6.1 Generic Flow
Version Control
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:
|
2.2-draft1 | Oct 26, 2021 | @Gavin Wong (Unlicensed) | Removed:
|
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 |
---|---|---|---|---|---|---|---|---|
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 | NA | NZWriteDomesticResponse1 |
debtor-account | GET | GET /domestic-payments/{DomesticPaymentId}/debtor-account | Mandatory | payments | Client Credentials | NA | 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 | |
---|---|---|
1 | Pending | Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
|
2 | Rejected | Payment initiation or individual transaction included in the payment initiation has been rejected.
|
3 | AcceptedSettlementInProcess | All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
|
4 | AcceptedSettlementCompleted | Settlement on the debtor's account has been completed.
|
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.
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 |
---|---|---|---|---|---|
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 |
---|---|---|---|---|---|
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 |