Version Control

Version

Date

Author

Comments

2.0.0

30 Apr 2020

Payments NZ API Working Group

Baseline

2.1-draft1

15 Jun 2020

Gavin Wong (Unlicensed)

Updated:

Usage Example version from v2.0 to v2.1

Definition

The domestic-payment-consents resource represents short lived payment-order consents that have been agreed between the Customer and the Third Party, and contains fields which describe the parameters for a single domestic-payment that may be initiated by a Third Party on behalf of a Customer.

The Status of a domestic-payment-consent represents the authentication and authorisation stage with the API Provider.

Endpoints

Resource	HTTP Operation	End-point	Mandatory ?	Scope	Grant Type	Idempotency Key	Request Object	Response Object
domestic-payment-consents	POST	POST /domestic-payment-consents	Mandatory	payments	Client Credentials	Yes	NZWriteDomesticConsent1	NZWriteDomesticConsentResponse1
domestic-payment-consents	GET	GET /domestic-payment-consents/{ConsentId}	Mandatory	payments	Client Credentials	NA	NA	NZWriteDomesticConsentResponse1

POST /domestic-payment-consents

The API endpoint allows a Third Party to ask an API Provider to create a new domestic-payment-consent.

The Third Party does this with the POST /domestic-payment-consents action.
The Third Party must have an access token issued by the API Provider using a client credentials grant.
The API endpoint allows the Third Party to send a copy of the consent (between Customer and Third Party) to the API Provider.
The API Provider creates the domestic-payment-consent and responds with a unique ConsentId to refer to the consent.
At the point the consent is created, the consent has not been authorised.
The domestic-payment-consent is only valid for 24 hours if not authorised by the Customer.

Flow

The Third Party uses the ConsentId to initiate an authorisation flow (as described in the Security Profile).

As part of the authorisation flow:

The API Provider authenticates the Customer.
The API Provider plays back the consent (registered by the Third Party) back to the Customer - to get consent authorisation. The Customer may accept or reject the consent in its entirety (but not selectively).
If the domestic-payment-consent does not indicate a debtor account, the API Provider presents the Customer a list of accounts from which the Customer must select one.

Once these steps are complete, the consent is considered to have been authorised by the Customer and the Status is updated to Authorised.

Status

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

GET /domestic-payment-consents/{ConsentId}

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

The Third Party does this with the GET /domestic-payment-consents/{ConsentId} action - where the ConsentId relates to the domestic-payment-consent 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-consent are:

AwaitingAuthorisation
Rejected
Authorised
Consumed

State Model

The state model for a domestic-payment-consent follows a short lived consent state model.

When the Third Party creates the payment-order consent with the API Provider, the Status of the payment-order consent will be set to AwaitingAuthorisation.
When the Customer authorises the payment-order consent with the API Provider, the Status of the payment-order consent will be updated with Authorised.
If the Customer rejects the consent or the payment-order consent has failed some other API Provider validation, the Status of the payment-order consent will be set to Rejected.
If the Third Party uses a payment-order consent in an Authorised Status to create a payment-order, the Status of the payment-order consent used will be set to Consumed.

Diagram

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

Definitions

	Status	Status Description
1	AwaitingAuthorisation	The consent resource is awaiting Customer authorisation. This is an initial state.
2	Rejected	The consent resource has been rejected. This is a terminal state. Does not distinguish between failure reasons - e.g. authorisation failed or bank rejected.
3	Authorised	The consent resource has been successfully authorised. This is an intermediate state.
4	Consumed	The consented action has been successfully completed. This does not reflect the status of the consented action. This is a terminal state.

Data Model

Reused Classes

NZDomesticConsent1

This section describes the NZDomesticConsent1 class - which is reused as the Consent object in the domestic-payment-consents and domestic-payments resources.

UML Diagram

Notes

