Domestic Payments - v2.1.0

Owned by Matthew Bell
Dec 01, 2020
12 min read

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:

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.

    • 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

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

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

Illustrative Interactions

Create Domestic Payment

Request
Response