Domestic Payments v2.3.0

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:

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

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

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.

  • 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

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

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