Version Control

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.

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

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.

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

Enduring Payment Consent - Request

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

Enduring Payment Consent - Response

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

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

Create Enduring Payment Consent

Retrieve Enduring Payment Consent

Delete Enduring Payment Consent

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

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