PurchaseAPI and failed starts reprocessing

DISCLAIMER

Product Information contained within this document, including technical information and functional specifications, is subject to change without notice. Naviga reserves the right to make any changes to the information in this document at any time without notice. Naviga makes no warranty, representation, or guarantee regarding the suitability of its products and services for any particular purpose.

Intro

Prior to Release 3.14.2, the Newstart flow was using Subscription API which had issues like poor performance (more than 20 seconds), multiple authorizations when auth event fails and user retries, missing support to reprocess events etc. In order to solve all these issues, Subscribe refactored the SubscriptionAPI and named it PurchaseAPI.

The purchase API has two execution parts: synchronous and asynchronous.

Please note that the synchronous part of the flow can be turned off for a consumer application using the Purchase.ProcessSync flag.

This can be useful for LTE. In case Purchase.ProcessSync flag is set to OFF user will get a permanent account number in the receipt

The synchronous part performs the input model validations and successful processing of the key events before showing success to the end-user. The asynchronous events continue to process in the background. In other words, the end-user sees failure on the screen if one of the synchronous events fails. On the other hand, the asynchronous step(s) would fail silently without any notification to the end-user.

A business user or customer service representative should review Event Viewer section of One CSR Portal on a regular basis to view, update, reprocess or close failed events.

Starting from 3.16.0 Release PurchaseAPI must be used for all new starts instead of SubscriptionsAPI.

Also, from 3.16.0, it is mandatory that consumer applications pass on the parameters for the Subscriber component (i.e., at least FirstName, LastName, and Email) in the Purchase API. Clients can achieve this by using either of these options in CMS: Billing Information, Payment Information, or the Independent Address component.

Note updated on July 11, 2023.

Note

1. The Release 3.14.2 covers the refactor for Standard and Complimentary starts for NCS Circ+Payway. The rest of the start flavors and circ systems will continue using SubscriptionAPI. There is a plan in future releases to upgrade those.

2. Starting from the release 3.14.2 onwards Braintree support was added

3. Since the account in NCS Circ gets created as part of the asynchronous events, then the end-user will not see the account number on the confirmation page of the Subscription Panel as well as in the LTE receipt. They would however get this information in the confirmation email.

4. Database occupant lookup was replaced by real-time occupant lookup in NCS circ starting from 3.16.0 onwards. There are two types of lookup: standard and email only (default). Please see the details below:

   • Email Only: If this mode is set up, send Email and Exact Match=true to NCS. We should always expect NCS to return one Occupant.

   • Standard: If this mode is set up, send Email and Exact Match=false to NCS. We might get multiple records. The result set is filtered by First Name, Last Name and Email (all of them should match) and the first occurrence is picked.

   • to switch between the lookup types please use Purchase.GetSubscriber.LookUpStategy setting in mg2control Last changes made July 5th 2022

The standard list of events during a new start

The following table represents events that occur in the purchase API flow.

When using the Synchronous flow, the API returns a success only if all events get processed successfully. However, in the case of an Asynchronous flow, the API returns a success first, and events marked "🗶" occur in the background.

Event ID	Event Name	Description	Sync	Async
62	ADDRSTD	Address Standardization	🗸	🗸
35	AUTHCC	Card Authorization. Processed before STARTSTD creation.	🗸	🗸
3	STARTSTD	Parent Newstart Event	🗸	🗸
140	FINDADDRESSOCCUPANT	Real-time occupant lookup in NCS Circ.	🗸	🗶
1103	CREATESUBSCRIBER	Occupant creation in NCS. New occupant will only be created if no matching occupant was found	🗸	🗶
141	ADDADDRESSOCCUPANT	Address creation in NCS	🗸	🗶
1111	ADDSUBSCRIPTION	Subscription creation in NCS	🗸	🗶
56	CCFUNDCAPTURE	Capture previously authorized funds	🗸	🗶
57	PAYMENTNEWSTART	Inform Payment in NCS	🗸	🗶
58	UPDATEPAYMENTTRAN	Update Transaction in Payway to store NCS info	🗸	🗶
1033	LINKOWNER	Creates the association between the Newstart and the Registration	🗸	🗶
954	CHGEMAILPREF	Subscribes the new subscription to the set of Preferences that are configured as default preferences.	🗸	🗶

Note updated on July 11, 2023.

View, Update, Reprocess, Close one or more failed events of New Start

The subscriber concierge admin displays the failed events. When the user process the failed event, the Subscribe API process all failed events. The business user will need to check why the start failed and fix it before reprocessing.

