Skip to end of banner
Go to start of banner

Domestic Payment Consents v2.2.3

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

Version Control

Version

Date

Author

Comments

2.0.0

Payments NZ API Working Group

Baseline

2.1-draft1

 

Gavin Wong (Unlicensed)

Updated:

2.2.1

Nigel Somerfield

Patch update to Swagger specification to BECSRemittance - DebtorReference and CreditorReference - specify additionalProperties: false

2.2.2

Nigel Somerfield

Patch update to Swagger to reflect /wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1455358006, which determined that the standard error response body should be included in all non-success HTTP responses.

2.2.3

Nigel Somerfield

Patch update to reflect /wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1455390754 , which removes the requirement to reject a domestic payment consent when DebtorReference is supplied without DebtorAccount

Definition

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

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

Endpoints

Resource

HTTP Operation

End-point

Mandatory ?

Scope

Grant Type

Idempotency Key

Request Object

Response Object

domestic-payment-consents

POST

POST /domestic-payment-consents

Mandatory

payments

Client Credentials

Yes

NZWriteDomesticConsent1

NZWriteDomesticConsentResponse1

domestic-payment-consents

GET

GET /domestic-payment-consents/{ConsentId}

Mandatory

payments

Client Credentials

NA

NA

NZWriteDomesticConsentResponse1

POST /domestic-payment-consents

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

  • The Third Party does this with the POST /domestic-payment-consents action.

  • The Third Party must have an access token issued by the API Provider using a client credentials grant.

  • The API endpoint allows the Third Party to send a copy of the consent (between Customer and Third Party) to the API Provider.

  • The API Provider creates the domestic-payment-consent and responds with a unique ConsentId to refer to the consent.

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

  • The domestic-payment-consent is only valid for 24 hours if not authorised by the Customer.

Flow

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

As part of the authorisation flow:

  • The API Provider authenticates the Customer.

  • The API Provider plays back the consent (registered by the Third Party) back to the Customer - to get consent authorisation. The Customer may accept or reject the consent in its entirety (but not selectively).

  • If the domestic-payment-consent does not indicate a debtor account, the API Provider presents the Customer a list of accounts from which the Customer must select one.

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

Status

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

GET /domestic-payment-consents/{ConsentId}

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

  • The Third Party does this with the GET /domestic-payment-consents/{ConsentId} action - where the ConsentId relates to the domestic-payment-consent to be retrieved.

  • The Third Party must have an access token issued by the API Provider using a client credentials grant.

Status

The available status codes for a domestic-payment-consent are:

  • AwaitingAuthorisation

  • Rejected

  • Authorised

  • Consumed

State Model

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

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

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

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

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

Diagram

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

Definitions

Status

Status Description

1

AwaitingAuthorisation

The consent resource is awaiting Customer authorisation.

  • This is an initial state.

2

Rejected

The consent resource has been rejected. 

  • This is a terminal state.

  • Does not distinguish between failure reasons - e.g. authorisation failed or bank rejected. 

3

Authorised 

The consent resource has been successfully authorised.

  • This is an intermediate state.

4

Consumed

The consented action has been successfully completed. This does not reflect the status of the consented action.

  • This is a terminal state.

Data Model

Reused Classes

NZDomesticConsent1

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

UML Diagram

Notes

  • In a domestic-payment-consent payload:

    • If the API Provider establishes a rejection scenario with payload or any contextual error during the API call, the API Provider must reject the request immediately with a 400 (Bad Request).

    • If the API Provider establishes a rejection scenario with the consent after the API call, the API Provider must set the Status of the consent to Rejected.

    • As a merchant may be initiating a payment via a Third Party - two identifiers are included in the payload: 

      • InstructionIdentification is uniquely generated by the Third Party - the expectation is that this is unique indefinitely across all time periods. The Third Party can ensure this is indefinitely unique by including a date or date time element to the field, or by inserting a unique Id. 

      • EndToEndIdentification is uniquely generated by the merchant.

    • The InstructionIdentification or EndToEndIdentification must not be used as the domestic-payment-consent identifier (ConsentId) - as the ConsentId must be uniquely generated by the API Provider.

    • The NZ Banking Data Account identification SchemeName is "BECSElectronicCredit".

    • Where "BECSElectronicCredit" is specified as the SchemeName in the Account identification section, the identification field must be populated with a structured bank account number in the form of 12-1234-1234567-12 where:

      • The first two digits are the bank number, which tells us which bank the account resides with;

      • The next four digits indicate the branch number, which tells us which branch of that bank the account is domiciled;  

      • The next seven digits indicate the account number; and

      • The last two digits indicate the account number suffix.

    • The DebtorAccount and DebtorReference are optional - as the Third Party may not know the account identification details for the Customer.

    • If the DebtorAccount is not specified in the payload, the Customer must select a valid DebtorAccount during the authentication flow with the API Provider.

    • If the DebtorAccount is specified by the Third Party - then the account identification details in the Consent object cannot be changed - as this is part of formal consent from the Customer.

    • If the DebtorReference is specified by the Third Party - then it cannot be changed - as this is part of formal consent from the Customer.

    • DebtorReference and CreditorReference - the Particulars, Code and Reference fields are currently constrained to 12 characters. The design choice has been made not to constrain through schema restrictions, to allow for future changes that remove the constraint. Note that not all banks will accept all valid characters. Constraining to a-z, A-Z, - (dash) and 0-9 is advised. One example is abc-XYZ-123.

    • The DebtorAccountRelease flag is optional - if set to true it indicates that the Customer has consented to releasing their debtor account details

    • API Providers must reject a domestic-payment-consent under these scenarios:

      • If the DebtorAccount is not valid.

      • If the SchemeName is not valid.

      • If the Currency is not supported.

      • If the Particulars, Code or Reference fields in either DebtorReference or CreditorReference objects contain invalid characters.

    • API Providers may reject a domestic-payment-consent depending on their own implementations:

      • If the CreditorAccount is not valid.

  • A payment-order initiated using a domestic-payment-consent:

    • must be a domestic-payment.

    • must have Consent and Risk objects that match the Consent and Risk objects of the corresponding domestic-payment-consent.

Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

