Enduring Payment Consents - v2.0.0

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

v2.0-draft1

May 1, 2019

@Gavin Wong (Unlicensed)

Initial version

v2.0-draft2

Jul 8, 2019 

@Gavin Wong (Unlicensed)

Updates:

  • "Authentication flow" to "authorisation flow"

  • Clarified in v2.0-draft2-NZEnduringConsent1

    • Clarified consent parameter behaviour further to "If an enduring consent parameter is not specified, the API Provider must not enforce a specific limit for the use of the enduring payment consent. E.g., if no TotalAmount is specified, there is no specific restriction on the total of all successful InstructedAmount(s) that may be initiated during the lifetime of the enduring payment consent."

    • Explicit references to Frequency/TotalCount (instead of TotalCount where applicable) and Frequency/TotalAmount (instead of TotalAmount). Reworded definition of the Frequency object for clarity.

    • IndividualAmount renamed to MaximumAmount for clarity

    • Frequency/Period updated to included Fortnight enumeration

  • CreditorAccount in v2.0-draft2-UsageExamples updated to array

  • Updated guidance to v2.0-draft2-Flow that if a debtor account is not specified in the enduring payment consent - the "Customer must select one." to reflect Technical Decision 008

  • In v2.0-draft2-NZEnduringConsent1

    • Updated DebtorAccount from 0..n to 0..1 (only one debtor account may be specified in the enduring payment consent) to reflect Technical Decision 008.

    • Updated selecting debtor accounts to "Customer must select one valid DebtorAccount" in v2.0-draft2-NZEnduringConsent1

    • Updated guidance on payment-orders created with an enduring payment consent "must have a DebtorAccount specified that matches the DebtorAccount linked to the enduring payment consent. This DebtorAccount linked to an enduring payment consent must not be modified by the Customer with the API Provider after authorisation."

  • Updated references in v2.0-draft2-UsageExamples web sequence diagrams to selecting "debtor account(s)" to "debtor account" to reflect Technical Decision 008.

  • Updated v2.0-draft2-DataModel to include DebtorAccountRelease flag (Business Decision - 002 - Debtor Account Information In a Payment Flow)

  • Updated Usage Example wording

  • Updated DeliveryAddress class in NZRisk1 to OBPostalAddress8 to align with Technical Decision - 009 - Standardising Address Objects

Additions:

  • In v2.0-draft2-NZEnduringConsent1 added

    • Definition for total number of successful payment-orders as "The total number of successful payment-orders is defined as the number of successfully created domestic-payments in the AcceptedSettlementInProgress or AcceptedSettlementCompleted state."

    • Definition for total amount of successful payment-orders as "The total amount of successful payment-orders is defined as the number of successfully created domestic-payments in the AcceptedSettlementInProgress or AcceptedSettlementCompleted state."

    • Notes on what is mandatory or optional in the payload

    • Examples for a "period" from the FromDateTime

  • Guidance for CreditorAccount in the Consent object

Removed:

  • In Notes section:

    • Removed the treatment of rejection scenarios - for 400 (Bad Request) vs. consent resource Status of Rejected. Have moved this to the main API page.

    • Removed reference to FromDateTime rejection scenario

  • Removed "GET /enduring-payment-consents/{ConsentId}/debtor-accounts" from specification page

  • Removed "The DebtorAccount list in the enduring payment consent response must match the DebtorAccount list in the request - even if the DebtorAccount list has changed." from v2.0-draft2-EnduringPaymentConsent-Response as no longer relevant with Technical Decision 008.

  • Removed v2.0-draft2-Accounts-Response section as no longer relevant with Technical Decision 008.

v2.0-draft3

Oct 8, 2019 

@Gavin Wong (Unlicensed)

Additions:

  • Additional rejection scenario for creating an enduring payment consent of "If the ToDateTime is not greater than the FromDateTime"

Updates:

Errata:

  • PSD2 terms updated in web sequence diagram

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

  • Date example errata in v2.0-draft3-NZEnduringConsent1

v2.0-rc2

Jan 6, 2020

