Passing Values to the Payment Provider

When you are passing information to a payment provider you need to ensure the data is validated, cannot be manipulated by the user, and that secure elements remain private.

Using Form Values

Like other field types, the payment fields support value substitution using #FIELDNAME# for input fields and %VARIABLENAME% for variables.

For example, the Capita field lets you pass the name of the user making the payment to Capita's payment portal. If the user enters their first name into a field called FIRSTNAME, the value of that field can be inserted into the payment field type by setting #FIRSTNAME# as the value of the "Account name - forename" property.

Calculating Totals

Perhaps the most important piece of information the iCM form passes to the payment provider is the amount to take payment for.

As with all forms work, it is wise never to trust values from a user's browser, which could be manipulated by browser side scripts or using a browser's developer tools.

User Defined Totals

If the person filling out the form is able to choose the amount they want to pay, perhaps by typing into a number input field, you can reference that amount directly in your payment field. Because the form is designed to let the user choose what they pay, there's no need to guard against someone manipulating that value.

You will need to validate the format of the value the user enters. For example, some payment provider expect the amount in pence, others pounds and pence.

Fixed Totals

Where a user has to pay a fixed amount per form submission, we recommend setting that amount in a server-only form helper variable field, then referencing that variable in your payment field.

For example, this field has a value of 2500:

Which is inserted into the payment field like this:

By storing the total to pay server-side it cannot be manipulated using browser developer tools or other browser-side scripts.

Calculated Totals

If the amount a user needs to pay is calculated based upon options selected in the form, transaction totals should always be re-calculated or validated server-side, before the payment field is triggered. There are two ways to do this.

1. On a multipage form, options for what to pay are chosen on one page, and recalculated server-side on a subsequent page that includes the payment action
2. On a single page form place a script action field above the payment action, which will be processed server-side when the page is submitted, and return a result before the user is redirected to the payment provider

In both scenarios the recalculated/validated total should be stored in a server-only form helper variable and passed to the payment payment field in the same way as the fixed total example above.

Floating Points

When you perform calculations in JavaScript you will encounter rounding errors due to the way those numbers are stored and processed. For example, 0.1*0.2 results in 0.020000000000000004

When you are working with decimals, always use a library to perform calculations. decimal.js is available in your forms and end points.