In a domestic-payment-consent payload:
- If the API Provider establishes a rejection scenario with payload or any contextual error during the API call, the API Provider must reject the request immediately with a 400 (Bad Request).
- If the API Provider establishes a rejection scenario with the consent after the API call, the API Provider must set the Status of the consent to Rejected.
- 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.
- The InstructionIdentification or EndToEndIdentification must not be used as the domestic-payment-consent identifier (ConsentId) - as the ConsentId must be uniquely generated by the API Provider.
- The NZ Banking Data Account identification SchemeName is "BECSElectronicCredit".
- Where "BECSElectronicCredit" is specified as the SchemeName in the Account identification section, 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.
- The DebtorAccount and DebtorReference are optional - as the Third Party may not know the account identification details for the Customer.
- If the DebtorAccount is not specified in the payload, the Customer must select a valid DebtorAccount during the authentication flow with the API Provider.
- If the DebtorAccount is specified by the Third Party - then the account identification details in the Consent object cannot be changed - as this is part of formal consent from the Customer.
- If the DebtorReference is specified by the Third Party - then it cannot be changed - as this is part of formal consent from the Customer.
- 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.
- The DebtorAccountRelease flag is optional - if set to true it indicates that the Customer has consented to releasing their debtor account details
- API Providers must reject a domestic-payment-consent 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-consent depending on their own implementations:
  - If the CreditorAccount is not valid.
A payment-order initiated using a domestic-payment-consent:
- must be a domestic-payment.
- must have Consent and Risk objects that match the Consent and Risk objects of the corresponding domestic-payment-consent.

Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class	Codes
NZDomesticConsent1		NZDomesticConsent1	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
InstructionIdentification	1..1	NZDomesticConsent1/InstructionIdentification	Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. Usage: the instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. OBNZ: Updated to allow 36 characters to allow for v4 UUID	Max36Text
EndToEndIdentification	1..1	NZDomesticConsent1/EndToEndIdentification	Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. OBNZ: Updated to allow 36 characters to allow for v4 UUID	Max36Text
DebtorAccountRelease	0..1	NZDomesticConsent1/DebtorAccountRelease	Flags whether the Customer has consented with the Third Party to release their debtor account information.	xs:boolean
InstructedAmount	1..1	NZDomesticConsent1/InstructedAmount	Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain.	OBActiveOrHistoricCurrencyAndAmount
Amount	1..1	NZDomesticConsent1/InstructedAmount/Amount	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	ActiveCurrencyAndAmount_SimpleType	^\d{1,13}\.\d{1,5}$
Currency	1..1	NZDomesticConsent1/InstructedAmount/Currency	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode	^[A-Z]{3,3}$
DebtorAccount	0..1	NZDomesticConsent1/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	NZDomesticConsent1/DebtorAccount/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification2Code	BECSElectronicCredit
Identification	1..1	NZDomesticConsent1/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	NZDomesticConsent1/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	NZDomesticConsent1/DebtorAccount/SecondaryIdentification	This is secondary identification of the account, as assigned by the account servicing institution.	Max34Text
CreditorAgent	0..1	NZDomesticConsent1/CreditorAgent	Financial institution servicing an account for the creditor.	OBBranchAndFinancialInstitutionIdentification2
SchemeName	1..1	NZDomesticConsent1/CreditorAgent/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalFinancialInstitutionIdentification2Code	BICFI
Identification	1..1	NZDomesticConsent1/CreditorAgent/Identification	Unique and unambiguous identification of a financial institution or a branch of a financial institution.	Max35Text
CreditorAccount	1..1	NZDomesticConsent1/CreditorAccount	Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.	OBCashAccountCreditor1
SchemeName	1..1	NZDomesticConsent1/CreditorAccount/SchemeName	Name of the identification scheme, in a coded form as published in an external list.	OBExternalAccountIdentification2Code	BECSElectronicCredit
Identification	1..1	NZDomesticConsent1/CreditorAccount/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	1..1	NZDomesticConsent1/CreditorAccount/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. API Providers may carry out name validation for Confirmation of Payee, but it is not mandatory.	Max70Text
SecondaryIdentification	0..1	NZDomesticConsent1/CreditorAccount/SecondaryIdentification	This is secondary identification of the account, as assigned by the account servicing institution.	Max34Text
RemittanceInformation	1..1	NZDomesticConsent1/RemittanceInformation	Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZRemittanceInformation1
Reference	0..1	NZDomesticConsent1/RemittanceInformation/Reference	Remittance information for use with BECSElectronicCredit payment scheme.	NZBECSRemittance1
CreditorName	1..1	NZDomesticConsent1/RemittanceInformation/Reference/CreditorName	The Creditor's Name.	Max20Text
DebtorName	0..1	NZDomesticConsent1/RemittanceInformation/Reference/DebtorName	The Debtor's Name.	Max20Text
CreditorReference	0..1	NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference	Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZBECSReference1
Particulars	0..1	NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference/Particulars	Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.	Max12Text
Code	0..1	NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference/Code	Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.	Max12Text
Reference	0..1	NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference/Reference	Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.	Max12Text
DebtorReference	0..1	NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference	Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.	NZBECSReference1
Particulars	0..1	NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference/Particulars	Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.	Max12Text
Code	0..1	NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference/Code	Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.	Max12Text
Reference	0..1	NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference/Reference	Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.	Max12Text

