DateTime and Frequency Periods

Owned by Nigel Somerfield
Last updated: Apr 05, 2023
15 min read

For scheduling, periodicity and consent bounding the following guidance is given.

The long-lived consents (account information and enduring payment at the time of writing) use ISO-8601 DateTime to determine:

  • The duration for which a consent is valid, and;

  • constraints on the use or applicability of the consent

In ISO-8601, a DateTime is an ‘instant’1 value, determining a single point in time, on the ‘time axis’2. It has multiple formats, however, the API Centre standards require that in JSON payloads this is format-constrained to

<date>T<time>+<offset>, for example 2023-03-15T15:42:33+13:00, where:

  • 2023-05-15 is 15th March, 2023

  • T delimits ‘Time’

  • 15:42:33 is the time, using the format hours:minutes:seconds

  • +13:00 is the time offset from UTC, in this case NZDT (New Zealand Daylight Time)

Implementation note: for ease of implementation, when dates are stored or used in calculations it is advisable to use UTC time, rather than local offset, for example 2023-03-15T02:42:33+00:00 which is equivalent to the previous example.

1,2 are IS0-8601 definitions and will be discussed later, including assumptions made.

Base Time Unit

All time units in the standards are based on the SI standard, unit the ‘second’. All other units are a multiple of this.

Time zone offset requirement

When different components are used by the actors in the system, they may not all be in the same time zone. Without the ability to calculate time zone-corrected values for display, scheduling or other time-dependant activities, unexpected outcomes may result. For example, a user may use a payment service to pay a bill but miss a due date because payment cut-off times could not be correctly calculated.

Consent Duration

The two long-lived consents have slightly different approaches to determining the period of validity:

Consent Type

Starts On

Ends On

Consent Type

Starts On

Ends On

Account Information

Authorisation DateTime, the date and time when the consent status became ‘Authorised’

ExpirationDateTime

Note: ExpirationDateTime is optional and if not set, consent does not expire

Enduring Payment

FromDateTime, from the start of the ‘date’ component (disregard the time component)

ToDateTime, at the end of the ‘date’ component (disregard the time component)

Note: ToDateTime is optional and if not set, the consent does not expire.

ISO-8601 Periods - Enduring Payment Consent

The following period definitions are used in the standard:

Period

ISO-8601 Unit

ISO definition

Notes

Example period using DateTimes

Period

ISO-8601 Unit

ISO definition

Notes

Example period using DateTimes

Daily

Calendar Day (3.1.2.11)

Time scale unit starting at the beginning of the day and ending with the beginning of the next day, the latter being the starting instant of the next calendar day.

For the purposes of handling in digital system, day start is indicated with a DateTime time component of 00:00:00 and day end is indicated with time component 23:59:59 and date component remains unchanged.

2023-03-15T00:00:00+13:00 to 2023-03-15T23:59:59+13:00

Weekly

Week (3.1.2.15)

Duration of a calendar week
Note 1 to entry: The term “week” applies also to the duration of any time interval which starts at a certain time of day at a certain calendar day and ends at the same time of day at the same calendar day of the next calendar week.

For the purposes of handling in digital system, day start is indicated with a DateTime time component of 00:00:00 and period end is indicated by start date plus 6 days, with time component 23:59:59.

2023-03-21T00:00:00+13:00 to 2023-03-27T23:59:59+13:00

Fortnightly

n/a - no ISO definition

n/a - no ISO definition

Defined as 2 weekly periods. For the purposes of handling in digital system, day start is indicated with a DateTime time component of 00:00:00 and period end is indicated by DateTime with date component set as start date plus 13 days, with time component 23:59:59.

2023-03-14T00:00:00+13:00 to 2023-03-27T23:59:59+13:00

Monthly

Month (3.1.2.18)

Duration of a calendar month
Note 1 to entry: The term “month” applies also to the duration of any time interval which starts at a certain time of day at a certain calendar day of the calendar month and ends at the same time of day at the same calendar day of the next calendar month, if it exists.
Note 2 to entry: In certain applications a month is considered as a duration of 30 calendar days.

