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.

Open

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

Open

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