e-Forms Payment Process Documentation - MITA1 · Public eForms Payment Process Documentation Page i Document Control Information 01. Document reference eForms-TMP-PaymentProcessDocumentation-v0.1.doc

Malta Information Technology Agency, Gattard House, National Road, Blata l-Bajda HMR 9010 Malta Telephone: (+356) 21234710 Facsimile: (+356) 21234701

Web Site: www.mita.gov.mt

e-Forms Payment Process Documentation

Date: 05/03/2012

Version: 1.0 Unit: eGov Architecture Department: eGov DEO

Public

Public eForms Payment Process Documentation

Page i

Document Control Information

01. Document reference

eForms-TMP-PaymentProcessDocumentation-v0.1.doc

02. Document type

Procedure

03. Security classification

Public

04. Synopsis

Document brief description

05. Document control

Author Change controller Distribution controller

Marie Rizzo eGovernment Architecture Team

eGovernment Architecture Team

06. Modification history

Version Date Comments

Draft 0.1 24/02/2012 Draft version for internal review

Version 1.0 05/03/2012 First version for release


File Name: Security Classification: Page:

eForms-TMP-PaymentProcessDocumentation-v1.0.doc Public 1 of 11

Table of Contents

DOCUMENT CONTROL INFORMATION .................................................................................................................................. I

TABLE OF CONTENTS.............................................................................................................................................................1

01. INTRODUCTION ..........................................................................................................................................................1

02. SCOPE .........................................................................................................................................................................2

03. THE PAYMENT SUB-PROCESS .................................................................................................................................3

03.1 ESCALATING THE PAYMENT .........................................................................................................................................3 03.2 DIFFERENT TYPES OF PAYMENT ..................................................................................................................................4

03.2.1 MyBills Payments ............................................................................................................................................4 Example of the response for a failed payment..................................................................................................................5 Example of the response for a successful payment..........................................................................................................5 03.2.2 Manual Payments............................................................................................................................................6

03.3 RETURN .....................................................................................................................................................................8 03.4 IMPLEMENTING THE PAYMENT SUB-PROCESS...............................................................................................................8

03.4.1 Main Process amendments .............................................................................................................................8 03.4.2 The Payment Amount Due ..............................................................................................................................8 03.4.3 Using the Payment Sub-Process.....................................................................................................................9

04. FURTHER ASSISTANCE...........................................................................................................................................12




01. Introduction

The Payment Process is a pattern of how the payment should take place within the eforms workflows. The Payment Process is as a self-contained sub-process which can be used as a task within any process requiring a payment. This document will describe how the Payment Sub-process can be configured and used with the use of examples.




02. Scope

This document describes the Payment sub-process and how to configure the main process so that they interact. The main constituents of the sub-process will be described briefly. However, detailed analysis of the payment code or the templates used is out of scope of this document.




03. The Payment Sub-Process

For ease of explanation, the sub-process has been divided into three separate areas; a.) Escalating the payment: remind applicant if the payment is not performed within a day b.) The myBills payment area interact with myBills Hosted Payment Page (HPP) c.) The manual payment area manual workflow for the cash office (personnel in charge of

receipts) to confirm that an indirect payment was received 03.1 Escalating the Payment

When an eForms workflow is routed to the payment page, the process will remain on hold unless the payment actually takes place. The process may remain on hold in situations such as when:

• the user did not make the payment; or • his payment was rejected and he is expected to try to pay again,

Escalation kicks in if the process remains on the payment task for one day,




During escalation, the process will send an email to remind the user that he is required to perform a payment. The email is configured as follows (refer to section 3.4 Using Payment Sub-Process to learn how to configure fields in the main process to be used by the payment sub-process):

• The email address is configured as a field in the main process. • The email body is a standard message and is contained in the parameter store. A developer

may override the parameter for a particular form.

03.2 Different Types of Payment

The Payment process caters for two categories of payments;

1.) Payments made using myBills 2.) Manual Payments, which comprise of cheques, bank transfers and internet banking.

03.2.1 MyBills Payments

MyBills payments make use of the myBills payment service, and, as such, do not require manual verification of the payment. After the submission of the Payment Form, the process will check whether the payment affected was a myBills payment or a Manual payment. Upon clicking on the submit button, the myBills HPP will open up in a lightbox, prompting the applicant to insert his/her card details.