In addition to the ISO definition, the NZ Legislation Act 2019 section 56 applies.

For the purposes of handling in digital system, month start is indicated with a DateTime time component of 00:00:00. The month period end is indicated by the corresponding day in the following month minus one day, or (if there is no such day), at the close of the last day in the month indicated by a DateTime, with time component 23:59:59.

 

With corresponding day:
2023-03-14T00:00:00+13:00 to 2023-04-13T23:59:59+12:00
2023-04-14T00:00:00+12:00 to 2023-05-13T23:59:59+12:00

No corresponding day:
2023-01-31T00:00:00+13:00 to 2023-02-28T23:59:59+13:00
2023-03-01T00:00:00+13:00 to 2023-03-31T23:59:59+13:00

Annually

Year (3.1.2.20)

Duration of a calendar year
Note 1 to entry: In the Gregorian calendar, a year has 365 or 366 days. The duration is 366 days if the corresponding time interval begins February 28 or earlier in a leap year or March 2 or later in a year immediately preceding a leap year. If the interval begins February 29 (on a leap year), or March 1 of a year preceding a leap year, the end date has to be agreed on. Otherwise the duration is 365 days.
Note 2 to entry: The term “year” applies also to the duration of any time interval which starts at a certain time of day at a certain calendar date of the calendar year and ends at the same time of day at the same calendar date of the next calendar year with the exception noted in Note 1 to entry.

ISO does not strictly specify behaviour for leap year. The API centre does not currently take a position on this, and it is left to the API Provider to determine treatment of leap year. The following is proposed:

For the purposes of handling in digital system, year start is indicated with a DateTime with time component of 00:00:00. The year period end is indicated by the corresponding date in the following year minus one day, or (if there is no such day), at the close of the last day in the month corresponding to the start month indicated by a DateTime, with time component 23:59:59.

With corresponding day:
2023-03-14T00:00:00+13:00 to 2024-03-13T23:59:59+13:00

No corresponding day:
2024-02-29T00:00:00+13:00 to 2025-02-28T23:59:59+13:00

Notes:

  • It is acknowledged that the day representation of time 00:00:00 to 23:59:59 is misaligned to the ISO definition by 1 second. This is a simplification made so that time may be disregarded in calculating ranges and pro-rating.

  • For consent handling, requests that fall in the 1 second interval between 23:59:59 and 00:00:00 the next day may be accepted or rejected at the discretion of the API provider. Appropriate responses must be returned to the consumer either way.

  • Even with NTP, clocks across multiple systems or components may have some skew. API providers may accept requests that fall within a reasonable skew period of the above definitions.

  • With the exception of the Daily period, period alignment is to the FromDateTime in the consent, and not to ISO units ‘Calendar Week’, ‘Calendar Month’ or ‘Calendar Year’, which specify particular start and end of the periods.

Enduring Payment Consent - examples of Frequency Periods

The following are non-normative examples of enduring payment consent requests and illustrative timelines of activity using the consent. The time flow is left-to-right (start of consent to end of consent).

Daily

The following shows a consent request for three daily periods. For simplicity, no counts of payments are included in the consent example:

{ "Consent": { "FromDateTime": "2023-03-22T08:42:32+13:00", "ToDateTime": "2023-03-24T08:42:32+13:00", "MaximumAmount": { "Amount": "100.00", "Currency": "NZD" }, "TotalAmount": { "Amount": "1000.00", "Currency": "NZD" }, "Frequency": { "Period": "Daily", "TotalAmount": { "Amount": "200.00", "Currency": "NZD" } }, "CreditorAccount": [ { "SchemeName": "BECSElectronicCredit", "Identification": "12-1234-1234567-12", "Name": "ACME Inc" } ] } }

The corresponding timeline with example activity:

