This document assumes a general familiarity with Transform - it only describes the additional information required to enable web-based credit card processing. General information about using Transform can be found in the Web Forms with Transform 3.0: the Users' Guide

In order to use this version of Transform, you must make arrangements with the IU Office of the Treasurer. Please contact them directly for information about becoming a Web merchant. Additional information is available on their Internet credit card page.

Note: by setting !epayment-mode = syntax-check (see below) TransformEp developers may test their applications without becoming a registered merchant with the IU Treasurer. This let's you assess whether TransformEP will suit your needs and allows initial testing without contacting the IU Treasurer. However, there is no actual credit card processing using this mode - syntax checks only. You must become a registered merchant to have credit card information processed.

Overview of credit card processing with TransformEP

Normally when using Transform, you define a number of template sections (e.g. *define-variables*, *success-response*, *email-response*, etc) to control how your form information is processed. To enable credit card transactions with TransformEP, there is an addition template section named *epayment-variables* that is used to describe various aspects of credit card processing. Among other things, the *epayment-variables* section describes:

Which of your form variables contains the total amount the user is to be charged.

The name of the submit button that should send the user to a credit card entry form to complete the charging process.

Given this information, processing follows these steps:

• The user completes your form that contains an appropriately defined "total amount" variable along with any other information you choose.

• When the user submits the form using the submit button you've defined as the "charge" button, a credit entry form provided by the IU Office of the Treasurer, is displayed. (Note: as a result, your own form will never have credit card entry fields. In addition, you have no control of this credit card entry form; a single common form supplied by the Treasurer will be used in all cases.)

• The user enters their credit card information and selects "Pay Now", initiating the online authorization/charging process. The form variable you specified as the "Total Amount" variable determines the amount the user is charged. This form is actually submitted to a special web server named IPAS (Internet Payment Authorization Service). This server communicates directly with the Verisign CashRegister Service to process the direct authorization/charging.

• After credit card processing is complete, control is returned to your TransformEP template file so you may display the results to the user and record information about the transaction (but the actual credit card information will not be available to you). This operates exactly as it would using the standard version of Transform, except that a number of additional template variables will automatically be set that indicate the success or failure of the credit card transaction. By testing against these variables in your template file, you can provide the appropriate success or error response to the user. In addition an order-id is returned that you can use to uniquely identify this transaction. This order-id is also used as a unique transaction id in the Treasurer's ledger and thus can be used to communicate with them about an individual transaction.

Installing TransformEP (aka transformep.cgi)

TreansformEP is installed in much the same way as Transform. The one restriction is that TransformEP may only be used with our secure SSL Web server. See the document, Secure WWW Server for information. Essentially what this amounts to is that your form/template files must be in your wwws directory rather than your www directory, and thus all url references must use https: rather than http:.

To install TransformEP, simply cd to your wwws directory and type tfeppf_install (rather than the tf_install command used to install Transform). If you have no wwws directory you must create one at the same level as your www directory. This installation procedure causes the following to happen:

• transformep.cgi, the TransformEP application you reference in your form action statement is installed in the current directory. (Note, that like tf_install, you may execute and have transformep.cgi installed in as many subdirectories in your wwws directory as you like.)

• A directory name tfep_support is installed in your wwws directory. In this directory, a helper application named tf_ipasagent.cgi is installed. This application is critical to the credit card processing - don't alter or remove this application.

• If one doesn't exist from a prvious installation of Transform, a directory name tf_support is installed in your login directory. Additional support directories are installed in this directory.

Setting the Form "action =" to Point to TransformEP

Like Transform, when using TransformEP, you simply use "transformep.cgi" in your form action statement (if transformep.cgi is installed in the same directory as the form.) Just remember that if you use a full url to point to transformep.cgi in an action statement, use https:, not http:. General information about setting the form action statement can be found in the standard Transform Users Guide.

The *epayment-variables* template section

The *epayment-variables* section is used to define variables that control various aspects of the charging process. Like other Transform commands, the commands described below must begin in the first column of the *epayment-variables* section. The commands and their functions are described below.

!epayment-mode

The !epayment-mode command is required and controls the mode of TransformEP with respect to the IPAS server. There are three allowed values:

!epayment-mode = syntax-check

!epayment-mode = simulate

!epayment-mode = active

• When set to "syntax-check", no credit card processing is done. In addition, you needn't be registered with the IU Treasurer to use TransformEP in this mode. This mode is useful in the early development of TransformEP application or when you want to create a non-functional prototype to see if TransformEP will suit your needs. No actual credit card transactions are processed in this mode.