Domestic Payment Consent - Request

The NZWriteDomesticConsent1 object will be used for the call to:

POST /domestic-payment-consents

UML Diagram

Notes

The domestic-payment-consent request contains these objects:

Consent
Risk

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class
NZWriteDomesticConsent1		NZWriteDomesticConsent1		NZWriteDomesticConsent1
Data	1..1	NZWriteDomesticConsent1/Data		NZWriteDataDomesticConsent1
Consent	1..1	NZWriteDomesticConsent1/Data/Consent	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	NZWriteDomesticConsent1/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 Consent - Response

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

POST /domestic-payment-consents
GET /domestic-payment-consents/{ConsentId}

UML Diagram

Notes

The domestic-payment-consent response contains the full original payload from the domestic-payment-consent request - with these additional elements:

ConsentId
Date time the domestic-payment-consent was created
Status of the domestic-payment-consent
Status update date time of the domestic-payment-consent

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
NZWriteDomesticConsentResponse1		NZWriteDomesticConsentResponse1	NZWriteDomesticConsentResponse1
Data	1..1	NZWriteDomesticConsentResponse1/Data	NZWriteDataDomesticConsentResponse1
ConsentId	1..1	NZWriteDomesticConsentResponse1/Data/ConsentId	Unique identification as assigned by the API Provider to uniquely identify the consent.	Max128Text
CreationDateTime	1..1	NZWriteDomesticConsentResponse1/Data/CreationDateTime	Date and time at which the consent was created.	ISODateTime
Status	1..1	NZWriteDomesticConsentResponse1/Data/Status	Specifies the status of consent in code form.	OBExternalConsentStatus1Code	Authorised AwaitingAuthorisation Consumed Rejected
StatusUpdateDateTime	1..1	NZWriteDomesticConsentResponse1/Data/StatusUpdateDateTime	Date and time at which the consent status was updated.	ISODateTime
Consent	1..1	NZWriteDomesticConsentResponse1/Data/Consent	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	NZWriteDomesticConsentResponse1/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

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.

Sequence Diagram

Click here to expand UML diagram source...

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

note over Customer, API Provider Resource Server
Step 1: Agree Domestic Payment Consent
end note
Customer -> Third Party: Agree domestic payment consent

note over Customer, API Provider Resource Server
Step 2: Create Domestic Payment Consent
end note
Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA
Third Party -> API Provider Authorisation Server: Initiate Client Credentials Grant
API Provider Authorisation Server -> Third Party: Return access-token
Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA
Third Party -> API Provider Resource Server: POST /domestic-payment-consents
note over API Provider Resource Server: Consent Status: AwaitingAuthorisation
API Provider Resource Server -> Third Party: HTTP 201 (Created), ConsentId