@Gavin Wong (Unlicensed)

Updates:

Errata:

  • Updating references to “resources” to clarify language

v2.0

Mar 20, 2020

@Gavin Wong (Unlicensed)

Updates:

  • As per API Council decision - CreditorAccount has been updated to mandatory:

    • Removed the “gateway model” illustrative interaction

    • Updated definition to “The CreditorAccount is mandatory - the Third Party may be given consent to initiate payments to one or many specified CreditorAccount(s).”

      • Updated UML diagram to reflect CreditorAccount as 1..n

      • Updated Data Dictionary to reflect CreditorAccount as 1..n

  • Removed “If no CreditorAccount is specified in the enduring-payment-consent, the Third Party may initiate a payment to any CreditorAccount.” as no longer applicable

Errata:

  • Update the definition of TotalAmount from "number of successfully created" to "sum total of the InstructedAmount(s) of successfully created"

Definition

The enduring-payment-consents resource represents long lived payment-order consents that have been agreed between the Customer and the Third Party, and contains fields which describe the parameters for payment-order(s) 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

The enduring-payment-consent endpoints are all optional to implement. However, if the enduring-payment-consent functionality is implemented, all endpoints must be implemented together.

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Idempotency Key

Request Object

Response Object

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Idempotency Key

Request Object

Response Object

enduring-payment-consents

POST

POST /enduring-payment-consents

Optional

payments

Client Credentials

Yes

NZWriteEnduringConsent1

NZWriteEnduringConsentResponse1

enduring-payment-consents

GET

GET /enduring-payment-consents/{ConsentId}

Optional

payments

Client Credentials

No

NA

NZWriteEnduringConsentResponse1

enduring-payment-consents

DELETE

DELETE /enduring-payment-consents/{ConsentId}

Optional

payments

Client Credentials

No

NA

NA

POST /enduring-payment-consents

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

  • The Third Party does this with the POST /enduring-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 enduring-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 enduring-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 enduring-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 enduring-payment-consent has been created.

GET /enduring-payment-consents/{ConsentId}

A Third Party may optionally retrieve an enduring-payment-consent that they have created to check its status.

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

  • AwaitingAuthorisation

  • Rejected

  • Authorised

  • Revoked

DELETE /enduring-payment-consents/{ConsentId}

If the Customer revokes the enduring-payment-consent with the Third Party - the Third Party must delete the enduring-payment-consent. 

  • The Third Party does this with the DELETE /enduring-payment-consents/{ConsentId} action - where the ConsentId relates to the enduring-payment-consent to be deleted.

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

State Model

The state model for an enduring-payment-consent follows a long 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 Customer revokes the payment-order consent in the Authorised Status with the API Provider, the Status of the payment-order consent will be set to Revoked.

Diagram

This is the state diagram for the status of an enduring-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

Revoked

The consent resource has been revoked via the API Provider interface.

  • This is a terminal state.

Data Model

The data dictionary section gives detail on the payload content for the enduring-payment-consent flows.

Reused Classes

NZEnduringConsent1

This section describes the NZEnduringConsent1 class which is reused in the enduring-payment-consent.

UML Diagram