• When set to "simulate", no credit card processing done. To use this mode, you must be a registered merchant with the IU Office of the Treasurer. Using this mode, checks are made to be sure that your merchant configuration information is accurate. Like 'syntax-check' above, this mode can also be used when first developing your TransformEP application so that you can test to be sure that the logic in your template file returns the appropriate success or error response to users. More information about the various steps used to test your application is described below.

• When set to "active", normal credit card processing is done, that is transactions are sent to Verisign. This is the normal setting used when your application is in production. (In addition, this mode is used in the final stages of testing, when "bogus" credit card numbers supplied by the Treasurer are used to test your application. The Treasurer will provide more information about these final levels of testing.)

!payment-total-amount

The !payment-total-amount command is required and is used to "tell" TransformEP 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: The IPAS server/Verisign 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.

!payment-button-name

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 TransformEP. 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/TransformEP 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.

!order-id-suffix

TransformEP automatically generates a unique order-id for every transaction. The format of this order-id is:

username-long number

where "username" is the web server account name, and "long number" is the year, month, day, hour, minutes, seconds and 3 additional random numbers. For example:

percival-20000209112525888

What !order-id-suffix allows you to do is define an additional string that will be appended (with a dash) to the end of the order-id. This might be useful if you have multiple TransformEP applications and you wanted to include an additional string that identifies which application created a given order-id.

The general form of this command is:

!order-id-suffix = string

where "string" is the string you'd like appended to the order-id. For example, if I included the following command:

!order-id-suffix = bk1

the order id example above would contain:

percival-20000209112525888-bk1

Note: the order-id-suffix can be no more than 5 characters and must consist of only letters and numbers.

!error-test

As mentioned above, after credit card processing, control is returned back to your TransformEP template. A number of additional variables are returned, including those which describe any errors that occurred during credit card processing (e.g. illegal card number, insufficient funds, etc). In your template file you must test for these errors so that you provide the user with the appropriate success or error response. (A complete discussion of these variables and how to test for them is provided below.)

The purpose of the !error-test command is to allow you to emulate any error condition while in the testing phase of building your TransformEP application. The general format of this optional command is:

!error-test = error-code

where "error-code" is any error codes listed in Appendix A: Error Codes. For example:

!error-test = CE-0001

would cause the emulation of error CE-0001, "The type of credit card specified cannot be accepted". By setting !error-test while testing your application, you can be sure you are testing for errors correctly before putting your application into production.

Additional variables returned by IPAS

A number of variables are returned by the IPAS server as a result of credit card processing. These variables may then be used anywhere in your template, just as you use the normal variables entered in a form submitted by a user (i.e. by referencing their name enclosed in square brackets). The additional variables returned include:

IPAS_order_id

IPAS_order_id is returned as a unique transaction id for a charge card submission.

IPAS_success

IPAS_success will be set to the string 'success' if their were no errors during the credit card transaction processing. It will not be set (i.e. null) if there were errors. This variable is especially useful in success-like conditions - if it is set, you can provide the user with an appropriate *success-response*.

IPAS_error_message

IPAS_error_message contains a text string that describes any error that occurred during processing. It has a value of "" (i.e. null) if no error occurred.

IPAS_error_code

IPAS_error_code contains the error code that corresponds to the string returned in IPAS_error_message when an error occurs. It has a value of "" if there was no error.

This is provided so you may test for individual IPAS_error_code values in your template file if you want to display your own specific error messages.

IPAS_amount_error

This variable is only set if there was an error in the amount variable that was sent to the IPAS server. Note that IPAS_error_message will be set as well. This variable may be used to easily test for errors in the amount in your template file. If you use Javascript to check the amount entered by the user (and you should), this variable is of little use since there should never be any amount formatting errors returned from the IPAS server.

IPAS_card_error

This variable is only set if there was an error in the credit card information provided by the user. Again, IPAS_error_message will be set as well. This variable is used to easily test for this class of error in your template file so you may give specific directions to the user.

Testing for transaction errors

