JetPay Module for Miva Merchant 5

This document gives instructions on installing and using the JetPay payment module for Miva Merchant shopping-cart systems. If you need additional details, check with your Miva or JetPay representative or documentation.

Version 5.00, April, 2007

This version of the module will only support Miva Merchant version 5 and up. Users of Merchant versions 1.00 thru 4.24 can continue to use older versions of this module.

Installation

The procedure for installing this module is the usual one for Miva Merchant modules: add the module to the site, and assign it to the store. The procedure is explained below in a bit more detail. If you need more information, see your Miva representative or documentation.

Log in to the Miva Merchant Administration page.
In the left-side menu, click the [Add] link next to the Modules link.
In the right-side frame, click the Upload button.
In the Upload box, click the Browse button.
Navigate to the folder where the payment module source file is located, and select the file. The filename is jetpay.mvc.
In the Upload box, click Upload. After a few moments, the Upload box will close.
In the right-side frame, click the Add button.

After the module is installed, you need to assign it to your store.

In the left-side menu, click the icon next to the Stores link (change it from plus to minus).
Click the icon next to the link labeled with the name of your store.
Click the link labeled Payment Configuration.
In the right-side frame, find the checkbox labeled Credit card payment via JetPay.com, and click it once (put a checkmark in the box).
Click the Update button in the lower right corner of the frame (you may need to scroll down to see it).

After the module is assigned to the store, a new "tab" link labeled Credit card payment via JetPay will be seen at the top of the right-side frame. Clicking this link will take you to the setup page for the module. Some of these settings will need to be adjusted as soon as you install the module, before you try to process any transactions. At a minimum, you will need to enter the server URL and your merchant ID. All the settings are described in the next section; you should familiarize yourself with them all before you put the module on-line.

Module Settings

This section describes the use of the various text boxes and buttons on the module's setup page.

NOTES:

After changing any settings, remember to click the Update button in the lower right corner of the frame (you may need to scroll down to see it).
Certain settings may not be permitted for your merchant account, or may affect your service charges. If you are in doubt, check with your JetPay representative or documentation.

Server URL

Type in the URL for your payment-processing server. Your JetPay representative will give you the specific URL that you should use.

Merchant ID

Type in the merchant ID code that you were issued.

Write log file

If this checkbox is checked, the module will write information to a text file every time it exchanges data with the payment server. This feature is intended for troubleshooting, and should normally be unused (the box should be unchecked). If it is used, the log file will be named jetpay.log, and will be located in the Merchant5 folder of your site's Miva data directory, which is usually named mivadata or htsdata. When logging is turned on, the log file's size will increase by a few hundred bytes for every transaction processed.

Transaction mode

The payment module can operate in either of two modes. Automatic capture means that the customer's purchase is both authorized and captured (billed) at the time of the purchase. Authorize only means that the module will authorize the payment at the time of the purchase, but you must capture the transaction manually at a later time. Manual capture is done through the Order Processing section of Miva Merchant.

Allowed cards

The module can accept several different types of credit cards, but your merchant account may not allow you to accept them all. These checkboxes allow you to specify which types of cards will be allowed.

Order-ID data and text

The Order ID is a data field that the module sends to the JetPay server with each transaction. In some cases, this data will appear on the customer's credit card statement, along with your business name. You can set this field to contain one of the following types of data:

The order number that is assigned by Miva Merchant.
The name of the first product in the customer's basket.
The name of the most expensive product in the customer's basket.
Any other text that you specify by entering it in the Order-ID text box. This text may be up to 24 characters; it must not contain the asterisk (*) character.

Customer message HTML

The text or HTML that you enter in this box will be displayed to customers on the third checkout page, just above the fields where they enter their credit-card numbers. If you are using authentication services (see below), you can use this message to advise customers that they may be transferred to another site to enter their password.

Authentication settings

The settings in this section are used to communicate with a server for authentication services such as Verified By Visa.

Enable

Check this box (and click Update) to enable the authentication services. If you don't want to use authentication, leave this box un-checked.

Transaction URL

Enter the URL that your store will use to contact the authentication server.

Processor ID, Merchant ID, Transaction password

Enter the ID codes and password that were assigned to you by your account representative.

Currency code

Enter the three-digit code that indicates the currency that your store uses. Several common codes are listed on the page. If you need a different code, contact your account representative.

Unprotected purchases

Normally, when your store uses authentication, customers' purchases are approved by the authenticator, giving you protection against chargebacks and other problems related to fraudulent or improper use of cards. Sometimes, though, the authenticator may give an indefinite or "semi-approval" response due to Internet problems, server errors, etc. In these cases, you have the option of accepting the transaction, even though you will not have the usual protection. Click Accept or Reject to specify how you want the store to handle these purchases.

Encryption key

