Domestic Payment Consents v2.3.0
- 1 Version Control
- 2 Definition
- 3 Endpoints
- 4 State Model
- 4.1 Diagram
- 4.2 Definitions
- 5 Data Model
- 5.1 Reused Classes
- 5.1.1 NZDomesticConsent1
- 5.2 Domestic Payment Consent - Request
- 5.2.1 UML Diagram
- 5.2.2 Notes
- 5.2.3 Data Dictionary
- 5.3 Domestic Payment Consent - Response
- 5.3.1 UML Diagram
- 5.3.2 Notes
- 5.3.3 Data Dictionary
- 5.1 Reused Classes
- 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:
|
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 toConsumed
.
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.
|
2 | Rejected | The consent resource has been rejected.
|
3 | Authorised | The consent resource has been successfully authorised.
|
4 | Consumed | The consented action has been successfully completed. This does not reflect the status of the consented action.
|
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 detailsAPI 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. | 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. | 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. | 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. | 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. | 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. | 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. | 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 | Codes |
---|---|---|---|---|---|
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 |
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
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
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 Consent
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 Consent
Request
Response