Reprocessing workflow

High-level flowchart of the reprocess flow

Example

To understand how the reprocessing works let’s follow this example:

1. The user submits the form in the consumer application

2. PurchaseAPI accepts the Input model (everything passed: Validations, Address Standardization, Auth, etc.) and creates STARTSTD event

3. PurchaseAPI returns a successful response back to the consumer application and triggers the asynchronous steps behind the scenes

4. PurchaseAPI fires CREATESUBSCRIBER as part of the asynchronous steps.

5. NCS Circ returns an error because the Last name contained a special character that is not supported. As a result, CREATESUBSCRIBER is marked withevent_status=3(failed)

To reprocess this Newstart event, first we need to make the necessary changes to avoid the issue to happen again. In this case, we need to update the last name in STARTSTD event to remove that special character that caused the failure.

Once that’s fixed, the Reprocess endpoint can be called.

1. PurchaseAPI will get the events of the previous execution. In this example, only CREATESUBSCRIBER with event_status=3 will be found

2. PurchaseAPI will determine this step needs reprocessing. As a result, it will create a new CREATESUBSCRIBER event with the new Event Log data from STARTSTD event

3. NCS Circ will succeed this time and the event will be marked withevent_status=2(success)

4. PurchaseAPI will update the previous failed event from event_status=3 (failed) to event_status=11 (reprocessed)

5. Purchase API will continue the execution of the rest of the asynchronous

   steps

Reprocessing in One CSR Portal

To view, update and reprocess failed starts in One CSR Portal user should go to Event Viewer section and set the filter to display Failed New Starts while processed events should be hidden.

Please note that 'View event viewer' toggle of the 3 STARTSTD event should be set to YES to view this events in the grid. This flag can be found under Event management -> Event types

Subscription information -> Event viewer

Filtered results set will be displayed in a grid where a CSR can see event information like Event ID, Event create date, Account Number, Error Message etc. In the Error message column you will see the information about the error that caused the start to fail. Same information can be found in the detailed information about the event.

Error message

Please note that the Account Number displayed in the grid is the temporary account number. If the start will be reprocessed successfully then this Account Number will be replaced by a permanent one.

To view the information about the event, update it, and reprocess please click 'Edit' button. The button will open a pop up with detailed information about the event

The fields below are available for an update before reprocessing the start, it’s advised not the update other fields

• Delivery Address, including City, Code and Unit Number

• Billing Address, including City, Code and Unit Number

• Email

• First name

• Last name

Detailed event information

Update an event

1. Edit field(s)

2. Click the 'Update' button

3. Refresh the page and confirm data update is successful

Reprocess

1. Make sure event updates, if needed, are complete

2. Click the 'Reprocess Newstart' button

3. View the success message displayed

The reprocessing creates a new child event with success status (id 2). The status of the previously failed event gets changed from failed to reprocessed (3 to 11). The reprocessed events do not appear in the event viewer

Please note that 'Allow resubmit' toggle of the 3 STARTSTD event should be set to YES to reprocess new start. This flag can be found under Event management -> Event types

A CSR can also click 'Mark as closed' button in case the failed start has been reviewed and the decision was made not to reprocess the event. In this case, the event will be updated with the event_status= 9(closed) and no longer displayed in the list of failed starts.

Main failure scenarios

Bad user data

These are the scenarios when the failure is caused by the bad data entered by user on Subscription Panel. The most common case in this category is special characters in user name or surname, e.g. John Doe's . For these types of failures the best practice is to update the data in the Event viewer and reprocess new start.

To update the first and/or last name please open the Address info tab and update Billing first name and/or Billing last name field(s). Then click Update button and Reprocess.

Bad Solicitor setup

This category covers all the failures caused by bad offer setup in Solicitor Concierge like wrong rate code and other billing codes. This data cannot be fixed via One CSR Portal so the CSR has to go to Solicitor Concierge, fix the offer setup and then reprocess the new start via Event Viewer.

There is an edge case where the business user has made major updates in offer data of the failed start in NCS Circ like billing codes, price, divisions etc. The reprocessing of failed starts will not work in this case as the data wouldn't match. It is advised to close the failed start and ask the customer to create a new start.

Third party issues

In this category we have the issues related with payment systems, APIs etc. Updating the new start data via One CSR Portal will not help in this case. It is recommended to make an attempt to reprocess (it will be successful if the third party issue is resolved). Or to close the failed start and ask the customer to create a new one.