NZDomesticConsent1


NZDomesticConsent1

The Consent payload is sent by the Third Party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.

NZDomesticConsent1


InstructionIdentification

1..1

NZDomesticConsent1/InstructionIdentification

Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.

Usage: the  instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.

OBNZ: Updated to allow 36 characters to allow for v4 UUID

Max36Text


EndToEndIdentification

1..1

NZDomesticConsent1/EndToEndIdentification

Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.

OBNZ: Updated to allow 36 characters to allow for v4 UUID

Max36Text


DebtorAccountRelease

0..1

NZDomesticConsent1/DebtorAccountRelease

Flags whether the Customer has consented with the Third Party to release their debtor account information.

xs:boolean


InstructedAmount

1..1

NZDomesticConsent1/InstructedAmount

Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

Usage: This amount has to be transported unchanged through the transaction chain.

OBActiveOrHistoricCurrencyAndAmount


Amount

1..1

NZDomesticConsent1/InstructedAmount/Amount

A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.

ActiveCurrencyAndAmount_SimpleType

^\d{1,13}\.\d{1,5}$

Currency

1..1

NZDomesticConsent1/InstructedAmount/Currency

A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".

ActiveOrHistoricCurrencyCode

^[A-Z]{3,3}$

DebtorAccount

0..1

NZDomesticConsent1/DebtorAccount

Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.

OBCashAccountDebtor1


SchemeName

1..1

NZDomesticConsent1/DebtorAccount/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

OBExternalAccountIdentification2Code

BECSElectronicCredit

Identification

1..1

NZDomesticConsent1/DebtorAccount/Identification

Identification assigned by an institution to identify an account. This identification is known by the account owner. For the NZ market, this will use the hyphen-delimited format: 2-4-7-2 where this is made up of bank-branch-account-suffix and each of the four components is a number, prepended with leading zeros to match the component length requirement.
For example 12-0123-0012345-00

Max34Text


Name

0..1

NZDomesticConsent1/DebtorAccount/Name

Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.

Max70Text


SecondaryIdentification

0..1

NZDomesticConsent1/DebtorAccount/SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution. 

Max34Text


CreditorAgent

0..1

NZDomesticConsent1/CreditorAgent

Financial institution servicing an account for the creditor.

OBBranchAndFinancialInstitutionIdentification2


SchemeName

1..1

NZDomesticConsent1/CreditorAgent/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

OBExternalFinancialInstitutionIdentification2Code

BICFI

Identification

1..1

NZDomesticConsent1/CreditorAgent/Identification

Unique and unambiguous identification of a financial institution or a branch of a financial institution.

Max35Text


CreditorAccount

1..1

NZDomesticConsent1/CreditorAccount

Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.

OBCashAccountCreditor1


SchemeName

1..1

NZDomesticConsent1/CreditorAccount/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

OBExternalAccountIdentification2Code

BECSElectronicCredit

Identification

1..1

NZDomesticConsent1/CreditorAccount/Identification

Identification assigned by an institution to identify an account. This identification is known by the account owner. For the NZ market, this will use the hyphen-delimited format: 2-4-7-2 where this is made up of bank-branch-account-suffix and each of the four components is a number, prepended with leading zeros to match the component length requirement.
For example 12-0123-0012345-00

Max34Text


Name

1..1

