The !payment-total-amount command is required and is used to "tell" TransformIUPayPlus which of your form variables will contain the total amount to be charged. The general form of this command is:

!payment-total-amount = [amount]

where in this case, the form variable "amount" would contain the total amount the user is to be charged. As is normal for Transform, the variable name is provided surrounded by square brackets.

Important note: TransformEP is very picky about the format of the amount. The amount must be of the form 0.00, that is dollars, a period and cents. Often users will not enter amounts in exactly this format. If you are not computing your own amounts (e.g. via Javascript), this can be a problem. An example below provides a couple of alternatives for testing your amount variable including some Javascript that may be used to check/convert user supplied amounts to the appropriate format.

The !payment-button-name command is required and is used to define the name of the submit button that when selected by the user, will cause the credit card entry form to be displayed (resulting in the display of the credit card entry form). The general form if this command is:

!payment-button-name = [pay]

where in this case, the form variable "pay" is the name of the submit button form variable.

Note: More often than not, submit buttons defined in html forms have no "name" attribute. That is most html form developers define submit buttons like so:

<input type = submit value = "Submit button label">

This type of submit button coding will not work with TransformIUPayPlus. In order to to set the !payment-button-name appropriately, you must also include a name = attribute when coding your html submit button. For example,

<input type = submit name = "pay" value = "Submit button label">

In this case, this submit button has a name attribute ("pay") as well as the value button label. It is the name attribute that must be provided to the !payment-button-name command.

Why must I supply a name for the submit button?

Transform/TransformIUPayPlus allows the development of applications that may use multiple forms and/or review-like functions. Thus, you may need the ability to have multiple submit buttons to control these various processes. In order to retain this flexibility and give absolute control over when the credit card input form is displayed, you must use !payment-button-name to specify which submit button initiates the charging process.

The !payment-orderType command is required and is used to pass in the order type set up by IU Treasury. For example

!payment-orderType = BL~TREA~test

The !payment-orderName command is optional and is used to pass in the name of the order or the name of the payer. For example

!payment-orderName = [name]

The !payment-orderDescription command is optional and is used to pass in the description of the order. For example

!payment-orderDescription = [description]

The !payment-userChoiceN command (where N represents the numbers 1-10) is optional and is used to pass in up to ten user choice fields. For example

!payment-userChoice1 = [choice1]

The !payment-redirectURL command is optional and is used to pass in the url that the payer's browser will be directed to after the payment is submitted. For example

!payment-redirectURL = [redirectURL]

The !payment-redirectURLParms command is optional and is used to pass in a comma delimited list of the parameters that will be passed in the redirectURL query string. For example

!payment-redirectURLParms = [redirectParms]

Please refer to Appendix A for the list of available redirect parameters.

The !payment-redirectURLRetries command is optional and is used to sets the number of retries you will allow the payer to attempt if the first payment attempt was not successful. For example

!payment-redirectURLRetries = 1

The !payment-email command is optional and is used to pass in the email address of the person making the payment. For example

!payment-email = [addr]

Examples of using TransformIUPayPlus

Below are a few actual examples of TransformIUPayPlus. These examples have been kept as simple as possible and are meant to demonstrate just those commands that are used to enable credit card transactions. By themselves, these examples are incomplete. For example, these examples provide no means of logging transactions that would obviously be important in a real setting. The assumption here is that the user is familar with standard Transform usage that would allow whatever additional functions are required.

A simple donation example

Below is a very simple (non-functional) form that might be used with TransformIUPayPlus

A Donation Form

Enter your name:

Enter the amount you'd like to donate:

Here's the source code for this form:

<h3>A Donation Form</h3>

<form  method = "POST" action =
"https://www.indiana.edu/~your_user_name/transformepcm.cgi">
<p>
Enter your name:<br>
<input name="name" size = 40>
<p>
<p>
Enter the amount you'd like to donate:<br>
<input name="amount" size=20 >
<p>
<input type="submit" name = charge
value="Go to the credit card entry form">
</form>

Note that the submit button has been assigned a name - in this case "charge".

Now examine a minimal electronic payment enabled TransformIUPayPlus template file that might be used to process this form. Bolded items are those that are specific to TransformIUPayPlus or non-typical and important to the charging process.