When customers use an authenticated card, they are temporarily redirected from your Miva store to the authentication site to enter their password. During the few moments needed for this, the Miva store must provide temporary storage for confidential data such as the card number. To ensure data security, this temporary storage is encrypted using the key that you enter here.

The key can consist of any text, but it must be exactly 16 characters long. Upon installation, this key is initialized with random text. You can change the key at any time; however, you should put the store in Maintenance mode first. If you change the key while customers are using your store, there is a slight chance that some of them may encounter errors during checkout.

CVV2 digit entry

The CVV2 code is a set of additional digits that customers may read off their credit card and type in when they make purchases at your store. There are three possible settings for the module:

None: customers will not be asked for CVV2 digits.
Optional: a text box for CVV2 will be displayed, but customers may leave it blank. If they do enter digits, the server will verify them.
Required: customers must enter valid CVV2 digits into the text box to make a purchase.

If you select Optional or Required, the CVV2 response buttons described below control how the module responds to CVV2 error conditions.

CVV2 explanatory text

This text box specifies HTML that is displayed to the customer under the text box for the CVV code. You can use this to provide instructions that will help customers find the code. JetPay provides two image files that illustrate the position of the codes:

Image: http://www.jetpay.com/cvv/cvv-visa.gif Image: http://www.jetpay.com/cvv/cvv-amex.gif

When you install the module, this text box is pre-loaded with HTML that includes both images. You can edit the HTML to remove the images, use different ones, add additional text, etc.

NOTE: if you use secure HTTP for your Miva checkout pages, you will need to use secure URLs for the image files. You can just edit the URLs in the text box, and change the initial http: to https: (adding the "s" makes it secure). If you don't do this, site visitors may see a warning message about secure and insecure data on the same Web page.

CVV2 responses

You can tailor the module's response to various types of CVV2-digit errors. There are 4 possible error conditions that the server may detect. You can click Accept or Reject to specify whether your module should allow transactions to proceed if each error occurs. The highest level of security is provided by selecting Reject for all options.

Send address info

The module can send the customer's billing address to the server, in order to verify whether the address that the customer typed matches the address on file for the credit card. If this box is checked, the module will send addresses, and will respond to mismatch conditions as specified by the response buttons described below.

AVS responses

You can tailor the module's response to various types of address-mismatch errors. There are 8 possible error conditions that the server may detect. You can click Accept or Reject to specify whether your module should allow transactions to proceed if each error occurs. The highest level of security is provided by selecting Reject for all options.

Address-match responses

These buttons are somewhat redundant to the AVS response buttons described above. They allow you to specify the module's response to several types of address-mismatch conditions. If a transaction generates a combination of Accept and Reject responses, the purchase will be rejected. The highest level of security is provided by selecting Reject for all options.

Zip-match responses

These buttons are somewhat redundant to the AVS response buttons described above. They allow you to specify the module's response to several types of Zip-mismatch conditions. If a transaction generates a combination of Accept and Reject responses, the purchase will be rejected. The highest level of security is provided by selecting Reject for all options.

Order Processing

Using encryption

The module stores credit-card numbers and other confidential information in the store databases. To protect this information, you should use Miva's encryption features. If you haven't already done so, you should click the Encryption link in the Order Processing section of the Miva admin pages, turn on encryption, and enter a pass phrase.

Once you have activated encryption and entered a pass phrase, you will need to enter the pass phrase whenever you access the encrypted data for viewing, running batch reports, capturing purchases, or doing VOID or CREDIT operations. If you lose the pass phrase, there will be no way to recover the encrypted data to perform these operations. Keep a copy of the pass phrase in a safe place, such as a paper copy in a locked container.

Processing orders (capturing funds)

If your payment module is set to authorize-only mode (see "Transaction mode" above), you will need to manually capture the authorized funds. You can do this in the Order Processing section of the Miva admin pages. Note that you must place orders in a batch before you can do this.

Click the "Process Orders" link for a batch that contains orders that you want to capture.
Enter your encryption pass phrase in the text box at the top of the page and click the "lock" button.
Click the checkboxes next to any orders that you want to capture.
Click the "Process" button at the bottom of the page.

For more details, consult your Miva documentation.

VOID and CREDIT operations

If you need to cancel a purchase or issue a refund, you can generate a VOID or CREDIT transaction for an order. Note that if your module is in authorize-only mode, you will need to capture an order before you can do this.

In the Order Processing section of the Miva admin pages, go to the order-details page for the order.
Enter your encryption pass phrase in the text box at the top of the page and click the "lock" button.
Click the link labeled "Credit card payment via JetPay.com" to view the payment data.
For a CREDIT transaction, if you don't want to refund the full amount of the order, you can enter a dollar amount in the text box.
Click the "Void" or "Credit" button, as needed.