NZDomesticConsent1/CreditorAccount/Name

Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.

Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
API Providers may carry out name validation for Confirmation of Payee, but it is not mandatory.

Max70Text


SecondaryIdentification

0..1

NZDomesticConsent1/CreditorAccount/SecondaryIdentification

This is secondary identification of the account, as assigned by the account servicing institution. 

Max34Text


RemittanceInformation

1..1

NZDomesticConsent1/RemittanceInformation

Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.

NZRemittanceInformation1


Reference

0..1

NZDomesticConsent1/RemittanceInformation/Reference

Remittance information for use with BECSElectronicCredit payment scheme.

NZBECSRemittance1


CreditorName

1..1

NZDomesticConsent1/RemittanceInformation/Reference/CreditorName

The Creditor's Name.

Max20Text


DebtorName

0..1

NZDomesticConsent1/RemittanceInformation/Reference/DebtorName

The Debtor's Name.

Max20Text


CreditorReference

0..1

NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference

Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.

NZBECSReference1


Particulars

0..1

NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference/Particulars

Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.

Max12Text


Code

0..1

NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference/Code

Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.

Max12Text


Reference

0..1

NZDomesticConsent1/RemittanceInformation/Reference/CreditorReference/Reference

Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.

Max12Text


DebtorReference

0..1

NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference

Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.

NZBECSReference1


Particulars

0..1

NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference/Particulars

Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.

Max12Text


Code

0..1

NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference/Code

Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.

Max12Text


Reference

0..1

NZDomesticConsent1/RemittanceInformation/Reference/DebtorReference/Reference

Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.

Max12Text


Domestic Payment Consent - Request

The NZWriteDomesticConsent1 object will be used for the call to:

  • POST /domestic-payment-consents

UML Diagram

Notes

The domestic-payment-consent request contains these objects:

  • Consent

  • Risk

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

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
AwaitingAuthorisation
Consumed
Rejected

StatusUpdateDateTime

1..1

NZWriteDomesticConsentResponse1/Data/StatusUpdateDateTime

Date and time at which the consent status was updated.

ISODateTime


Consent

1..1

NZWriteDomesticConsentResponse1/Data/Consent

The Consent payload is sent by the Third Party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.

NZDomesticConsent1


Risk

1..1

NZWriteDomesticConsentResponse1/Risk

The Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.

NZRisk1


Usage Examples

Generic Flow

This example flows and payload examples are for a Third Party staging a domestic-payment-consent with an API Provider on behalf of a Customer.

Sequence Diagram

 Click here to expand UML diagram source...
participant Customer
participant Third Party
participant API Provider Authorisation Server
participant API Provider Resource Server

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

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

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

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

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

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

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

Illustrative Interactions

Create Domestic Payment Consent