# Begin the *epayment-variables* section.
# Here we've set !epayment-mode to active.
# The !payment-total-amount variable is set to [amount],
# the name of the amount input field on our form.
# The !payment-button-name variable is set to [charge],
# the name of our submit button.
*epayment-variables*
!epayment-mode = active
!payment-orderType = BL~TREA~test
!payment-total-amount = [amount]
!payment-button-name = [charge]

# Begin the *define-variables* section.
# This is only used to set !force-error-if
*define-variables*

*success-response*

*error-response*
<html>
<head>
<title>There has been an error!</title></head>
<body>
<h3>The following error occurred:</h3><br>
[IPAS_error_message]<br>
<h3>The error code was:</h3> [IPAS_error_code]<br>
</body>
</html>

#####   end template file
     

You may try a live version of this form and template to see how it operates.

To summarize, the example above shows:

• How the required *epayment-variables* are used to describe to TransformIUPayPlus the mode, the amount, and the charge button's name. Please note that *success-response* and *error-response* are required to satisfy the editing reqirements of TransformEP. These sections are non-functional with IUPayPlus and will be removed in the next release.

While the template above would work, its hardly a complete example. Let's examine some of the problems with this template and then the additional Transform commands that can be used to correct these problems. The following example makes extensive use of the conditional branching capabilities of Transform as well as !carry-forward to create hidden variables for a chained form. If you have not used these features, you should review the Advanced Use section of the Transform's Users Guide.

Problems with the template above:

• What about required variables? Normally the *error-response* section is used to provide errors about required variables. In the example below, we'll show the same template file, with the *error-response*, to handle required variables.

• As mentioned above, TransformEP is very particular about the format of the amount variable - it must be of the form 0.00. This is best dealt with in the form itself via Javascript and/or with a test in the template file. If not handled immediately, users will not see any amount error until they have gone to the credit card entry page and submitted this form. As a result, users would have to use the Back button twice to get back to your form to correct any error. The example below adds tests in the template file for the amount variable. A more general Javascript solution is shown later.

• In the following example, bolded lines indicate new lines added in this example.

*epayment-variables*
!epayment-mode = active
!payment-orderType = BL~TREA~test
!payment-total-amount = [amount]
!payment-button-name = [charge]

*define-variables*
# Make both "name" and "amount" required variables.
[req-name]
[req-amount]


# Add a !force-error-if that tests to be sure the
# amount entered by the user is in the correct format.
# This regular expression test simply says: does the
# amount variable begin with one or more digits, 
# followed by a period and ends with two digits.
!force-error-if not [amount] =~ /^\d+\.\d\d$/


# Here's a silly *success-response*.
*success-response*

<h2>Thank you for your donation</h2>

Your name: [name]<br>
The amount your have been charged: <b>$[amount]</b><p>



# Here is a standard error response. 
# This *error-response* will be used
# if the user didn't complete all required variables
# or if the test on the amount variable fails.
# Note that required variables processing is done
# before the user is sent to the credit card entry
# form. 
*error-response*

<h2>Error - this is the first error-response</h2>

# Test the amount field and print an error message
# if it has an incorrect format.
!print-if not [amount] =~ /^\d+\.\d\d$/

The amount you entered: <b>[amount]</b>
has an incorrect format.<br>
The amount must include
dollars and cents (e.g. 10.00).<p>
!end-print-if

# This section tests for the presence of other required
# variables and prints a message if they are missing.
# Here only [name] is tested for - others could be added
# depending on your form.
!print-if not [name] 
The name field on the form is required.<p>
!end-print-if

Use the Back button on your browser to return to the form.
<p>


#####   end template file

You may try this form/template to see how it differs from the previous example. In trying this example, note what happens if 'name' is omitted or the amount is in the incorrect format.

Now for one final refinement - some Javascript that checks/corrects the amount field. This example uses exactly the same template file as the previous example. The only difference is the Javascript added to the form. You may try this form to see how this Javascripts checks and/or modifies the amount entered by the user. This is only one example of the way Javascript might be used to check the amount value. Depending on your application, you may want to use Javascript to compute a total amount.

Below are links to the source for the final form and template file:

The form source code containing the Javascript. Note the OnChange addition for the amount field and the OnSubmit in the form tag.

The template source code

Appendix A
Redirect URL Parameters