As mentioned above, there may be errors during the credit card authorization process. As a result, you MUST test for these potential errors in your TransformEP template file (i.e. you wouldn't want to deliver a successful response to the user if the credit card transaction was not successful).

Transform as well as TransformEP provides a number of ways for you to check for the values of variables and control what is output based on these tests. This involves using the conditional branching and test functionality available in Transform. If you have not used these functions, you should look at the Advanced Use section in the Transform Users' Guide beginning with the Conditional Branching section.

The basic idea is to provide some conditional test for the variable [IPAS_error_message]. If this variable has a value, then some kind of error has occurred and this variable contains a text message that describes the error. Thus, if this variable has a value, you need to display an error report to the user. If [IPAS_error_message] has no value, then the authorization/charge process was succesful and you can proceed with a successful response to the user.

While Transform/TransformEP provides the flexibility to accomplish the above task in many ways, perhaps the simpliest method is to use !force-error-if. For example, if you include a *define-variables* section in your template that looks like:

*define-variables*

!force-error-if [IPAS_error_message]

Setting !force-error-if [IPAS_error_message] has the following effect: if there is a charge transaction error then [IPAS_error_message] will be set and the !force-error-if statement will allow only *error-response* sections to be displayed. Thus using this simple method, you can have *error-response* sections display the appropriate error messages. Examples follow...

Examples of using TransformEP

Below are a few actual examples of TransformEP. 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 TransformEP

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/transformep.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 TransformEP template file that might be used to process this form. Bolded items are those that are specific to TransformEP or non-typical and important to the charging process.

# Begin the *epayment-variables* section.
# Here we've set !epayment-mode to syntax-check.
# 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 = syntax-check
!payment-total-amount = [amount]
!payment-button-name = [charge]

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

# If there is an error during the payment
# authorization process, the variable IPAS_error_message
# will be set. Here call !force-error-if with this variable.
# This will cause only *error-response* sections to be
# used if there was an IPAS error.
!force-error-if [IPAS_error_message]


# Here's a silly *success-response*.
# Note that IPAS_order_id is displayed to the user!
*success-response*

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

Your name: [name]<br>
The amount you have been charged: <b>$[amount]</b><p>
Your Order ID: <b>[IPAS_order_id]</b>

# Here is the *error-response*.
# This section will only be displayed if there is
# an IPAS_error_message. The !force-error-if command
# accomplished this.
*error-response*

<b>The following error occurred:</b><p>
[IPAS_error_message]
<p>
Just for fun show the error code: [IPAS_error_code]

#####   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 TransformEP the mode, the amount, and the charge button's name.

• You must check for possible transaction errors using [IPAS_error_message]. While there are other ways to accomplish this, the use of !force-error-if shown in this example is probably the easiest.

• As shown in this example, you should always provide the IPAS_order_id to the customer.

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 !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, but with two *error-responses*, one to handle required variables, and the other to deal with IPAS errors.

• As mentioned above, the IPAS server 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.

• If there is a problem with the information a user enters on the credit card entry form, TransformEP sets the IPAS_error_message variable, but also sets IPAS_card_error, indicating this specific type of error. What this allows you to do is check for IPAS_card_error, and if present, give the user the opportunity to go forward and retry entering information on the credit card entry form. This is preferable to forcing the user to use the Back button to return to the credit card entry form. This form is not cached and the user will get a "Re-post form data" message if they attempt to use the Back button to return to this credit card form. The example below adds Transform commands that allows the user to re-enter credit card information if the IPAS_card_error variable was set.

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

*epayment-variables*
!epayment-mode = syntax-check
!payment-total-amount = [amount]
!payment-button-name = [charge]

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

# If there is an error during the payment
# authorization process, the variable IPAS_error_message
# will be set. Here call !force-error-if with this variable.
# This will cause only *error-response* sections to be
# used if there was an IPAS error.
!force-error-if [IPAS_error_message] 

# 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*.
# Note that IPAS_order_id is displayed to the user!
*success-response*

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

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



# Here is a standard error response if there were
# no IPAS errors. 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. Thus, if there are required variable errors,
# IPAS_error_message will not yet have been set.
# The !use-if command below simply says: process
# this section if there is no IPAS_error_message.
*error-response*
!use-if  not [IPAS_error_message] 

<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>

# Here is the second *error-response*.
# This section will only be displayed if there is
# an IPAS_error_message. The !force-error-if command
# accomplished this.

# The !use-if command below insures this section will
# only be displayed if there were IPAS errors.
*error-response*
!use-if [IPAS_error_message] 

<b>The following error occurred:</b><p>
[IPAS_error_message]
<p>
Just for fun show the error code: [IPAS_error_code]


# Next, within this *error-response* we create a new <form> (button)
# that allows the user to return directly to the credit card entry form.
# This may or may not be appropriate depending on the error
# that occurred. The !print-if below checks for just errors
# on the credit card entry form using IPAS_card_error. 
# Hence the form is only printed when there are errors on that form.
!print-if [IPAS_card_error] and not [IPAS_amount_error]

<p>
If you would like to re-enter your credit card information,
use the submit button below.<p>

The total amount you will be charged is: $[amount]<p>

# Here we must supply the full path to transformep.cgi and the template
# file because we are calling transform from a template file.
<form method = "POST" action =
"https://www.indiana.edu/~your_user_name/transformep.cgi?your_user_name/wwws/donate">
<p>

# The !carry-forward command insures that all previous form
# information will be available.
!carry-forward all

# Again, the "charge" submit is supplied with a name attribute.
<input type="submit" name = charge value="Go to the credit card entry form">
</form>

!end-print-if


#####   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 (i.e. the first *error-response* is used). In addition, if you make errors on the credit card entry form, you'll see that the second *error-response* is used.

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 see how this Javascripts checks and/or modifies the 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 - Error Codes

Below is a table of the errors returned in IPAS_error_code and IPAS_error_message respectively. There are many more "CR" errors than those listed in the table below. These are just some of the more common ones.

Amount Value Errors
AE-0001	A purchase amount to be approved was not specified.
AE-0002	The purchase amount to be approved has an invalid format.
Credit Card Entry Errors
CE-0001	The type of credit card specified cannot be accepted.
CE-0002	A credit card number was not supplied.
CE-0003	The credit card's expiration date was not supplied.
Verisign Cash register Errors - there are many others
CR-0001	Cash Register: Cannot find a required field in the approval request.
CR-0002	Cash Register: The order id contains illegal characters. An order id can contain letters, numbers, periods (.), commas (,), dashes (-), and underscores (_).
CR-0003	Cash Register: The order id is longer than the maximum of 40 characters.
CR-0004	Cash Register: The order id field is missing.
CR-0005	Cash Register: The credit card number contains illegal characters. A credit card number can contain numbers, dashes (-), underscores (_), or blank spaces.
CR-0006	Cash Register: The credit card number is longer than the maximum of 20 characters.
CR-0007	Cash Register: The credit card number was not received.
CR-0008	Cash Register: The credit card number is invalid
CR-0009	Cash Register: The order id received already exists for this merchant
CR-0010	Cash Register: The order id could not be found.
CR-0034	Cash Register: The length of one or more of the card-expiration-date, card-name, card-address, card-city, card-state, card-country, or tax-id is too long.
System Errors
SE-0001	The IPAS error message you want to test does not exist.
SE-0002	The IU IPAS was contacted using an invalid HTTP access method. Please notify the merchant of this error.
SE-0003	IPAS could not update it's transaction notification log. Please notify ???? at ???? of this error.
SE-0004	IPAS did not receive a response from the IPAS agent.
SE-0005	The format of the order id that was received is invalid.
SE-0006	The IU IPAS configuration for this merchant is invalid or missing. Please notify the merchant of this error.
SE-0007	IPAS did not receive the variable 'IPAS_variable_list' or it does not have a value Please notify the merchant of this error.
SE-0008	IPAS did not receive the variable 'IPAS_return_url' from the IPAS Agent or it does not have a value. Please notify the merchant of this error.
SE-0009	IPAS did not receive the variable 'IPAS_request_method' or it does not have a value. Please notify the merchant of this error.
SE-0010	IPAS did not receive the variable 'IPAS_order_id' or it does not have a value. Please notify the merchant of this error.
SE-0011	The format of the 'IPAS_order_id' variable that IPAS received is invalid.
SE-0012	IPAS was not able to retrieve the amount of the purchase. Please notify the merchant of this error.
SE-0013	The IPAS agent received an order id for which no order information could be found.
SE-0014	The IPAS agent was activated with an invalid HTTP request method.
SE-0015	The IPAS agent received an invalid HTTP user agent name.
SE-0016	The IPAS agent received an invalid IPAS host IP number.
SE-0017	The IPAS agent received an invalid IPAS host name.
SE-0018	The IPAS agent received an invalid IPAS merchant name.
SE-0019	The IPAS agent received an invalid request mode from IPAS
SE-0020	One or more reserved variable names were recognized and are listed below. Please select other names.
SE-0021	The variable 'IPAS_return_url' is not valid.
SE-0022	An illegal value was received for IPAS_request_method. This method is not supported