Notes

  • In an enduring-payment consent-payload:

    • If an enduring-payment-consent parameter is not specified, the API Provider must not enforce a specific limit for the use of the enduring-payment-consent. E.g., if no TotalAmount is specified, there is no specific restriction on the total of all successful InstructedAmount(s) that may be initiated during the lifetime of the enduring-payment-consent. 

    • The FromDateTime is mandatory as it defines the start date for the Frequency/Period to be calculated.

    • The ToDateTime is optional as the enduring-payment-consent may be valid for an indefinite period.

    • The TotalCount is optional and specifies the total number of successful payment-orders that may be created using the enduring-payment-consent. The total number of successful payment-orders is defined as the number of successfully created domestic-payments in the AcceptedSettlementInProgress or AcceptedSettlementCompleted state.

    • The TotalAmount is optional and specifies the total amount of successful payment-orders that may be created using the enduring-payment-consent. The total amount of successful payment-orders is defined as the sum total of the InstructedAmount(s) of successfully created domestic-payments in the AcceptedSettlementInProgress or AcceptedSettlementCompleted state.

    • The MaximumAmount is mandatory and specifies the maximum individual amount for a payment-order that may be created using the enduring-payment-consent. A Customer and Third Party may still agree a fixed amount for payment-orders, as long as it is under the MaximumAmount.

    • The Frequency object is mandatory and specifies constraints on the payment-orders that may be initiated within a "period" from the FromDateTime:

      • A period from the FromDateTime is calculated with the FromDateTime being fixed. E.g., 

        • A "Monthly" period with a FromDateTime 2019-08-21T00:00:00 will have periods defined as

          • 2019-08-21T00:00:00 to 2019-09-20T23:59:59

          • 2019-09-21T00:00:00 to 2019-10-20T23:59:59

          • 2019-10-21T00:00:00 to 2019-11-20T23:59:59

          • Etc

        • A "Weekly" period with a FromDateTime 2019-08-21T00:00:00 will have periods defined as

          • 2019-08-21T00:00:00 to 2019-08-27T23:59:59

          • 2019-08-28T00:00:00 to 2019-09-03T23:59:59

          • 2019-09-04T00:00:00 to 2019-09-10T23:59:59

          • Etc

      • The Frequency/Period is mandatory and specifies a rolling period to measure the total count or total amount of successful payment-orders.

      • The Frequency/TotalCount is optional and specifies the total number of successful payment-orders that may be initiated within a Frequency/Period.

      • The Frequency/TotalAmount is mandatory and specifies the total amount of successful payment-orders that may be created within a Frequency/Period.

    • The DebtorAccount is 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 one valid DebtorAccount during the authorisation flow with the API Provider.

    • The CreditorAccount is mandatory - the Third Party may be given consent to initiate payments to one or many specified CreditorAccount(s).

    • 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 an enduring-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 ToDateTime value is in the past.

      • If the ToDateTime is not greater than the FromDateTime.

      • If the Frequency/Period is not supported. 

    • API Providers may reject an enduring-payment-consent depending on their own implementations:

      • If the Frequency, MaximumAmount, TotalCount or TotalAmount values exceed implemented limits.

      • If the CreditorAccount is not valid.

  • A payment-order created using an enduring-payment-consent:

    • must be created with the API Provider between the FromDateTime and ToDateTime in the enduring-payment-consent.

    • must not have an InstructedAmount that exceeds the MaximumAmount in the enduring-payment-consent.

    • must be rejected if the cumulative successful payments initiated (including the current payment) via the Payment APIs exceed the limits (i.e., the TotalCount, TotalAmount) in the enduring-payment-consent.

    • must be rejected if the cumulative successful payments initiated (including the current payment) via the Payment APIs for the specified period from the FromDateTime (i.e., the Frequency/Period) exceed the limits for the specified period (i.e., Frequency/TotalCount, Frequency/TotalAmount) in the enduring-payment-consent,

    • must have a DebtorAccount specified that matches the DebtorAccount linked to the enduring-payment-consent. This DebtorAccount linked to an enduring-payment-consent must not be modified by the Customer with the API Provider after authorisation.

    • must have a CreditorAccount specified that matches one of the CreditorAccount values in the enduring-payment-consent.

Data Dictionary

Name

Occurrence

XPath

Notes

Class

Codes

Name

Occurrence

XPath

Notes

Class

Codes

NZEnduringConsent1



NZEnduringConsent1

The Consent payload is sent by the Third Party to the API Provider. It is used to request a long lived payment consent to move funds from a debtor account to a creditor.

NZEnduringConsent1



FromDateTime

1..1

NZEnduringConsent1/FromDateTime

Start date time for which the enduring payment consent remains valid.

ISODateTime



ToDateTime

0..1

NZEnduringConsent1/ToDateTime

End date time for which the enduring payment consent remains valid.

ISODateTime



TotalCount

0..1

NZEnduringConsent1/TotalCount