The applicant can proceed with the payment and the result will be displayed in the same lightbox. Two sample messages, below, show a payment that has failed and a payment which is successful.




Example of the response for a failed payment

Example of the response for a successful payment




The applicant is expected to close the lightbox in order to proceed with the process. If this doesn’t occur within a few minutes, the lightbox will close automatically and submit the payment form. From then on, the payment process can continue with the payment verification. The process will then run a script that will verify that the payment was made. If a payment is found, whether authorised or rejected, the payment status is updated accordingly in the process’ output field and the sub-process completes. If the payment is not found, then a delay is triggered and the verification retried. This is done either until the payment is found or until the timeout expires, at which point the payment is treated as failed and the status updated accordingly.

The result status is stored in a field called escalationEmailAddress. Please read section 3.4 Using Payment Sub-Process to learn how to configure fields in the main process to be used by the payment sub-process. Important: The Payment form will submit when the lightbox is closed even if a payment is not affected. In such a case, the payment will go through the verification, and upon timeout, return to the user’s mailbox so that the user may attempt again to pay. 03.2.2 Manual Payments

In the case of manual payments, the verification process has to be performed manually by a backend user, which we shall call the Cash Officer. The process, upon determining that the payment made was a manual payment will check whether the payment was already done and verified. This is required to filter out payments which were already made but for some reason the payment process is executing for a second time. If the payment is found, then the status is simply updated and the payment sub-process completes. If the payment is still to be verified, then the following will occur:

a.) The timeline status needs to be updated b.) An email is sent to the workqueue c.) The Cash Officer needs to verify or reject the payment




The Progress Status task is responsible for updating the process timeline. This will enable the process timeline to be correctly displayed in the Web Portal. This can be configured by adding the process status number to a field called manualPaymentStatusCode in the main process. The workqueue must be informed that they (the Cash Officers) have a payment to verify. The name of the workqueue can be configured by adding a field called manualPaymentWorkQueue which should contain the name of the workqueue to the fields in the main process. The name of the Liquid Office work queue should follow the standard convention XXXnnnCashOffice. Where XXXnnn reflects the service unique description. The payments reconciliation report uses this convention to determine the access rights to transactions and accounts. The Cash Officer would then be able to manually confirm or reject the payment using the Manual Payment Verification Form displayed below.

Depending on the Cash Officer’s selection, the process will update the status of the payment and the sub-process will complete, giving control back to the main process.




03.3 Return

Upon completion of the sub-process, the main process will resume operation. Please read the next section which details how the sub-process should be set up. The main process would then need to retrieve the payment status which was populated by the sub-process. This can be done by simply retrieving the value of the field from the process, provided that the sub-process was configured as embedded. Read more about this in the next section. 03.4 Implementing the Payment Sub-Process

03.4.1 Main Process amendments

In order to implement the Payment Sub-Process, the following import statements and variables need to be added to the main process.

Import statements which need to be added to the Main Process import mt.gov.forms.Payment;

import mt.gov.forms.Parameters;

import java.lang.String;

import java.text.SimpleDateFormat;

import mt.gov.forms.FormUtils;

String paymentDateFieldName = "hdnDatePaymentVerified";

Calendar dtStart;

03.4.2 The Payment Amount Due

The payment amount is loaded from the database when the Payment Form is loaded rather than from the hdnAmountDue. This is a security feature so that no one tries to inject a bogus amount due from the form itself. By default, the Payment Form will load the Deposit Amount as configured on the process from the Payment Details tab in the Suppliers Portal. In the case you need to calculate the payment amount dynamically (e.g. according to user selection), a new amount can be inserted in the database from the process. In either case, the following code should be inserted in the Script Task preceding the payment sub-process so that the final payment amount is written to the database and can then be used in the payment process.

Code to be inserted in the Script Task preceding the Payment sub process

void enteredActive(State state) {

// we need to perform some calculations on the payment amount and store it in

the database

// get payment from database and store it in the hidden field

String amount = Payment.getPaymentAmountDueFromDB(thisProcess);

// do some calculation to get the final amount due.

// amount = “100”;




// write the amount to the database

Payment.saveAmountDue(thisProcess, amount);

// write payment into hidden field

thisProcess.setFieldValue("hdnAmountDue", amount);

}

