Polling

Some payment fields redirect back to your form before the transaction has been fully processed. This means the user ends up back on your site and the form then has to poll the provider to find out if the payment was successful or not.

This is currently the case for the Bottomline, Capita Paye.net (which includes a second action field) and Civica Estore fields.

This documentation provides an overview of the functionality, example forms called BOTTOMLINETEST, PAYEDOTNET360TESTFORMHELPERVARS and CIVICAESTOREEXAMPLE should have been installed with the payment fields.

Form Design Overview

Unlike most payment action fields, which are added to the final page of a form, "polling" fields need two additional pages to be added following the usual "submit" page.

Submit Page

The submit page will be the last page a user interacts with directly. It may be the "final" page of a multipage form, or a single page form. It's the one that has the payment field on it and will redirect the user to the payment provider.

Wait Page

Users are returned to the wait page once they have attempted their payment on the payment portal.

Context variables (the names of these vary per provider) will indicate at this point whether checkout was completed, whether it was cancelled, or if an error occurred. If successful, the page will enter a wait state until it receives the final notification from the payment provider that processing has completed. If the user cancelled checkout or an error occurred then suitable messages can be displayed here.

Next Button

A next button should be placed on the page and hidden by the page initialisation handler. This button will be triggered automatically once we've received notification from the payment provider. It's also good to practice to include some additional text on the page because should JavaScript be disabled the button will be visible (necessarily so, since without JavaScript the user will need to manually click it to finish).

Page Client Init Handler

The Wait page should have an initialisation handler function which checks the _COMPLETE and _RECEIVED context variables (you'll need to use form variable fields to get the context variables and store them for use clientside), and displays the content of the _MESSAGE context variable (again, store this in a form variable field).

If _COMPLETE is false, an error has occurred (or checkout has been cancelled) and so the form should advance no further. The _MESSAGE will contain the text from either the "Cancel Message" or "Error Message" properties (whichever is applicable) and so should be displayed to inform the user.

If _COMPLETE is true, the form will need to enter a wait state until the final notification message is received from the provider. This is achieved by setting a timeout to call helper.triggerActionButton every 5 seconds. This timed resubmitting of the page causes the form skeleton to re-check whether the notification has been received, giving it a chance to advance to the next page if it has or redisplay the current one if it hasn't.

Example Page Client Init Handler using Civica Estore:

function(helper, pageName, pageInstance) {
    helper.hideField("BUTTONS");
    if (helper.getVariable("CIVICACOMPLETE") == "true") {
        // Process seemed to complete ok
        helper.hideField("ERROR");
        helper.showBusy("WAITING");
        if (helper.getVariable("NOTIFICATIONRECEIVED") == "true") {
            // Notification already received; skip straight to the next page
            helper.triggerActionButton("NEXT");
        } else {
            // Wait for notification
            helper.setFieldValue("WAITINGTEXT", helper.getVariable("CIVICAMESSAGE"));
            setTimeout(function() {
                helper.triggerActionButton("NEXT");
            }, 5000);
        }
    } else {
        // Error occurred
        if (helper.getVariable("CIVICAMESSAGE") != "") {
            helper.setFieldValue("ERRORTEXT", helper.getVariable("CIVICAMESSAGE"));
        }
        helper.hideField("WAITING");
        helper.showField("ERROR");
    }
}

Example Next Button Function:

function (helper, defaultPage) {
    var theNextPage;
    if(Context["USER"]["NOTIFICATION_RECEIVED"]) {
        // Notification was received; go to the next page
        theNextPage = defaultPage;
    } else {
        // Notification not received; just reload this page
        theNextPage = helper.getPageName();
    }    
    return theNextPage;
}

Finish Page

The third and final page is used to display details of the completed checkout process to the user. Form variables are used to access information returned in context variables, which can then be displayed in a suitable HTML field.

Confirmation Text

Having reached this page the _MESSAGE context variable should contain the text of the "Success Message" property of the payment action, so this should be displayed to the user.

Notification Response

The information contained within the notification received from the payment provider is made available in the _RESPONSE context variable.