note over Customer, API Provider Resource Server
Step 3: Authorise Consent
end note
alt Redirection (Using authorization code grant)
Third Party -> Customer: HTTP 302 (Found), Redirect (ConsentId)
Customer -> API Provider Authorisation Server: Follow redirect (ConsentId)
Customer <-> API Provider Authorisation Server: Authenticate
Customer <-> API Provider Authorisation Server: Select debtor account if required
Customer <-> API Provider Authorisation Server: Authorise consent
note over API Provider Resource Server: Consent Status: Authorised
API Provider Authorisation Server -> Customer: HTTP 302 (Found), Redirect (authorization-code)
Customer -> Third Party: Follow redirect (authorization-code)
Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA
Third Party -> API Provider Authorisation Server: Exchange authorization-code for access token
API Provider Authorisation Server -> Third Party: Return access-token
else Decoupled (Using CIBA)
Third Party -> API Provider Authorisation Server: POST /bc-authorize (login_hint_token)
API Provider Authorisation Server -> Third Party: OK

Customer -> API Provider Authorisation Server: Authorise (Consent Id)
Customer <-> API Provider Authorisation Server: Authenticate
Customer <-> API Provider Authorisation Server: Select debtor accounts if required
Customer <-> API Provider Authorisation Server: Authorise consent
note over API Provider Resource Server: Consent Status: Authorised

alt Using callback
API Provider Authorisation Server -> Third Party: Callback (authorization-code)
Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA
Third Party -> API Provider Authorisation Server: Exchange authorization-code for access token
API Provider Authorisation Server -> Third Party: Return access-token
else Using polling
Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA
Third Party -> API Provider Authorisation Server: Poll at /token using auth-req-id
API Provider Authorisation Server -> Third Party: Return access-token
end alt
end alt

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

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

Illustrative Interactions

Create Domestic Payment Consent

Request

POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
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": {
        "Consent": {
            "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": {
        "ConsentId": "58923",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:15:13+00:00",
        "Consent": {
            "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-payment-consents/58923"
    },
    "Meta": {
        "TotalPages": 1
    }
}

Retrieve Domestic Payment Consent

Request

GET /domestic-payment-consents/58923 HTTP/1.1
Authorization: Bearer Jhingapulaav
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
Accept: application/json

Response

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

{
    "Data": {
        "ConsentId": "58923",
        "Status": "Authorised",
        "CreationDateTime": "2017-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:20:13+00:00",
        "Consent": {
            "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-payment-consents/58923"
    },
    "Meta": {
        "TotalPages": 0
    }
}

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 Consent

Request

POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
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": {
        "Consent": {
            "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": {
        "ConsentId": "58923",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:15:13+00:00",
        "Consent": {
            "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-payment-consents/58923"
    },
    "Meta": {
        "TotalPages": 1
    }
}

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 Consent

Request

POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
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": {
        "Consent": {
            "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"
    }
}

Response

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
  
{
    "Data": {
        "ConsentId": "7290",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:15:13+00:00",
        "Consent": {
            "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/v2.1/domestic-payment-consents/7290"
    },
    "Meta": {}
}

Domestic Payment Consents - v2.2.0

Version Control

Definition

Endpoints

POST /domestic-payment-consents

Flow

Status

GET /domestic-payment-consents/{ConsentId}

Status

State Model

Diagram

Definitions

Data Model

Reused Classes

NZDomesticConsent1

UML Diagram

Notes

Data Dictionary

Domestic Payment Consent - Request

UML Diagram

Notes

Data Dictionary

Domestic Payment Consent - Response

UML Diagram

Notes

Data Dictionary

Usage Examples

Generic Flow

Sequence Diagram

Illustrative Interactions

Create Domestic Payment Consent

Request

Response

Retrieve Domestic Payment Consent

Request

Response

Merchant

Illustrative Interactions

Create Domestic Payment Consent

Request

Response

Person To Person

Illustrative Interactions

Create Domestic Payment Consent

Request

Response