Clarify and simplify prepayment

[nickevansuk]

Proposer

ODI

Why is this needed?

The explanations of the logic to handle prepayment in the current specification are scatted throughout the booking flows and do not cover all cases: leaving the reader to make assumptions about edge-case behaviour. Additionally the logic itself requires both the Booking System and Broker to implement the same checks, which introduces unnecessary additional implementation complexity.

This proposal centralises the explanation into a single section of the specification, handling all edge-cases, and introduces a prepayment property of PriceSpecification within totalPaymentDue, so that the logic for deciding the overall prepayment status can be implemented once by the Booking System and the result used by the Broker.

It also introduces a new UnnecessaryPaymentDetailsError to cover the case where payment is taken when it is not permitted.

Note this proposal does not alter any behaviour for the cases described in the current specification, and is fully compatible with the existing logic.

Proposal

Booking without payment

If the OPTIONAL prepayment feature of this specification is supported by the Booking System, the following logic MUST be applied by the Booking System to populate the prepayment value of totalPaymentDue in the OrderQuote response of C1 or C2:

acceptedOffers across OrderItems	Booking System sets prepayment value of totalPaymentDue
Any prepayment values are either https://openactive.io/Required or omitted where price values are also not 0	https://openactive.io/Required
At least one prepayment value is https://openactive.io/Optional and the rest are either https://openactive.io/Unavailable or omitted where price values are also 0	https://openactive.io/Optional
In all cases either prepayment value is https://openactive.io/Unavailable or price value is 0	https://openactive.io/Unavailable

If the prepayment property is not supported by the Booking System, the prepayment property MUST simply be omitted in all cases, however the Booking System MUST still handle the payment error conditions.

The following logic MUST be applied by the Broker to determine whether to initiate taking payment from the Customer, and applies whether or not the Booking System supports prepayment:

totalPaymentDue	Broker initiates payment
prepayment is https://openactive.io/Required, or omitted and price is not 0	Always
prepayment is https://openactive.io/Optional	The Customer MAY be given the option, at the Broker's discretion
prepayment is https://openactive.io/Unavailable or price is 0	Never

If payment is not to be initiated based on the above:

• The Broker MUST communicate to the Customer that they are simply reserving a space without payment.
• The Broker MUST NOT accept payment details, attempt payment pre-authorisation, or attempt payment capture.
• The Broker MUST NOT include the payment property in the request to B or P.
• The Booking System therefore MUST NOT include the payment property in the response from B or P, and MUST proceed to create a payment-free Order or OrderProposal.

Free opportunities

Free Opportunities, defined as those with at least one applicable Offer with a price of 0, MUST follow the same workflow as paid Opportunities.

For Offers with a price of 0:

• The prepayment property of the Offer MUST be either https://openactive.io/Unavailable or unspecified.
• The Offer MAY not include priceCurrency.
• If a priceCurrency is not available then Brokers SHOULD communicate "Free" or equivalent when referencing a zero price.

When an Order or OrderProposal involves exclusively Free Opportunities the totalPaymentDue will be 0 regardless of the prepayment property values. In this case, no interaction with a Payment Provider is required, the payment property MAY be omitted at C1 and C2, and MUST be omitted at B or P.

Payment error conditions

At B or P the Booking System MUST produce an error response in the following cases:

• If the payment property is expected in the request (as within totalPaymentDue: prepayment is https://openactive.io/Required, or if prepayment not supported, price is not 0) but not provided, then a MissingPaymentDetailsError MUST be returned .
• If the payment property is provided but not expected in the request (as within totalPaymentDue: prepayment is https://openactive.io/Unavailable or price is 0), then an UnnecessaryPaymentDetailsError MUST be returned.
• If the payment property does not include identifier, then an IncompletePaymentDetailsError MUST be returned.
• If the payment details supplied (e.g. accountId) are not considered valid for reconciliation by the Booking System then an InvalidPaymentDetailsError MUST be returned.

[lukehesluke]

@nickevansuk a suggested revision to the Payment error conditions section. Changes in boldtalics:

Payment error conditions

At B or P the Booking System MUST produce an error response in the following cases:

• If the payment property is expected in the request (as within totalPaymentDue: prepayment is https://openactive.io/Required, or if prepayment not supported, price is not 0) but not provided, then a MissingPaymentDetailsError MUST be returned .
• If the payment property is provided but not expected in the request (as within totalPaymentDue: prepayment is https://openactive.io/Unavailable or price is 0), then an UnnecessaryPaymentDetailsError MUST be returned.
• If the payment property is expected in the request AND the payment property does not include identifier, then an IncompletePaymentDetailsError MUST be returned.
• If the payment property is expected in the request AND the payment details supplied (e.g. accountId) are not considered valid for reconciliation by the Booking System then an InvalidPaymentDetailsError MUST be returned.

to clarify that the latter two conditions only count when payment is expected