The Payment Form

Payment forms are responsible for taking the contents of the basket, ensuring the items are in the correct format, then redirecting to the third party payment provider.

Due to the unique requirements of each payment provider and the flexibility available when integrating with them we do not provide a standard payment form.

Payment Snippets

When setting up the payment basket for the first time, a payment form should be created using one of the provider specific snippets as a starting point. We currently have snippets for:

• Capita SCP Multi-Item
• Civica (not eStore)
• PayPal

Each snippet follows a similar pattern.

View Model

The default function of this variable field calls into a set of End Points with the name of the payment provider and details about the current user (either their unique session or username). It returns the items in the user's basket in the format needed for the payment provider.

Preparing Items

Some payment providers require additional information from the user, like their address. These fields should be added to the payment form, then this script should merge the view model response with those fields into the format required by the payment provider.

Locking

The payment field should be placed between script actions which lock and unlock the basket. The basket is locked prior to redirecting to the payment provider. There's no need to unlock a basket that is successfully paid for, but should there be a problem, the basket will be unlocked and the user can attempt payment again. Locking the basket pauses the timeout so baskets cannot time out while the user is on the payment provider's site.

The Payment Field

Each payment provider has its own payment action field. Generally the formatted list of items in the basket are passed to the provider via the "Payment List" or "Dynamic Item List" property.

The "Response Handler" property of the payment action is responsible for notifying the Multiple Payment Basket that payment has been made. On a successful payment, the basket and its items (as they was passed to the provider) are sent back to Multiple Payments via the goss.MultiplePayments.crud.completeBasket End Point.

This is an example handler for a successful response from Civica:

function(helper, successful, status, details) {
    helper.trace("SUCCESSFUL: " + successful);
    helper.trace("STATUS: " + status);
    helper.trace("DETAILS: " + JSON.stringify(details));

    //Multiple Payments element
    let paymentResponse = {
        "success": successful,
        "details": details
    };

    helper.trace(successful);
    helper.trace(details);

    if (successful && details) {
        // Add details of the sales for Civica to the additional data elements.
        let additionalData = {
                "paymentAuthorisationCode": details.PAYMENTAUTHORISATIONCODE,
                "incomeManagementReceiptNumber": details.INCOMEMANAGEMENTRECEIPTNUMBER
            },
            userName = helper.getSiteVariable("SITEUSERNAME"),
            sessionKey = helper.getSiteVariable("ISLOGGEDIN") ? "" : Context.USER.FORMSESSIONSTORE.PAYMENTSSESSIONID,
            order = helper.getVariable("viewModel").order,

            resp = helper.utilServerAPIServerCall("serverlibrary", "goss.MultiplePayments.crud.completeBasket", {
                "businessKey": order.businessKey,
                "basket": order,
                "siteUserId": userName,
                "sessionKey": sessionKey,
                "status": "paid",
                "additionalData": additionalData
            });

        helper.trace(resp);

        // Store the response of the complete basket action for debugging later if needed.
        paymentResponse.reaminingBasket = resp;
        helper.setVariable("paymentResponse", paymentResponse);
    }
}

Basket Snippet

If you'd like to redisplay the basket on the payment form, without the option to remove items from it, use the "Basket" form snippet.