Domestic Payment Consents - v3.0.1

Version Control

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

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

NZWriteDomesticConsent2

NZWriteDomesticConsentResponse2

domestic-payment-consents

GET

GET /domestic-payment-consents/{ConsentId}

Mandatory

payments

Client Credentials

NA

NA

NZWriteDomesticConsentResponse2

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

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.

    • 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

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 NZWriteDomesticConsent2 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

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZWriteDomesticConsent2



NZWriteDomesticConsent2



NZWriteDomesticConsent2



Data

1..1

NZWriteDomesticConsent2/Data



NZWriteDataDomesticConsent1



Consent

1..1

NZWriteDomesticConsent2/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

NZWriteDomesticConsent2/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 NZWriteDomesticConsentResponse2 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

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZWriteDomesticConsentResponse2



NZWriteDomesticConsentResponse2

NZWriteDomesticConsentResponse2





Data

1..1

NZWriteDomesticConsentResponse2/Data

NZWriteDataDomesticConsentResponse1





ConsentId

1..1

NZWriteDomesticConsentResponse2/Data/ConsentId

Unique identification as assigned by the API Provider to uniquely identify the consent.

Max128Text



CreationDateTime

1..1

NZWriteDomesticConsentResponse2/Data/CreationDateTime

Date and time at which the consent was created.

ISODateTime



Status

1..1

NZWriteDomesticConsentResponse2/Data/Status

Specifies the status of consent in code form.

OBExternalConsentStatus1Code

Authorised
AwaitingAuthorisation
Consumed
Rejected

StatusUpdateDateTime

1..1

NZWriteDomesticConsentResponse2/Data/StatusUpdateDateTime

Date and time at which the consent status was updated.

ISODateTime



Consent

1..1

NZWriteDomesticConsentResponse2/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

NZWriteDomesticConsentResponse2/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

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
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