Notes:

  • Validity starts on Wednesday 22nd March 2023 and ends on Friday 25th March 2023

  • Payments can occur at any time on any of the valid days.

  • Amount values must be respected

  • API Provider processing schedules may mean that payments submitted close to the end of one day could be processed the following day (if following day is still within consent validity)

Weekly

The following shows a consent request for three weekly periods, encompassing two full week durations and one partial week duration. The calendars used are March and April 2023, starting on 22nd March, and ending on 7th April. This means the consent expires before the 3rd week is complete, hence the partial last week. The week periods are aligned with the consent FromDateTime. Calendars to assist visualisation:

March 2023 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 April 2023 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

For simplicity, no counts of payments are included in the consent example:

{ "Consent": { "FromDateTime": "2023-03-22T08:42:32+13:00", "ToDateTime": "2023-04-07T08:42:32+12:00", "MaximumAmount": { "Amount": "200.00", "Currency": "NZD" }, "TotalAmount": { "Amount": "3000.00", "Currency": "NZD" }, "Frequency": { "Period": "Weekly", "TotalAmount": { "Amount": "500.00", "Currency": "NZD" } }, "CreditorAccount": [ { "SchemeName": "BECSElectronicCredit", "Identification": "12-1234-1234567-12", "Name": "Spark Ltd" } ] } }

The corresponding timeline is:

Fortnightly

The following shows a consent request for two fortnightly periods, one full fortnight and one partial. The calendars used are March and April 2023, starting on 22nd March, and ending on 7th April. This means the consent expires before the 2nd fortnight is complete. The fortnight periods are aligned with the consent FromDateTime. Calendars to assist visualisation:

For simplicity, no counts of payments are included in the consent example:

The accompanying visualisation of the consent periods and usage is:

Monthly

The following shows a consent request for three monthly periods, two full months and one partial. The calendars used are March through June 2023, starting on 31st March, and ending on 7th June. This means the consent expires before the third month is complete. The monthly periods are aligned with the consent FromDateTime. Calendars to assist visualisation:

 

For simplicity, no counts of payments are included in the consent example:

The visualisation of monthly periods is:

Notes:

  • The monthly period end day is determined by the FromDateTime in the consent. In the example given the end day is the 30th day of the month.

  • When the monthly period end day is not available, the last day of the month is used

Annual

The following shows a consent request for three annual periods, two full years and one partial. The calendars used are March through June 2023, starting on 22nd March 2023, and ending on 7th June 2025. This means the consent expires before the third year is complete. The annual periods are aligned with the consent FromDateTime. For simplicity, no counts of payments are included in the consent example:

The accompanying visualisation corresponding to the consent is:

Account Information - Transaction Date Range

In the Account Access Consent request, two optional fields determine the time interval for which account related information may be retrieved:

  • TransactionFromDateTime - Specified start date and time for the transaction query period.
    If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.

  • TransactionToDateTime - Specified end date and time for the transaction query period.
    If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.

More information - if you have time

ISO-8601 refers to Einstein's theory of special relativity for the definition of time axis, against which all definitions of time are related. The API Centre standards make the following assumptions for clarity and consistency:

  • The standards assume only a single, shared frame of reference, as described in special relativity. This is assumed to be earth, sea-level anywhere in Aotearoa (New Zealand)

  • Time dilation effects from relativistic velocities are negligible, and no allowance has been made in the standards

  • Time dilation effects from gravity or acceleration are negligible, and no allowance has been made in the standards

  • Since the calendar generally used in NZ is the Gregorian Calendar, this will be used as the basis for standardised calendar dates, albeit using the ISO-8601 terms above

  • The time ‘instant’ referred to earlier is a single point, on the observably-shared time-axis (also mentioned earlier) in spacetime:

By SVG version: K. Aainsqatsi at en.wikipediaOriginal PNG version: Stib at en.wikipedia - Transferred from en.wikipedia to Commons.(Original text: self-made), CC BY-SA 3.0, File:World line.svg - Wikimedia Commons