PASI EPS2 Payment Reconciliation

F9663 - CF - is this document an overview?

The purpose of this document is to provide an overview of the process used in PASI to reconcile payments with EPS2 (Electronic Payment System) for myPass services that requires payment collection. The following myPass services incorporates a payment collection process:

Overview

If a service on myPass has an associated cost, a user generally must submit the payment before it is submitted to PASI for processing. For example, a Transcript Document Order must be paid for in full before it is prompted to a status of Ordered.

For connected students and 3rd party users on myPass, the payment must be made using EPS2 (Electronic Payment System), which is the common electronic payment system (EPS) used by applications in the ministry to collect payment. EPS2 uses https://www.bambora.com/en/ca/ to collect payment from users.

When a user indicates that they would like to proceed with payment on myPass, the Payment Item the user is paying for is placed in a “Payment Pending” status. A PaymentPending status indicates that a payment session has been started in EPS2, but myPass has not received an indication from EPS2 that the payment process was completed.

In most cases, once a user completes the payment process on EPS2, myPass will receive a response from EPS2 and update the Payment Item accordingly. However, there are scenarios where the response fails to return to myPass. This can be caused by the user abandoning the payment process in EPS2/Bambora (e.g. by closing the browser window), or myPass has lost connection with EPS2. Hence, a reconciliation process is needed to determine the statuses of these outstanding Payment Pending orders/requests, so that PASI can update them accordingly.

I think these bullet points don't belong in this document F9663 - CF

  • For more information on the Document Order statuses and lifecycle, please refer to the Document Orders Overview.
  • For more information on how connected students/3rd party users (referred to as “myPass public users”) uses myPass to submit Transcript Document Orders, please refer to the Order a Transcript overview.
  • For more information on the Exam Registration Request statuses and lifecycle, please refer to the Diploma Exam Registration Management Overview
  • For more information on how connected students/3rd party users uses myPass to submit Diploma Exam Registrations, please refer to the Register for a Diploma Exam overview.
  • For more information on the Diploma Exam Rescore statuses and lifecycle, please refer to the Diploma Exam Rescore Management
  • For more information on how connected students/3rd party users uses myPass to submit Exam Rescore Request, please refer to the Create Rescore Request - Public (myPass) overview.

Electronic Payment System Invoices

PASI, using the Submit Invoice service, creates an Electronic Payment System Invoice with a Processing Status of Initiated (Invoice Processing Status) anytime a user launches EPS2 (Electronic Payment System) to pay for a service. The Invoice Identifier serves as the identifier for the payment session when communicating with EPS2.

The Processing Status is updated accordingly along with the Payment Item if PASI successfully obtains an End State response from EPS2.

While a particular payment item can have multiple Electronic Payment System Invoices (if user were to launch EPS2 to pay for the item multiple times), each payment item should only have at most one Initiated Invoice at any time.

Possible EPS2 Responses on Payment Status

During reconciliation, PASI will receive one of the following responses from EPS2 regarding the status of an Electronic Payment System Invoice:

  1. Approved (End State)
  2. Declined (End State)
  3. Lost - no finalized transaction found and session has timed out (End State)
  4. In Progress - no finalized transaction found and session has not timed out

For a payment item to be brought out of a PaymentPending status, the associated Invoice must have one of the three End States; otherwise the payment item remains in Payment Pending status.

Possible Validation Errors from EPS2

EPS2 will perform validation on the request from myPass before determining the status of the payment; if the request fails validation, a validation error will be returned instead of one of the 4 possible responses listed in the Payment Reconciliation Process section below. The following are the possible validation errors that may be returned from EPS2:

  1. Payment for the given Invoice ID is not found
  2. More than one payment is found for the given Invoice ID

PASI Reconciliation Process

Triggers

Payment reconciliation can be triggered by one of two methods. Regardless of how it is triggered, the process to reconcile Payment Pending Payment Items is identical.

Method 1 - User-triggered

Can also be called User Reconciliation.

Reconciliation is triggered automatically as soon as one of the aforementioned pages loads. Depending on the result of the reconciliation, user may be given an option to manually trigger the reconciliation process to run again.

Reconciliation runs only on the payment item(s) that the Education Account user has created that is currently in the “Payment Pending” status. The associated Electronic Payment System Invoice that has a status of Initiated will be the invoice selected for reconciliation in the process.

Method 2 - Scheduled task

Can also be called Scheduled Reconciliation.

A scheduled Reconciliation task in PASI will run the reconciliation process regularly. In all environments, the process will execute once every 46 minutes in all environments if the configuration setting Core.PaymentReconciliationEnabled is set to true.

The reconciliation process has been updated to attempt to reconcile invoices for the following discrepancies:

  1. Invoices that are NOT in a final state which have exceeded the Reconciliation Timeout of 45 minutes.
    1. Not in a final state refers to ElectronicPaymentSystemInvoices that have an InvoiceProcessingStatus = Initiated
    2. Reconciliation Timeout is a configurable value in web.config named Core.PaymentReconciliationTimeoutInMinutes, currently it is set for 45 minutes
  2. Invoices that ARE in a Final state and therefore do NOT have an InvoiceProcessingStatus in an Initiated state AND one of the following:
    1. DocumentOrder Reconciliation
      1. Are associated with Document Orders having an OrderStatus = PaymentPending
      2. Document Order is NOT deleted
      3. Associated invoice has exceeded the reconciliation timeout
    2. ExamRegistrationRequest Reconciliation
      1. Are associated with Exam Registration Request having a RequestStatus = PaymentPending
      2. Exam Registration Request is NOT deleted
      3. Exam Registration Request RequestExpireUtcTime that has expired
    3. ExamRescoreRequest Reconciliation
      1. Are associated with Exam Rescore Request having an RescorePaymentStatus = PaymentPending
      2. Exam Rescore Request is NOT deleted
      3. Associated invoice has exceeded the reconciliation timeout
