Reduce number of calls for critical path

[nickevansuk]

Source

Netpulse

Feedback

While booking a class, right now we have to do several API calls:
a) When no purchase needed for the booking: create order -> add class to order -> get order -> complete order
b) When purchase is needed: create order -> add class to order -> get order -> add payment -> complete order (not supported by Netpulse standard API flows)

It would be great if we could do the above mentioned in just one API call at least for the case a). Since our app allows users to book a class in just one click, the more API calls involved, the longer user is waiting for a booking result (and also there might be unexpected errors that break the whole API requests chain).

[peter-dolkens]

I think there needs to be two approaches to the Booking API spec.

• One, for single-purchases, which would follow a far simpler create > pay flow
• One, for multi-purchases, which follows the create > add > pay > complete flow

I think the booking spec should be able to indicate which of these flows are available, as not all systems will support the more complex multi-purchase flow, or have the ability to reserve capacity until completion.

I don't think it would be too hard to create aliases in implementations that support the multi-purchase flow, to also support the single-purchase flow.

The multi-purchase flow would then become used only by the more advanced systems.

[nickevansuk]

Totally agree with this, and bringing in feedback from a review of Google Reserve, please see the following proposal which effortlessly satisfies these additional constraints, by using a create+pay flow for all use-cases, with an optional check/create+pay for multi-purchases:

Revisiting the function and importance of the "lease"

• Google has moved away from an individual session "lease+book" pattern in V3 of the Reserve API, and towards an Order-based approach which matches ours.
• Interestingly they have also moved away completely from the idea of an anonymous lease holding a spot before payment, and actually make use of the payment processors' commonly available two-step payment flows. Details on this below.
• Just as Google has dropped anonymous leases, the latest version of the OA spec has not included anonymous lease behaviour at all, which means we can greatly simplify the implementation, as in the current implementation the user could still experience "i'm sorry, the space has been taken while you were entering your payment details" error.
• Also note, for hard-to-get spaces in both the current and proposed implementations, brokers could easily implement stored customer and card details within a profile to allow for an "1-click-booking" button, which is a likely a better solution than attempting to hold the space with all the related complexity on the booking system side while payment details are being entered.
• The great thing about an Order-based approach over a Reservation-based approach is that a single-item Order is the same as a single reservation, so the simple-case requires the same number of calls, if we can remove the need for a confirmation call for free events.

Revisiting the Problem Statement

Because both payment and booking must succeed, a two-phase commit is required on at least one side to avoided unnecessary reverting transactions. Specifically, given that the "confirmation" of either side is likely to trigger emails to the user, we prefer "reserve+commit" to "commit+revert" approach, as the former allows error cases to be handled without needing to send "cancellation" emails.

Solution Options

Two approaches in common use, which represent the two-phase commit happening on either the booking system or payment provider side, respectively.

A) Two-step booking

1. Lease Order
2. Capture Payment
3. Book Order

B) Two-step payment

1. Auth Payment
2. Book Order
3. Capture Payment

The current spec uses (A), this proposal suggests (B) as a simpler approach.

Solution Proposal

Given that all major payment providers already support (B) (and indeed according to CardStream p. 108 this is the more common approach), we can simplify implementation for the many OpenActive booking systems by leveraging this.

This changes our flow from:

1. Create Order, lease OrderItems and receive totalPaymentDue
2. Capture Payment
3. Complete order with Payment taken

And instead becomes:

1. Booking System: Check Order (see OrderQuote #87), and return totalPaymentDue (can be done without including customer details, and may not be needed if the feed contents is reliable)
2. Payment Provider: Authorize totalPaymentDue amount
3. Booking System: Create Order request including Authorised Amount and customer details, book OrderItems, return totalPaymentDue (if less than Authorised Amount, otherwise error)
4. Payment Provider: Capture Payment for totalPaymentDue

Note that in the unlikely event that the amount that the user is expecting to pay increases from what they have seen at the "Check Order Availability" stage of booking, the user needs to be notified of the new price and the payment reconfirmed anyway, and the error potentially returned from step (3) above fits with this - so there is not a case where this new flow limits any desired behaviour.

Such a simplification also reduces the number of calls on the critical path to an absolute minimum. If the broker is already confident in the price (from the Opportunity API, or directly from the open feed), they can simply authorise that amount with the payment provider, and skip step 1 - hence the minimal case here requires just a single API call.

The other advantage of this is that it doesn't require any type of lease state on the booking system side, which simplifies the simple implementation case.

Additionally, for future "shopping basket" usecases, as a user adds items to their basket, a single call can be made to check order availability for the basket each time the basket is updated, so the user can be notified if anything within the basket is no longer available. This proposal is effectively scrapping the idea of incrementally adding items to an order before paying it, and instead add all items at the point of order creation. This also makes an order immutable during the booking process, and reserves mutability for post-order-completion item cancellation.

Finally for the most critical error case - interruption before final commit ("paid but not booked" in the existing spec) - this new proposal's equivalent ("authed and booked but not captured") can be easily monitored for MVP scenarios using the payment providers own tooling (e.g. in Stripe the report https://dashboard.stripe.com/payments?captured=false returns all authed-not-captured charges), and the error can be recovered easily by simply capturing the payment manually via the Stripe dashboard within 7 days.

Another advantage is that for free bookings, step (3) can be used in isolation, creating the simplest possible flow.

[nickevansuk]

The calls required to complete any booking have been rationalised to just three for all cases: C1, C2 and B. The reason that C2 and B alone are not sufficient is due to the potential for explicit consent being required before the customer's details can be provided to C2.

They are best summarised as:

• C1: Check availability and get full information about items being ordered and details that must be supplied
• C2: Dry run of the booking, to confirm all details being submitted are valid
• B: The actual booking