Request
POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
    "Data": {
        "Consent": {
            "InstructionIdentification": "ACME412",
            "EndToEndIdentification": "FRESCO.21302.GFX.20",
            "InstructedAmount": {
                "Amount": "165.88",
                "Currency": "NZD"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "ACME Inc",
                "SecondaryIdentification": "0002"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "BillPayment",
        "MerchantCategoryCode": "O743",
        "MerchantCustomerIdentification": "CustomerId",
        "DeliveryAddress": {
            "AddressType": "DeliveryTo",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
    }
}
Response
HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
    "Data": {
        "ConsentId": "58923",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:15:13+00:00",
        "Consent": {
            "InstructionIdentification": "ACME412",
            "EndToEndIdentification": "FRESCO.21302.GFX.20",
            "InstructedAmount": {
                "Amount": "165.88",
                "Currency": "NZD"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "ACME Inc",
                "SecondaryIdentification": "0002"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "BillPayment",
        "MerchantCategoryCode": "O743",
        "MerchantCustomerIdentification": "CustomerId",
        "DeliveryAddress": {
            "AddressType": "DeliveryTo",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
    },
    "Links": {
        "Self": "https://api.alphabank.com/open-banking-nz/v2.1/domestic-payment-consents/58923"
    },
    "Meta": {
        "TotalPages": 1
    }
}

Retrieve Domestic Payment Consent

Request
GET /domestic-payment-consents/58923 HTTP/1.1
Authorization: Bearer Jhingapulaav
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json
Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
    "Data": {
        "ConsentId": "58923",
        "Status": "Authorised",
        "CreationDateTime": "2017-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:20:13+00:00",
        "Consent": {
            "InstructionIdentification": "ACME412",
            "EndToEndIdentification": "FRESCO.21302.GFX.20",
            "InstructedAmount": {
                "Amount": "165.88",
                "Currency": "NZD"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "ACME Inc",
                "SecondaryIdentification": "0002"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "BillPayment",
        "MerchantCategoryCode": "O743",
        "MerchantCustomerIdentification": "CustomerId",
        "DeliveryAddress": {
            "AddressType": "DeliveryTo",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
    },
    "Links": {
        "Self": "https://api.alphabank.com/open-banking-nz/v2.1/domestic-payment-consents/58923"
    },
    "Meta": {
        "TotalPages": 0
    }
}

Merchant

This example set of flows and payload examples are for a payment initiated by a merchant via a Third Party.

In this scenario:

  • The merchant has not specified the Debtor Account details for the Customer - the Customer will select their account during the authorisation of consent

  • The merchant's account is a building society account - with a roll number specified in the SecondaryIdentification field

Illustrative Interactions

Create Domestic Payment Consent

Request
POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
    "Data": {
        "Consent": {
            "InstructionIdentification": "ACME412",
            "EndToEndIdentification": "FRESCO.21302.GFX.20",
            "InstructedAmount": {
                "Amount": "165.88",
                "Currency": "NZD"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "ACME Inc",
                "SecondaryIdentification": "0002"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "BillPayment",
        "MerchantCategoryCode": "O743",
        "MerchantCustomerIdentification": "CustomerId",
        "DeliveryAddress": {
            "AddressType": "DeliveryTo",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
    }
}
Response
HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
    "Data": {
        "ConsentId": "58923",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:15:13+00:00",
        "Consent": {
            "InstructionIdentification": "ACME412",
            "EndToEndIdentification": "FRESCO.21302.GFX.20",
            "InstructedAmount": {
                "Amount": "165.88",
                "Currency": "NZD"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "ACME Inc",
                "SecondaryIdentification": "0002"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "BillPayment",
        "MerchantCategoryCode": "O743",
        "MerchantCustomerIdentification": "CustomerId",
        "DeliveryAddress": {
            "AddressType": "DeliveryTO",
            "AddressLine": [
                "ACME Wine Sales"
            ],
            "StreetName": "Shortland Street",
            "BuildingNumber": "123",
            "PostCode": "1010",
            "TownName": "Auckland",
            "Country": "NZ"
        }
    },
    "Links": {
        "Self": "https://api.alphabank.com/open-banking-nz/v2.1/domestic-payment-consents/58923"
    },
    "Meta": {
        "TotalPages": 1
    }
}

Person To Person

This example set of flows and payload examples are for a payment initiated by a person to another person via a Third Party.

In this scenario:

  • The Customer has pre-specified the account from which funds will be transferred (i.e., the Debtor Account details)

  • No building society accounts are involved in this interaction - so only the sort code and account number are specified in the DebtorAccount and CreditorAccount sections

Illustrative Interactions

Create Domestic Payment Consent

Request
POST /domestic-payment-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
  
{
    "Data": {
        "Consent": {
            "InstructionIdentification": "ANSM023",
            "EndToEndIdentification": "FRESCO.21302.GFX.37",
            "InstructedAmount": {
                "Amount": "20.00",
                "Currency": "NZD"
            },
            "DebtorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "Andrea Smith"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "21-4321-7654321-12",
                "Name": "Bob Clements"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    },
                    "DebtorName": "The Debtor",
                    "DebtorReference": {
                        "Particulars": "DebtorPart",
                        "Code": "DebtorCode",
                        "Reference": "DebtorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "PersonToPerson"
    }
}
Response
HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
  
{
    "Data": {
        "ConsentId": "7290",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime": "2019-06-05T15:15:13+00:00",
		"StatusUpdateDateTime": "2019-06-05T15:15:13+00:00",
        "Consent": {
            "InstructionIdentification": "ANSM023",
            "EndToEndIdentification": "FRESCO.21302.GFX.37",
            "InstructedAmount": {
                "Amount": "20.00",
                "Currency": "NZD"
            },
            "DebtorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "Andrea Smith"
            },
            "CreditorAccount": {
                "SchemeName": "BECSElectronicCredit",
                "Identification": "12-1234-1234567-12",
                "Name": "Bob Clements"
            },
            "RemittanceInformation": {
                "Reference": {
                    "CreditorName": "The Creditor",
                    "CreditorReference": {
                        "Particulars": "CreditorPart",
                        "Code": "CreditorCode",
                        "Reference": "CreditorRef"
                    },
                    "DebtorName": "The Debtor",
                    "DebtorReference": {
                        "Particulars": "DebtorPart",
                        "Code": "DebtorCode",
                        "Reference": "DebtorRef"
                    }
                }
            }
        }
    },
    "Risk": {
        "PaymentContextCode": "PersonToPerson"
    },
    "Links": {
        "Self": "https://api.alphabank.com/open-banking-nz/v2.1/domestic-payment-consents/7290"
    },
    "Meta": {}
}

  • No labels