Energy - GetAgreedPaymentSchedule API - manualPayment section should have paymentFrequency instead of billFrequency field

[Kingson-EA]

Description

Currently provided structure for manualPayment section intend to capture the manual payment schedule of customer but requested information is billFrequency. Where Customer makes a manual payment based on instalment schedule, payment schedule (weekly, Fortnightly or monthly) is different to billing schedule (Monthly or Quarterly).

Area Affected

Get Agreed Payment Schedule - Energy API

Current Structure

manualPayment - represents a manual payment schedule where the customer pays in response to a delivered statement. Mandatory if paymentScheduleUType is set to manualPayment)
» billFrequency - The frequency with which a bill will be issued

Change Proposed

Change billFrequncy to PaymentFrequency (similar to card/direct Debit section). If manual payment is by instalment schedule then instalment frequency can be mapped other bill frequency shall be mapped as payment frequency.

manualPayment - represents a manual payment schedule where the customer pays in response to a agreed schedule or delivered statement. Mandatory if paymentScheduleUType is set to manualPayment)
» paymentFrequency - The frequency that payments will occur.

[CDR-API-Stream]

There are a few issues/questions raised against GetAgreedPaymentSchedule API, including this CR. The DSB is including a summary and proposed solution for each of them here to make it easy to review:

Issue 1: Manual payments via payment schedule-plan (this CR):

Summary:
This issue was discussed during the MI11 call on 8th June. Below are the key points:

• The intent of this API is to describe the election on how the customer wishes to pay for their account; it is not to describe payment plans details (for e.g. how a consumer would pay for if in arrears and what the schedule in place for it is).
• If there is no specific election, the consumer would get bills and pay when they would like.
• As an example, if a consumer has setup a $10 / week payment plan which they do manually, the $10/week is not expected in this API but the fact that manual payment is made is.

Proposed solution:
As discussed during the call, based on the above points no change is recommended to the schema. The description of the API can be updated to ensure the intent is clearly understood. Energy Australia stated agreement to this proposal.

Issue 2: Multiple payment agreements for a single account (CR 511 comment)

Summary:

• A consumer could have different payment schedules setup for different connection points within a single account.

Proposed solution:
The DSB recommends converting EnergyPaymentSchedule into an array and add servicepointId in the schema as an identifier. The proposed schema would be as below:

{
    "data": {
        "paymentSchedules": [ /// Array of payment schedules
            {
                "servicePointId": "string", //mandatory - ServicePointId for the paymentschedule
                "amount": "string",
                "paymentScheduleUType": "cardDebit",
                "cardDebit": {
                  "cardScheme": "VISA",
                  "paymentFrequency": "string",
                  "calculationType": "STATIC"
                },
                "directDebit": {
                  "isTokenised": true,
                  "bsb": "string",
                  "accountNumber": "string",
                  "paymentFrequency": "string",
                  "calculationType": "STATIC"
                },
                "manualPayment": {
                  "billFrequency": "string"
                }
            }
        ]
    },
    "links": {
        "self": "string"
    },
    "meta": {}
},

Issue 3: Paypal based payments (CR 511 comment)

Summary

• A consumer may have paypal/digital wallet based payment setup. The current standards do not cater for this (or other types of digital wallet)

Proposed solution:
Add a new UType for digital wallet (which would allow specifying PayPal). The BankingDigitalWalletPayee schema can be reused with the addition of paymentFrequency and calculationType fields.

"digitalWallet": {
  "name": "string", // The name assigned to the digital wallet by the owner of the wallet, else the display name provided by the digital wallet provider
  "identifier": "string", // The identifier of the digital wallet (dependent on type)
  "type": ["EMAIL", "CONTACT_NAME", "TELEPHONE"] // The type of the digital wallet identifier
  "provider": ["PAYPAL_AU", "OTHER"] // The provider of the digital wallet
  "paymentFrequency": "string",
  "calculationType":  ["STATIC", "BALANCED", "CALCULATED"]
}

Issue 4: Unclear isTokenised description (CR 511 comment)

Summary

• The isTokenised field description currently states the following:
  Flag indicating that the account details are tokenised and cannot be shared. False if absent. If false then bsb and accountNumber should not be expected to be included
• This is incorrect as the bsb and accountNumber should be shared if they are not tokenised.

