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 field called SUCCESS, trace the details, and update some other fields if the response was successful:

function(helper, successful, status, details) {
    helper.setFieldValue("SUCCESS", successful);
    helper.trace(details);
    if (successful){
        helper.setFieldValue("CARTID", details.CARTID);
        helper.setFieldValue("PAYID", details.PAYID);
    }
}

Other Action Fields

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.