03.4.3 Using the Payment Sub-Process

The logic within the Payment Sub-Process is self contained and, as such, can be used as a plug-and-play component inside a main process. This section will illustrate with a simplified example how the payment can be set-up. Example Scenario: Consider the following scenario. A citizen needs to fill in an application to apply for a service. Upon submitting the form, the total amount that he has to pay needs to be calculated, and the payment form should be displayed. The citizen should then be presented with a number of different payments types from which to choose. The citizen will make the payment and the payment will be verified. Upon successful payment, the citizen will be informed by email that his application was successful. If the payment was not successful and the citizen was logged into the system, he should be allowed to re-attempt the payment. Otherwise, if the citizen was using an unauthenticated account, he should be notified by mail that the payment has failed and that his application will not proceed. The above scenario can be easily converted into a timeline, as seen in the diagram below. There is no need to cater neither for different payment types, nor for the payment validation, since these are managed within the payment sub-process.

The payment sub-process requires two input parameters, which relate to manual payments and a third input parameter for the escalation part of the process:

a.) The Status Code to which the process timeline should progress when an applicant opts to pay through one of the manual payment options.

b.) The name of the Work Queue which will be in charge of verifying a manual payment. c.) The email address for the recipient of the payment pending notification email




These three parameters should be configured as fields in the Process Properties of the main process:

Figure: Fields tab in the Process Properties with the inputs and output fields of the payment sub-process highlighted.

Name Parameter Type Type Initial Value

manualPaymentStatusCode Input Text Should contain the status code to be used when moving to the Manual Payment Verification stage.

manualPaymentWorkQueue Input Text Should contain the name of the Work Queue responsible for performing the manual payment verification

escalationEmailAddress Input Mnemonic Should contain the mnemonic of the field containing the email address of the applicant

paymentStatus Output Text Should be left empty.

The sub-process also returns the result of the payment, i.e. whether the payment was successful or not. This output parameter is also configured as a field in the Process Properties of the main process. The fields created in the main process can be shared with the payment sub-process by configuring the sub-process as embedded. This can be done by opening the sup-process task properties dialog and select the “Embed Sub-process instance in Main Process” option from the Sub-process tab. This can be seen in the figure below.




At this point, the sub-process is configured within the main process. The only thing left to be done is to read the result of the payment from the main process and, hence, decide whether to carry on with the process or else iterate, asking the user to make a payment again in the case of a failed payment. In this example, the check can be performed either when the sub-process is completed (enteringDone event) or else when the “Retry Payment” branch becomes active (enteringActive event). In order to check the outcome of the sub-process, the output field needs to be read. Below is an example script that

• retrieves the paymentStatus field from the process; • checks whether the payment was authorised, and • based on the result, decides which branch in the process to take.

void enteringDone(State state) { // retrieve the paymentStatus field String paymentstatus = thisProcess.getFieldValue("paymentStatus"); // check whether the payment was authorised by t he subprocess or not. Set the default // path of the “Rety Payment” branch according t o the result if ((paymentstatus.equalsIgnoreCase("authorised"))) { thisProcess.getTaskByName("Retry Payment").setDefaultSelectedIndex(1); } else { thisProcess.getTaskByName("Retry Payment").setDefaultSelectedIndex(0); } } What happens outside the sub-process is a business decision. In this case, if the payment is successful, the process will send an email to the applicant, informing him that the payment was accepted. Otherwise, if the payment was rejected, it checks whether the user was authenticated or not. When a user is authenticated, the Payment sub-process can be looped, and the user is asked to re-open the payment form from his mailbox and resubmit the payment. An anonymous user does not have a mailbox. For this reason, if a user is unauthenticated, the process sends an email informing the unauthenticated user that his payment was rejected and that he’ll have to resubmit the application again.




04. Further Assistance

If you have a question about this eForms Component guide, or you encounter an issue, please

contact us on [email protected].

Documents

e-Forms Payment Process Documentation - MITA1 · Public eForms Payment Process Documentation Page i Document Control Information 01. Document reference eForms-TMP-PaymentProcessDocumentation-v0.1.doc