Proposed solution:

• Update the description to:
  Flag indicating that the account details are tokenised and cannot be shared. False if absent. If true then bsb and accountNumber should not be expected to be included

Feedback on the proposed options for all the above issues is welcome.

[perlboy]

Issue 2: Multiple payment agreements for a single account (CR 511 comment)

A payment plan may not be attached to a specific service point identifier and there is no mechanism to list all of them. An example of this is a customer who receives a Q1 bill and sets up a payment plan for this over 12 months, then receives a Q2 bill and sets up a payment plan for this over 12 months. For Months 3 - 9 there are two payment plans.

Additionally, on an Infosec front. The agreed payment schedules CX language does not include NMI. While it seems logical Basic Energy Accounts scope would be included, this isn't explicitly the case. This CR proposes to introduce data which is not disclosed in the Data Cluster related to the scope.

Finally, as this is now changing to an array of payment schedules the correct path for this endpoint is now GET /energy/accounts/{accountId}/payment-schedules.

Issue 3: Paypal based payments (CR 511 #511 (comment))

While this is following an existing pattern it's unclear why paymentFrequency and calculationType are contained within the payment acquisition method. Wouldn't moving this fields one level up make the overall payload more succinct and allow a direct $ref for the BankingDigitalWalletPayee? This will help with cross-industry data structure sharing.

Issue 4: Unclear isTokenised description (CR 511 #511 (comment))

The language of If true then bsb and accountNumber should not be expected to be included is not binding in any way. Suggest dropping the statement entirely and relying upon bsb and accountNumber descriptions to do the job ("Less is more").

[CDR-API-Stream]

The following is the summary of feedback discussed during Energy MI call on 14th June:

Issue 1: Manual payments via payment schedule-plan (this CR)

No specific feedback was received during the call for this issue.

In response to following @perlboy's comment:

A payment plan may not be attached to a specific service point identifier and there is no mechanism to list all of them. An example of this is a customer who receives a Q1 bill and sets up a payment plan for this over 12 months, then receives a Q2 bill and sets up a payment plan for this over 12 months. For Months 3 - 9 there are two payment plans.

As mentioned before, the intent of this API is not to describe payment plans details, it is to describe how a consumer has elected to pay for a given account or connection points within a given account. As mentioned in Issue 1 comment, the DSB will update the description of the API to ensure the intent is understood.

Issue 2: Multiple payment agreements for a single account

Feedback in the call suggested making servicePointId optional in the proposed structure as there could be account level payment agreement for a single account with multiple connection points. This is incorporated in the updated structure below.

Issue 3: Paypal based payments

The following question was raised:

• Can the proposed digitalWallet can be made a direct $ref to BankingDigitalWalletPayee by moving paymentFrequency and calculationType one level above .

This was considered but not adopted as combining them would create dependency and add constraints to any future changes. The retailers noted they would review and provide any feedback to the digitalWallet structure if required.

Issue 4: Unclear isTokenised description

The following comment from @perlboy's was discussed during the call:

The language of If true then bsb and accountNumber should not be expected to be included is not binding in any way. Suggest dropping the statement entirely and relying upon bsb and accountNumber descriptions to do the job ("Less is more"). This is roughly analogous with BankingTransaction postingDateTime:

The DSB agrees with the above suggestions and will incorporate it in the change.

In response to following @perlboy's comment:

Additionally, on an Infosec front. The agreed payment schedules CX language does not include NMI. While it seems logical Basic Energy Accounts scope would be included, this isn't explicitly the case. This CR proposes to introduce data which is not disclosed in the Data Cluster related to the scope.

The proposed structure does not include NMI so there is no change to CX language required.

Updated Structure

Below is the updated structure with above feedback incorporated. If no further feedback is received, the DSB proposes to recommend the change to the Chair for approval.

{
    "data": {
        "paymentSchedules": [ /// Array of payment schedules
            {
                "servicePointId": "string", //optional- servicePointId for the paymentschedule. If absent, account level payment is assumed
                "amount": "string",
                "paymentScheduleUType": ["cardDebit", "directDebit", "digitalWallet", "manualPayment"]
                "cardDebit": {
                  "cardScheme": ["VISA","MASTERCARD", "AMEX", "DINERS", "OTHER", "UNKNOWN"]
                  "paymentFrequency": "string",
                  "calculationType": ["STATIC", "BALANCE", "CALCULATED"]
                },
                "directDebit": {
                  "isTokenised": true,
                  "bsb": "string",
                  "accountNumber": "string",
                  "paymentFrequency": "string",
                  "calculationType": ["STATIC", "BALANCE", "CALCULATED"]
                },
                "digitalWallet": {
                  "name": "string", // The name assigned to the digital wallet by the owner of the wallet, else the display name provided by the digital wallet provider
                 "identifier": "string", // The identifier of the digital wallet (dependent on type)
                 "type": ["EMAIL", "CONTACT_NAME", "TELEPHONE"] // The type of the digital wallet identifier
                 "provider": ["PAYPAL_AU", "OTHER"] // The provider of the digital wallet
                 "paymentFrequency": "string",
                 "calculationType":  ["STATIC", "BALANCED", "CALCULATED"]
                },
                "manualPayment": {
                  "billFrequency": "string"
                }
            }
        ]
    },
    "links": {
        "self": "string"
    },
    "meta": {}
},

[perlboy]

Firstly, reiterating my comment within the call, I'm finding it a bit difficult to see what the reasoning for merging payment acquisition methods with payment schedule when the schedule components appear broadly universal. The above updated structure is demonstrating the problem with doing so whereby a recipient must now process calculationType and paymentFrequency per method when it has very little to do with how money is received.

An approach to conditionality (using description for additional business rules) was already defined in banking but now the DSB seems to have reinvented the wheel with an inverse pattern. It is unclear why the DSB hasn't been consistent.

A cleaner structure with a fair bit of similarity to banking would instead be:

{
    "data": {
        "paymentSchedules": [ /// Array of payment schedules
            {
                "servicePointId": "string", //optional- servicePointId for the paymentschedule. If absent, account level payment is assumed
                "amount": "string",
                "paymentFrequency": "string", // Mandatory if paymentScheduleUType is cardDebit or directDebit
                "calculationType":  ["STATIC", "BALANCED", "CALCULATED"] // Mandatory if paymentScheduleUType is cardDebit or directDebit
                "billFrequency": "string" // Mandatory if paymentScheduleUType is manualPayment
                "paymentScheduleUType": ["cardDebit", "directDebit", "digitalWallet", "manualPayment"]
                "cardDebit": {
                  "cardScheme": ["VISA","MASTERCARD", "AMEX", "DINERS", "OTHER", "UNKNOWN"]
                },
                "directDebit": {
                  "isTokenised": true,
                  "bsb": "string",
                  "accountNumber": "string"
                },
                "digitalWallet": {
                  "name": "string", // The name assigned to the digital wallet by the owner of the wallet, else the display name provided by the digital wallet provider
                 "identifier": "string", // The identifier of the digital wallet (dependent on type)
                 "type": ["EMAIL", "CONTACT_NAME", "TELEPHONE"] // The type of the digital wallet identifier
                 "provider": ["PAYPAL_AU", "OTHER"] // The provider of the digital wallet
                }
            }
        ]
    },
    "links": {
        "self": "string"
    },
    "meta": {}
},

Issue 2: Multiple payment agreements for a single account
Feedback in the call suggested making servicePointId optional in the proposed structure as there could be account level payment agreement for a single account with multiple connection points. This is incorporated in the updated structure below.

While making this optional is a solution for the problem raised, I reiterate again that the addition of servicePointId appears to be a feature not a requirement with some unintended consequences (see below). I'm unclear why it was deemed necessary to add it when the ask was an array of schedules. I asked specifically whether this had been requested and the answer was that No it had not been. This seems like scope creep on an industry less than 6 months away from the mandated delivery date.

Issue 3: Paypal based payments
The following question was raised:
Can the proposed digitalWallet can be made a direct $ref to [BankingDigitalWalletPayee(https://consumerdatastandardsaustralia.github.io/standards/#tocSbankingdigitalwalletpayee) by moving paymentFrequency and calculationType one level above .
This was considered but not adopted as combining them would create dependency and add constraints to any future changes. The retailers noted they would review and provide any feedback to the digitalWallet structure if required.

Not doing something (or worse still, not copying an existing pattern) because it might impact a future and undefined state is a terrible justification and in this case flies in the face of the Standards own Technical Principle 6:

Technical Principle 6: APIs are consistent
The API definitions across the full suite of APIs should be consistent with each other as much as possible. Where possible common data structures and patterns should be defined and reused.

Finally on this comment:

The proposed structure does not include NMI so there is no change to CX language required.

The proposed structure discloses servicePointId which was not previously disclosed in this scope. I note that the endpoint authorised with energy:accounts.basic:read also does not include NMI but the language includes NMI. On this basis they appear to be considered analogous as far as the Consumer is concerned?

It certainly seems that way because the energy:accounts.basic:read Authorisation Scopes refer to it as Includes simple energy account information basic plan information and service points that are part of the account. while the CX Language refers to it as National Meter Identifier (NMI);. If they aren't analogous why does the CX Language already refer to a NMI in a payload that doesn't have it?

Regardless, a further question comes about. If access has not been granted to a servicePointId listed in the payment schedule (via a payment schedule connected with two servicePointId entries for which only one is disclosed) what should the behaviour be? Further, if a single payment schedule is setup across multiple accounts, should it be repeated for each account? How does a recipient determine if these are two separate payment schedules or a shared one? That matters because it will multiply the apparent payment obligation being communicated.

[agl-cdrprogram]

ssue 2: Multiple payment agreements for a single account (CR 511 comment)

A payment plan may not be attached to a specific service point identifier and there is no mechanism to list all of them. An example of this is a customer who receives a Q1 bill and sets up a payment plan for this over 12 months, then receives a Q2 bill and sets up a payment plan for this over 12 months. For Months 3 - 9 there are two payment plans.

Additionally, on an Infosec front. The agreed payment schedules CX language does not include NMI. While it seems logical Basic Energy Accounts scope would be included, this isn't explicitly the case. This CR proposes to introduce data which is not disclosed in the Data Cluster related to the scope.

Agree to this point.

[CDR-CX-Stream]

why does the CX Language already refer to a NMI in a payload that doesn't have it?

This is a good catch @perlboy - thanks for highlighting it.

We currently refer to NMI in the data language standards for the accounts, billing, and electricity servicepoints data clusters. The intent is to surface NMI where it is shareable in the scope, but if we've incorrectly surfaced this information then we'll do further analysis and consider raising a separate CR to deal with the issue.

[CDR-API-Stream]

servicePointId will be removed from the proposed structure for Issue 2 based on feedback received in MI11 calls and comments within this CR. The updated structure is below:

{
    "data": {
        "paymentSchedules": [ /// Array of payment schedules. Must have at least one entry
            {
                "amount": "string",
                "paymentScheduleUType": ["cardDebit", "directDebit", "digitalWallet", "manualPayment"]
                "cardDebit": {
                  "cardScheme": ["VISA","MASTERCARD", "AMEX", "DINERS", "OTHER", "UNKNOWN"]
                  "paymentFrequency": "string",
                  "calculationType": ["STATIC", "BALANCE", "CALCULATED"]
                },
                "directDebit": {
                  "isTokenised": true,
                  "bsb": "string",
                  "accountNumber": "string",
                  "paymentFrequency": "string",
                  "calculationType": ["STATIC", "BALANCE", "CALCULATED"]
                },
                "digitalWallet": {
                  "name": "string", // The name assigned to the digital wallet by the owner of the wallet, else the display name provided by the digital wallet provider
                 "identifier": "string", // The identifier of the digital wallet (dependent on type)
                 "type": ["EMAIL", "CONTACT_NAME", "TELEPHONE"] // The type of the digital wallet identifier
                 "provider": ["PAYPAL_AU", "OTHER"] // The provider of the digital wallet
                 "paymentFrequency": "string",
                 "calculationType":  ["STATIC", "BALANCED", "CALCULATED"]
                },
                "manualPayment": {
                  "billFrequency": "string"
                }
            }
        ]
    },
    "links": {
        "self": "string"
    },
    "meta": {}
},

Pending any other feedback, the DSB will recommend the above change for Issue 2 and the proposed solutions for issues 1, 3 and 4 stated this comment to the Chair for approval.

[biza-io]

Biza.io supports the proposal without servicePointId. We continue to believe that the payment acquisition method should be separated from the frequency and calculation approaches however given Energy delivery date we will instead seek to raise a CR at an appropriate time for this component.