Maximum number of instructions to be created and processed for the enduring payment consent.

DecimalNumber



DebtorAccountRelease

0..1

NZEnduringConsent1/DebtorAccountRelease

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

xs:boolean



TotalAmount

0..1

NZEnduringConsent1/TotalAmount

Maximum amount of money to be moved between the debtor and creditor as a cumulative total for the duration of the enduring payment consent, before deduction of charges, expressed in the currency as ordered by the initiating party.

OBActiveOrHistoricCurrencyAndAmount



Amount

1..1

NZEnduringConsent1/TotalAmount/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

NZEnduringConsent1/TotalAmount/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}$

MaximumAmount

1..1

NZEnduringConsent1/MaximumAmount

Maximum amount of money to be moved between the debtor and creditor for an individual payment, before deduction of charges, expressed in the currency as ordered by the initiating party.

OBActiveOrHistoricCurrencyAndAmount



Amount

1..1

NZEnduringConsent1/MaximumAmount/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

NZEnduringConsent1/MaximumAmount/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}$

Frequency

1..1

NZEnduringConsent1/Frequency

The payment limits for a specified period.

NZEnduringFrequency1



Period

1..1

NZEnduringConsent1/Frequency/Period

Period for which the number of instructions are to be created and processed.

Frequency6Code

Annual
Daily
Fortnightly
Monthly
Weekly

TotalCount

0..1

NZEnduringConsent1/Frequency/TotalCount

Maximum number of instructions to be created and processed during the specified period.

DecimalNumber



TotalAmount

1..1

NZEnduringConsent1/Frequency/TotalAmount

Maximum amount of money to be moved between the debtor and creditor during the period specified, before deduction of charges, expressed in the currency as ordered by the initiating party.

OBActiveOrHistoricCurrencyAndAmount



Amount

1..1

NZEnduringConsent1/Frequency/TotalAmount/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

NZEnduringConsent1/Frequency/TotalAmount/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

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

NZEnduringConsent1/DebtorAccount/SchemeName

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

OBExternalAccountIdentification2Code

BECSElectronicCredit

Identification

1..1

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

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

NZEnduringConsent1/DebtorAccount/SecondaryIdentification

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

Max34Text



CreditorAccount

1..n

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

NZEnduringConsent1/CreditorAccount/SchemeName

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

OBExternalAccountIdentification2Code

BECSElectronicCredit

Identification

1..1

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

NZEnduringConsent1/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.
OB: No name validation is expected for confirmation of payee.

Max70Text



SecondaryIdentification

0..1

NZEnduringConsent1/CreditorAccount/SecondaryIdentification

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

Max34Text



The NZWriteEnduringConsent1 object will be used for the call to:

  • POST /enduring-payment-consents

UML Diagram

Notes

The enduring-payment-consent request contains these objects:

  • Consent

  • Risk

Data Dictionary

Name

Occurrence

XPath

Notes

Class

Codes

Name

Occurrence

XPath

Notes

Class

Codes

NZWriteEnduringConsent1



NZWriteEnduringConsent1



NZWriteEnduringConsent1



Data

1..1

NZWriteEnduringConsent1/Data



NZWriteDataEnduringConsent1



Consent

1..1

NZWriteEnduringConsent1/Data/Consent

The enduring payment consent payload is sent by the Third Party to the API Provider.

NZEnduringConsent1



Risk

1..1

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



The NZWriteEnduringConsentResponse1 object will be used for a call to:

  • POST /enduring-payment-consents

  • GET /enduring-payment-consents/{ConsentId}

UML Diagram

Notes

  • The enduring-payment-consent response contains the full original payload from the enduring-payment-consent request, with the additional elements below:

    • ConsentId

    • Status

    • CreatedDateTime

    • StatusUpdateDateTime

Data Dictionary

Name

Occurrence

XPath

Notes

Class

Codes

Name

Occurrence

XPath

Notes

Class

Codes

NZWriteEnduringConsentResponse1



NZWriteEnduringConsentResponse1

NZWriteEnduringConsentResponse1