Student Messages -Outstanding/Pending Payments
  • If the Scheduled Reconciliation process (Method 2), determines and set the status of a Payment Item to 'Payment Not Received' then PASI will send a message 1) to inform the student that the payment for their Payment Item was unsuccessful. The Following are the 3 Payment Items that PASI sends messages to the user.

Information Consumed

  • For user reconciliation, the reconciliation process will only look at the Electronic Payment System Invoices created by the Education Account user that has a status of Initiated.
  • For scheduled reconciliation, the task will select a list of Electronic Payment System Invoices with status = “Initiated” status that has a Last Updated Date/Time that is 45 minutes or more in the past.
    • The 45+ minute window was added to avoid collisions with users currently interacting with myPass/EPS2 to pay for their orders.
  • If for any reason the Reconciliation process finds an Invoice with an ID that doesn’t exist in EPS2, or it is duplicated in EPS2, the Invoice in question is ignored

Processing Rules

Invoices for Document Order

  1. For each Document Order Invoice that needs to be reconciled, determine the status of the Invoice from EPS2
    1. When EPS2 returns with a response, update the Document Order using the Construct Document Order (System Service) Service (if needed) as documented below.
Information Produced
If EPS2 return the status ofUpdate Document Order to
Approved
  • Status = “Ordered”
  • Payment Transaction ID = Payment ID returned from EPS2.
  • Ordered Placed Date = {current date/time}
    • Amount Collected = Total Amount of the Order Item
  • For the Electronic Payment System Invoice the user has just paid:
    • Processing Status = Successful
Declined
Lost
In Progress(No Updates)
Validation Errors
(see Possible Validation Errors from EPS2)

Treat as Lost status:

An error will also be logged for the validation error (see Logging Validation Errors)

{Error}
(that are not Validation Errors)
(No Updates)

Invoices for Exam Registration Request

  1. For each Diploma Exam Registration Request Invoice that needs to be reconciled, determine the status of the Invoice from EPS2
    1. When EPS2 returns with a response, update the Document Order using the Submit Diploma Exam Registration Request Service (if needed) as documented below.
Information Produced
If EPS2 return the status ofUpdate Diploma Exam Registration Request to
Approved
Declined
Lost
In Progress(No Updates)
Validation Errors
(see Possible Validation Errors from EPS2)

Treat as Lost status:

An error will also be logged for the validation error (see Logging Validation Errors)

{Error}
(that are not Validation Errors)
(No Updates)

Invoices for Diploma Exam Rescore Request

  1. For each Diploma Exam Rescore Request Invoice that needs to be reconciled, determine the status of the Invoice from EPS2
    1. When EPS2 returns with a response, update the request using the Submit Diploma Exam Rescore Request Service (if needed) as documented below.
Information Produced
If EPS2 return the status ofUpdate Diploma Exam Registration Request to
Approved
  • Payment Status = “Payment Received”
  • Payment Transaction ID = Payment ID returned from EPS2.
  • Amount Collected = Total Due
  • For the Electronic Payment System Invoice the user has just paid:
    • Processing Status = Successful
Declined
Lost
In Progress(No Updates)
Validation Errors
(see Possible Validation Errors from EPS2)

Treat as Lost status:

An error will also be logged for the validation error (see Logging Validation Errors)

{Error}
(that are not Validation Errors)
(No Updates)

Logging Validation Error

If a Validation Error was returned from EPS2, a Warning Message will be logged in PASI as follows:

  • Business Error from EPS2 while reconciling Invoice Id: {InvoiceID} * Payment Resolved to Lost *, Error Message: {EPS2 Validation Error Message}

Performance Counters

  • PaymentReconciliationProcess.Periodic Payment Reconciliation Process
    • Stopwatch which will begin timing from the point the reconciliation process begins for all Incomplete invoices currently available and stop once the entire batch has completed. (Total time for the process to complete)
  • PaymentReconciliationProcess.IncompleteInvoiceProcess
    • Stopwatch which will time the reconciliation process for each incomplete invoice to be processed individually. (Total time for each individual invoice to be processed)
  • PaymentProcessor.ReconcilePayment
    • Success/Failure flag reporting whether or not the individual IncompleteInvoiceProcess was successful or not for a specific Invoice.
  • PaymentGateway.GetElectronicPaymentSystemInvoice for (Transcript | Exam Registration | Rescore Request)
    • Success/Failure flag reporting whether or not the system was able to retrieve a specific ElectronicPaymentSystemInvoice from the database using the associated SourceOrderType and SourceOrderId.
  • PaymentGateway.TryGetElectronicPaymentSystemInvoiceById
    • Success/Failure flag reporting whether or not the system was able to retrieve a specific ElectronicPaymentSystemInvoice from the database using the associated ElectronicPaymentSystemInvoiceId.
  • PaymentGateway.GetBillingInformationById
    • Success/Failure flag reporting whether or not the system was able to retrieve a specific BillingInformation record from the database using the associated BillingInformationId.
1)
PED send_message API is used to send message to the student