/
Domestic Payment Consents - v2.0-rc1

Domestic Payment Consents - v2.0-rc1

Owned by Matthew Bell
Nov 13, 2019
18 min read

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

v1.0.0

May 1, 2019

@Gavin Wong (Unlicensed)

Baseline

v2.0.0-draft1

May 8, 2019

@Gavin Wong (Unlicensed)

Updates:

  • Restructured pages to one page per resource

  • Updated payment resource to domestic-payment-consent (aligned with OBIE v3.1.2)

  • Updated PaymentId to ConsentId (aligned with OBIE v3.1.2)

  • Updated name of Initiation object to Consent (to align all consent resources)

  • Updated Payments section to v2.0-draft1-Endpoints section with sub-sections for:

  • In Domestic Payment Consents - v2.0-draft2#v2.0-draft1-Endpoints table - have updated "Idempotent" column to "Idempotency Key" (aligned with OBIE v3.1.2)

  • Updated "Authorization Code" grant to "authorization flow (either redirect flow or decoupled flow)"

  • Updated v2.0-draft1-StateModel and clarified triggers for all Status changes, and tightened language

  • Updated "Authorised" to an intermediate state (to align with OBIE v3.1.2)

  • Separated out v2.0-draft1-NZDomesticConsent1 - as this is re-used across the domestic-payment endpoints:

    • Clarified 400 (Bad Request) vs Status of Rejected

    • Separated scenarios where the API Provider must or may reject a domestic payment consent (for clarity)

    • Reworded "Neither the InstructionIdentification nor EndToEndIdentification will be used as the payment resource identifier (PaymentId) - as the PaymentId must be uniquely generated by the API Provider." to "The InstructionIdentification or EndToEndIdentification must not be used as the domestic payment consent resource identifier (ConsentId) - as the ConsentId must be uniquely generated by the API Provider." for clarity

  • Updated structure of v2.0-draft1-UsageExamples:

Additions:

  • New section for v2.0-draft1-Definition

  • In v2.0-draft1-POST/domestic-payment-consents section added two sections to clarify behaviour:

  • Added new status for consent object of "Consumed" (to align with OBIE v3.1.2)

  • In v2.0-draft1-NZDomesticConsent1 section:

    • Added guidance that "If the DebtorAccount is not specified in the payload, the Customer must select a valid DebtorAccount during the authentication flow with the API Provider." for completeness

    • Added section for "API Providers must reject a domestic payment consent under these scenarios:"

    • Added section for "API Providers may reject a domestic payment consent depending on their own implementations:"

    • Added behaviour for "A domestic payment initiated using a domestic payment consent:"

    • Added to API Providers must reject:

      • If the SchemeName is not valid.

      • If the Currency is not supported.

    • Added to API Providers may reject:

      • If the CreditorAccount is not valid.

  • In v2.0-draft1-DomesticPaymentConsent-Response have added the StatusUpdateDateTime field (to align with OBIE v3.1.2, and the Account Information API)

Removed:

  • In v2.0-draft1-StateModel have removed the "NZ Status Clarification" column, and merged "Payment Status Description" to have a "Status Description" column.

  • Comment "Design decisions for the Initiation section of the payload - and how this maps to the ISO 20022 messaging standard are articulated in the Mapping to Schemes and Standards section." in the v2.0-draft1-NZDomesticConsent1 section

v2.0-draft2

Jul 8, 2019 

@Gavin Wong (Unlicensed)

Updates:

Errata:

  • In Flow section - updated to "the Customer must select one."

  • Typos

v2.0-draft3

Oct 8, 2019 

@Gavin Wong (Unlicensed)

Updates:

  • Updated class name for Status field to OBExternalConsentStatus1Code

Errata:

  • Incorrect consent resource Status field enumeration in Data Dictionary

  • PSD2 terms updated in web sequence diagram

  • Updated DeliveryAddress in v2.0-draft3-UsageExamples to align with data model

Definition

The domestic-payment-consent resource represents a short lived payment-order consent that has 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 the payment-order 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

third_party_client_credential

Client Credentials

Yes

NZWriteDomesticConsent1

NZWriteDomesticConsentResponse1

domestic-payment-consents

GET

GET /domestic-payment-consents/{ConsentId}

Mandatory

third_party_client_credential

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

  • 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 resource and responds with a unique ConsentId to refer to the resource.

  • At the point the consent resource is created, the consent has not been authorised.

  • The domestic-payment-consent resource 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 resource 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 the enduring-payment-consent resource are:

  • AwaitingAuthorisation

  • Rejected

  • Authorised

  • Consumed

State Model

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

  • When the Third Party creates the payment-consent resource with the API Provider, the Status of the payment-consent resource will be set to "AwaitingAuthorisation".

  • When the Customer authorises the payment-consent resource with the API Provider, the Status of the payment-consent resource will be updated with "Authorised".

  • If the Customer rejects the consent or the payment-consent has failed some other API Provider validation, the Status of the payment-consent resource will be set to "Rejected".

  • If the Third Party uses a payment-consent in an "Authorised" Status to create a payment resource, the Status of the payment-consent resource used will be set to "Consumed".

Diagram

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

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-consent and domestic-payment 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 resource 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 resource 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 domestic payment initiated using a domestic payment consent:

    • must be a domestic-payment resource.

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

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 resource was created

  • Status of the domestic-payment-consent resource

  • Status update date time of the domestic-payment-consent resource

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

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

Max128Text



CreationDateTime

1..1

NZWriteDomesticConsentResponse1/Data/CreationDateTime

Date and time at which the resource was created.

ISODateTime



Status

1..1

NZWriteDomesticConsentResponse1/Data/Status

Specifies the status of consent resource in code form.

OBExternalConsentStatus1Code

Authorised
AwaitingAuthorisation
Consumed
Rejected

StatusUpdateDateTime

1..1

NZWriteDomesticConsentResponse1/Data/StatusUpdateDateTime

Date and time at which the resource 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



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.0/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.0/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 Enduring 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.0/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.0/domestic-payment-consents/7290"
    },
    "Meta": {}
}