Data

1..1

NZWriteEnduringConsentResponse1/Data

NZWriteDataEnduringConsentResponse1





ConsentId

1..1

NZWriteEnduringConsentResponse1/Data/ConsentId

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

Max128Text



CreationDateTime

1..1

NZWriteEnduringConsentResponse1/Data/CreationDateTime

Date and time at which the consent was created.

ISODateTime



Status

1..1

NZWriteEnduringConsentResponse1/Data/Status

Specifies the status of consent in code form.

OBExternalConsentStatus1Code

Authorised
AwaitingAuthorisation
Rejected
Revoked

StatusUpdateDateTime

1..1

NZWriteEnduringConsentResponse1/Data/StatusUpdateDateTime

Date and time at which the consent status was updated.

ISODateTime



Consent

1..1

NZWriteEnduringConsentResponse1/Data/Consent

The Consent payload is sent by the Third Party to the API Provider. It is used to request a long lived payment consent to move funds from a debtor account to a creditor.

NZEnduringConsent1



Risk

1..1

NZWriteEnduringConsentResponse1/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 set of flows and payload examples are for a Third Party staging an enduring-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 Enduring Payment Consent end note Customer -> Third Party: Agree enduring payment consent note over Customer, API Provider Resource Server Step 2: Create Enduring 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 /enduring-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 account 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 enduring-payment-consents Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA Third Party -> API Provider Resource Server: GET /enduring-payment-consents/{ConsentId} API Provider Resource Server -> Third Party: HTTP 200 (OK) enduring-payment-consent resource end opt

Illustrative Interactions

Request
POST /enduring-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": { "FromDateTime": "2019-05-05T00:00:00+00:00", "MaximumAmount": { "Amount": "100.00", "Currency": "NZD" }, "TotalAmount": { "Amount": "10000.00", "Currency": "NZD" }, "Frequency": { "Period": "Monthly", "TotalAmount": { "Amount": "1000.00", "Currency": "NZD" } }, "CreditorAccount": [{ "SchemeName": "BECSElectronicCredit", "Identification": "12-1234-1234567-12", "Name": "ACME Inc" }] } }, "Risk": { "PaymentContextCode": "BillPayment" } }
Response
HTTP/1.1 201 Created x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Content-Type: application/json   { "Data": { "ConsentId": "89887", "Status": "AwaitingAuthorisation", "CreationDateTime": "2019-05-05T15:15:13+00:00", "StatusUpdateDateTime": "2019-05-05T15:15:13+00:00", "Consent": { "FromDateTime": "2019-05-05T00:00:00+00:00", "MaximumAmount": { "Amount": "100.00", "Currency": "NZD" }, "TotalAmount": { "Amount": "10000.00", "Currency": "NZD" }, "Frequency": { "Period": "Monthly", "TotalAmount": { "Amount": "1000.00", "Currency": "NZD" } }, "CreditorAccount": [{ "SchemeName": "BECSElectronicCredit", "Identification": "12-1234-1234567-12", "Name": "ACME Inc" }] } }, "Risk": { "PaymentContextCode": "BillPayment" }, "Links": { "Self": "https://api.alphabank.com/open-banking-nz/v2.0/enduring-payment-consents/89887" }, "Meta": { "TotalPages": 1 } }
Request
Response
Request
Response

Subscription

The generic flow for setting up an enduring-payment-consent remains the same. However, the consent payload differs depending on the scenario.

In this scenario:

  • The payment-order using the enduring-payment-consent is for the same fixed amount for a regular monthly subscription.

    • The MaximumAmount is set to the maximum of NZD 100.

    • The Frequency is set to 1 successful payment per month.

    • The CreditorAccount is set to the account of the merchant.

Illustrative Interactions

Create Enduring Payment Consent

Request
Response

Direct Model

The generic flow for setting up an enduring-payment-consent remains the same. However, the consent payload differs depending on the scenario.

In this scenario:

  • The enduring-payment-consent is to an account authorised by the Customer

Illustrative Interactions

Create Enduring Payment Consent

Request
Response