Handling Responses

Most payment providers, once a user has attempted to make a payment, redirect the user back to the iCM form with a "successful: true/false" property, accompanied by an authorised, refused, cancelled or error status.

The "successful" and "status" messages vary between providers. This information is included in the documentation for each field type. You'll need to know the status messages specific to your payment provider so that you can handle the response appropriately.

For example, the Capita provider response includes:

Whereas the Adelante response includes:

Response Handler

The payment field types include a "Response Handler" property. This property lets you write a JavaScript function that will be executed when the response is received.

In this example the handler is used to update the value of a variable called SUCCESS, trace the details, and update some other fields if the response was successful. if unsuccessful it removes a workflow action:

function(helper, successful, status, details) {
    helper.setVariable("SUCCESS", successful);
    helper.trace(details);
    if (successful) {
        helper.setFieldValue("CARTID", details.CARTID);
        helper.setFieldValue("PAYID", details.PAYID);
    } else {
        helper.utilRemoveAction('COMPLETETASK', Context);
    }
}

Other Action Fields on the Same Page

It's highly likely that your form will include other action fields, like the email action or start-workflow action, and that you'll want to change what these field do depending on the result of the payment.

Action fields are, generally, executed in the order they are placed on your form (see The Form Lifecycle: Control and Action Processing for a more detailed discussion of action processing). So, if your email action is placed above your payment field, an email will be sent before the payment field is processed. This means that, in the majority of situations, a payment field should be placed above all other action fields so that you know the result of the payment, and can handle it, before the other fields are triggered.

The forms helper library includes two functions that can be used to remove form actions. .utilRemoveAction can be used to disable a single action, .utilRemoveAllActions will remove all actions. Using either of these functions in your payment field's response handler allow you to change the behaviour of your form depending on the response.

In this example a successful response from PayPal will update some fields. Any other response will remove all of the remaining action fields and create a new confirmation action:

function (helper, successful, details, fieldName){
    helper.setFieldValue("STATUS", details.STATUS);
    helper.setFieldValue("SUCCESS", successful);
    helper.trace(details);
    if (successful){
        helper.setFieldValue("CARTID", details.CARTID);
        helper.setFieldValue("PAYID", details.PAYID);
    } else {
        helper.utilRemoveAllActions(Context);
        helper.utilAddAction(helper.utilCreateConfMessageAction("PAYPAL", "Something went wrong"), Context);
    }
}

Most payment fields also include a property called "Stop Processing on Error". If set to true, should the payment provider return an error state or status, all of the subsequent action fields on the form will be disabled.

Pages Following the Redirect

There are two ways you can set up pages and payment actions.

Using a Submit Button

If you use the standard Submit or Wizard buttons on the page you form that has your payment field, the form will be submitted, the redirect to the payment provider will be performed, and the user will be redirected back to your form, as described above.

Because the form has been submitted, your response handler can allow or cancel any appropriate actions, and display a message to the user, but the form session has otherwise ended.

Using Navigation Buttons

An alternative pattern of form design uses navigation buttons, typically labelled "continue" or "make payment", and places additional pages after the page with the payment field.

In these cases, because the redirect to the payment provider is performed on page submission, rather than form submission, the user's form session is still active when they return to your form.

That means your navigation function can check the result of the payment (ie check for the success variable set by the payment field's response handler) and navigate to an appropriate page. That follow-up page could also use conditional layouts to further customise what the user sees.

One caveat to using navigation rather than submit buttons, is that your follow-up page after the payment is still part of an active form session, and will remain active until it is submitted.