Perceptive TransForm FormPay

Transcription

1 Perceptive TransForm FormPay Setup Guide Version: 8.x Date: September 2016

2 2016 Lexmark. All rights reserved. Lexmark is a trademark of Lexmark International Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Lexmark.

3 Table of Contents Overview... 4 FormPay process... 4 Prerequisites... 5 Set up an Authorize.Net Merchant account... 5 Configure the E-Forms Manager and ifiller installations... 5 Reverse proxy configurations... 5 Configure Authorized.Net Merchant Account... 5 Response Relay URL... 5 License FormPay... 6 FormPay configuration... 6 Add FormPay to the TransForm Form s design... 6 Designer FormPay catalog... 7 FormPay result fields... 7 Configure FormPay merchant account... 8 Configure FormPay handler... 9 Test the TransForm form Test Mode in a live environment Live Mode in a live environment Turn Test Mode on or off Test steps Error cases Errors prior to display of the Authorize.Net Payment form Errors after an Authorize.Net Processes transaction

4 Overview This document provides information on how to set up and configure the FormPay feature of E-Forms Manager. FormPay process The following steps provide an overview of the FormPay process from an end user s perspective. 1. In ifiller, a user opens a form that utilizes FormPay. 2. The user fills out the form. 3. The user clicks the FormPay Pay button. 4. If all the required information is provided, the secure Authorize.Net payment form displays. Note If an error occurs prior to the display of the Authorize.Net payment form, a dialog box displays with an error message. Refer to Error cases for more details. 5. The user enters the appropriate required information in the Authorize.Net payment form and clicks the Submit button. 6. If the user does not enter all the required payment information or enters invalid data (incorrect format, such as credit card number or expiration date), the Authorize.Net payment form displays the appropriate errors to the user to correct. 7. If the user provides all the required payment information and the information is valid (correct format), the Authorize.Net payment form closes and Authorize.Net attempts to authorize the transaction. 8. The result of the transaction displays in ifiller on a receipt page. 9. If the transaction is approved and the transaction results populate into the FormPay results form fields if they exist in the form. 1. The form is submitted to E-Forms Manager. Note If an error occurs during form submission to E-Forms Manager, an error message displays. Refer to Error cases for more details. 2. The following transaction information displays on the receipt page. Date/Time. The date and time of transaction Transaction ID. The assigned unique identification number for the transaction Authorization Code. The authorization or approval code for the transaction Description. The transaction description that was specified by the FormPay Handler Payment Method. The credit card type and last four digits of credit card Total. The amount of the transaction Invoice Number. The invoice number that was provided for the transaction Billing Information. The billing information provided for the payment 4

5 10. If the transaction is declined or an error occurs processing the transaction, the following information displays. Date/Time. The date and time of transaction Transaction ID. The assigned unique identification number for the transaction Reason. The text that details the specific reason for the declined transaction or processing error Prerequisites You must complete the following procedures before the FormPay feature can facilitate credit card payments from a TransForm form. You only need to complete these procedures one time regardless of the number of forms that use the FormPay feature. 1. Set up an Authorize.Net Merchant account. 2. Configure E-Forms Manager and ifiller installations. 3. License FormPay. Set up an Authorize.Net Merchant account To facilitate credit card payments with TransForm e-forms, you need to set up an e-commerce (Card Not Present) Authorize.Net Payment Gateway account. Once the Authorize.Net account is set up, then the Authorize.Net Merchant Interface is used to customize the account and retrieve the necessary information to configure the FormPay related items in E-Forms Manager. Configure the E-Forms Manager and ifiller installations All instances of E-Forms Manager and ifiller that will process live credit card transactions must be configured to allow secure connection to the credit card payment processor. For E-Forms Manager and ifiller to facilitate credit card payments, you must configure the installations as follows. 1. The E-Forms Manager and ifiller instance must be configured to run over SSL using the standard HTTPS port of The E-Forms Manager and ifiller instance must be configured to be publicly accessible. Reverse proxy configurations Environments that use a web server (such as Apache and Microsoft IIS) to reverse proxy requests to E- Forms Manager and ifiller must ensure that the host name from the original incoming request is passed as the host when the request is proxied. In Apache, this can be achieved by turning the ProxyPreserverHost directive on, and a similar property can be set for IIS. Other web servers should also have a similar way to configure this behavior. Configure Authorized.Net Merchant Account Response Relay URL You must set the Response Relay URL in the Merchange Account to the correct FormPay Response Relay URL for Authorize.Net to send the transaction response back to the FormPay process. To set the Relay Response URL, complete the following steps. 1. Log in to the Authorize.Net Merchant Interface. 5

6 2. On the top menu (such as Home, Tools, Reports), click Account. 3. In the left pane, click Settings. 4. On the Settings page, under Transaction Response Settings, click Response/Receipt URLs. 5. On the Default Relay Response URL row, click Edit. 6. Enter the URL as <ifiller Server URL>/formpay/relay.jsp, where <ifiller Server URL> is the Server URL that is specified in the ifiller section of the Administration tab. For example, if the ifiller Server URL is set to then the Response Relay URL would be 7. To save the URL, click Submit. A message displays indicating that the Relay Response setting has been successfully applied. 8. To verify the Default Relay Response URL, click Settings and then click Response/Receipt URLs. Note If the Authorize.Net merchant account is used by more than one E-Forms Manager or ifiller instance, such as a different ifiller Server URL, you need to add each of the FormPay Relay Response URLs to the list of Response/Receipt URLs. You can do this by clicking the Add URL link on the Response/Receipt URLs page. License FormPay The FormPay feature is an optionally licensed feature. As such, the E-Forms Manager license must have this feature enabled for the feature to be enabled in E-Forms Manager. FormPay configuration The following procedures provide an overview of the steps required to configure FormPay for a form. 1. Add FormPay to the TransForm Form s design. 2. Configure a FormPay Merchant account. 3. Configure a FormPay Handler. 4. Test the TransForm Form. Add FormPay to the TransForm Form s design For a TransForm e-form to facilitate credit card payments through FormPay, the form design needs to contain specific objects. You can add the following FormPay related objects to the form design. Design Objects Required Description FormPay button and hidden field A pre-configured FormPay button and hidden field is provided in the Designer FormPay Catalog. This button, which contains a Remote Command that initiates the FormPay transaction along with the required hidden field, must be placed on the form for the FormPay functionality to work. 6

7 Amount field ly Required If the amount of the transaction should be specified by the form, then the form design should contain an EditBox field that collects the amount. The EditBox field must: contain validation that ensures a value is provided in the field ensure that the value entered is a valid monetary amount (without the dollar sign) Invoice ID field ly Required If the form specifies an Invoice ID, then the form design should contain an EditBox field that contains a unique identifier. This field is usually read-only and populated by the FormID feature. Billing Information fields ly Required If the billing information for the transaction is provided by fields in the form, the form design should contain EditBox fields that collect the appropriate billing information. FormPay Result fields To have the results of a successful FormPay transaction populated into the form, the form design should contain specifically named EditBox fields. These EditBox fields can be visible or hidden. Refer to the FormPay Result Fields section for the naming requirements of the fields. A set of FormPay Result fields is provided in the Designer FormPay Catalog. Designer FormPay catalog Starting with E-Forms Manager version 8.3.0, a FormPay Catalog is installed to My Forms\E-Forms Manager Sample Forms if you select the E-Forms Manager Sample Forms install during installation. FormPay result fields Following a successful credit card transaction, certain transaction results can be stored in the TransForm e-form before it is submitted to E-Forms Manager. The following table lists the transaction results that are populated into specifically named form fields if they exist on the form. Transaction Result EditBox FieldCode Description Authorization Code formpay_auth_code The transaction authorization or approval code that is generated by Authorize.Net Transaction ID formpay_trans_id The assigned unique identification number for the transaction that is generated by Authorize.Net Amount formpay_amount The amount of the transaction Card Type formpay_card_type The type of credit card Card Last Four formpay_card_last_four The last four digits of credit card 7

8 Configure FormPay merchant account A FormPay Merchant Account specifies the information for the merchant account that is used to process credit card payments. FormPay Merchant Accounts are defined in the Administration tab under FormPay. Use the information in the following table to configure a FormPay Merchant Account. Field Description Required Input Account Name The name assigned to the Merchant Account for identification within E-Forms Manager Enter a unique descriptive name for the merchant account. Account Type The type of merchant account that is used to process credit card payments Select Authorize.Net Live to process real credit cards with a live payment gateway account. Select Authorize.Net Development to use a development test payment gateway account to process test credit cards. API Login ID The Authorize.Net merchant API Login ID Enter the API Login ID that is specified in the Authorize.Net Merchant Interface. Transaction Key The Authorize.Net merchant Transaction Key. The Transaction Key is sensitive information and should not be shared, written down, or stored where it could be retrieved. Enter the Transaction Key that is specified in the Authorize.Net Merchant Interface. Payment Enabled? A flag that indicates whether payments are enabled through this merchant account. Disabling payments to a merchant account causes forms that use this merchant account not to accept payments. Select the check box to enable payment; deselect the check box to disable payment. 8

9 Configure FormPay handler A FormPay Handler is the configuration for a form version that specifies the merchant account and payment information that is used during the FormPay transaction. You can configure the following information for a form version s FormPay Handler. Note Only one FormPay Handler can be configured for a form version. Field Description Required Input Merchant Account The Merchant Account that is used to facilitate the payment Select the merchant account. Description description of the transaction Enter a description that, if supplied, is available for display on Authorize.Net payment form. Amount Placeholder or static value that is used as the transaction amount Either enter a dollar amount (without the dollar sign; for example, 25.50) or select a constant or form field that provides the amount for the transaction. Invoice ID Form field that provides the unique Invoice Id for the transaction Select a form field that provides the unique Invoice Id for the transaction. You can enter the following billing information in the second step of the FormPay Handler setup wizard. Field Description Required Input First Name Form field that provides customer s first name. If supplied, the value of the selected form field populates the First Name (Billing Information) field on the Authorize.Net payment form. provides the customer s first name. Last Name Form field that provides the customer s last name. If supplied, the value of the selected form field populates the Last Name (Billing Information) field on the Authorize.Net payment form. provides customer s last name. Company Form field that provides the customer s company. If supplied, the value of the selected form field populates the Company (Billing Information) field on the Authorize.Net payment form. provides customer s company. 9

10 Field Description Required Input Address Form field that provides the customer s address. If supplied, the value of the selected form field populates the Address (Billing Information) field on the Authorize.Net payment form. provides customer s address. City Form field that provides the customer s city. If supplied, the value of the selected form field populates the City (Billing Information) field on the Authorize.Net payment form. provides customer s city. State Form field that provides the customer s state. If supplied, the value of the selected form field populates the State (Billing Information) field on the Authorize.Net payment form. provides customer s state. Zip Code Form field that provides the customer s zip code. If supplied, the value of the selected form field populates the Zip Code (Billing Information) field on the Authorize.Net payment form. provides customer s zip code. Country Form field that provides the customer s country. If supplied, the value of the selected form field populates the Country (Billing Information) field on the Authorize.Net payment form. provides customer s country. Phone Form field that provides the customer s phone. If supplied, the value of the selected form field populates the Phone (Billing Information) field on the Authorize.Net payment form. provides customer s phone. Form field that provides the customer s address. If supplied, the value of the selected form field will populate the (Billing Information) field on the Authorize.Net payment form. will provide customer s address. Test the TransForm form You should thoroughly test a form that utilizes the FormPay feature before publishing the form and making it available to end users. Test the form s validation, FormPay configuration, and interaction with the payment gateway to ensure the form correctly facilitates credit card payments. When testing the interaction with the payment gateway, the testing should be done in two phases. The first phase involves placing the live payment gateway in Test Mode and submitting test transactions. If the testing is successful in this phase, the second phase involves submitting live transactions with a real credit card to verify that it is processed correctly. 10

11 Test Mode in a live environment You can place a merchant payment gateway account in Test Mode to allow test transactions to be processed without the transaction being submitted to financial institutions. Test transactions submitted in Test Mode are not stored in the Merchant Interface. To test transactions, complete the following steps. 1. Place the merchant payment gateway account in Test Mode. Refer to Turn Test Mode on or off. 2. Complete the steps in the Test steps section. 1. When entering a credit card number, use one of the following test credit card numbers: Visa Test Card: Second Visa Test Card: American Express Test Card: Discover Test Card Ensure the expiration date is set to the current date or later. Live Mode in a live environment To process real credit card transactions, the merchant payment gateway must be in Live Mode. Transactions submitted in live mode are processed and submitted by a financial institution and the transactions are stored in the Merchant Interface. To test a transaction, complete the following steps. 1. Place the merchant payment gateway account in Live Mode. Refer to Turn Test Mode on or off. 2. Complete the steps in the Test Steps section below. In Live Mode, you must use a real credit card number. You can use any valid credit card number to submit a test transaction. You can void successful transactions immediately to prevent live test transactions from being processed. This can be done quickly on the Unsettled Transactions page of the Merchant Interface. It is recommended that when testing using a live credit card, you use a nominal value, such as $0.01. For VISA verification transactions, you can submit a $0.00 value instead. Bill To address and zip code are required for VISA verification transactions. Turn Test Mode on or off To modify the Test Mode setting for a merchant payment gateway account, complete the following steps. 1. Log in to the Authorize.Net Merchant Interface. 2. On the top menu (such as Home, Tools, Reports), click Account. 3. Under Security Settings, click Test Mode. 4. The Test Mode page displays the current mode of the account. Click the Turn Test ON button to place the account in Test Mode. Click the Turn Test OFF button to place the account in Live Mode. 11

12 Test steps To test a transaction, complete the following steps. 1. In E-Forms Manager, ensure that the form version s FormPay Handler is enabled. Also, ensure that the FormPay Merchant Account that is used by the FormPay Handler has payment enabled. 2. View the form to be tested with ifiller. 3. Enter the required information for the form. 4. Click the Pay button on the form. 5. If all the required information is provided, the Authorize.Net payment form displays. If an error occurs prior to the display of the Authorize.Net payment form, an error message displays. 6. Enter the appropriate required information in the payment form. 1. Check to make sure that any payment information that was configured in the FormPay Handler to be populated from the form is populated correctly. For example, verify that the description and billing information displays. 2. For credit card number and expiration date, enter the appropriate information for the phase of testing that is being performed. 7. Click the Submit button. 8. Review the transaction details on the receipt page. 9. If the transaction is approved, ensure that the form is successfully submitted to E-Forms Manager. Error cases The following sections describe errors that may occur during different stages of the transaction process. Errors prior to display of the Authorize.Net Payment form After a FormPay Pay button is clicked, if an error occurs prior to the display of the Authorize.Net payment form, an ifiller dialog box displays the message: Payment cannot be completed at this time. Your credit card has not been charged. Please try again and if you continue to receive this message, please contact the form provider. Code:Code# The Code# at the end of the message is a number indicating the type of error that has occurred. The table below lists the possible code along with its cause and description. Code Cause Description 0 General Error A general error has occurred that does not match any of the other causes. The E-Forms Manager and ifiller logs need to be checked to get more information about the problem. 1 Invalid License The E-Forms Manager license is not valid. This could be caused by an expired license or if the submissions have surpassed the licensed submission capacity. 2 FormPay Feature Not Licensed The E-Forms Manager license does not contain the FormPay feature. Upload a license that contains FormPay. 12

13 3 FormPay Handler Not Configured 4 FormPay Handler Disabled The FormPay Handler has not been defined for the form version. Define a FormPay Handler for the form version to resolve the error. The form version s FormPay Handler is defined but disabled. Enable the FormPay Handler to resolve the error. 5 Form Version Not Found The form version specified in the FormPay request cannot be found. This error is unlikely and if it occurs, the cause is probably due to misconfiguration of E-Forms Manager and ifiller or caused by another system error. 6 Form Processing Disabled Form processing for the form version is disabled. Enable form processing for the form version to resolve the error. 7 Submission Disabled Submission of the form version is disabled. Enable submission for the form version to resolve the error. 8 Merchant Account Disabled The Merchant Account that is selected to be used by the FormPay Handler has payment disabled. Enabled payment for the Merchant Account to resolve the error. Errors after an Authorize.Net Processes transaction The following table lists the errors that can occur after Authorize.Net processes a transaction but prior to the receipt page displaying in ifiller or prior to the form being submitted to E-Forms Manager. Cause This error occurs after the user clicks the Submit button on Authorize.Net payment form but prior to the receipt page displaying in ifiller. The Authorize.Net Transaction ID is not available. This error occurs after the user clicks the Submit button on Authorize.Net payment form but prior to the receipt page displaying in ifiller. The Authorize.Net Transaction ID is available. This error occurs after the user clicks the Submit button on Authorize.Net payment form and receipt page displays in ifiller, but before the form is successfully submitted to E-Forms Manager. Error Message An error occurred while trying to report your payment transaction to the merchant. It is advisable for you to contact the merchant to verify that you will receive the product or service. An error occurred while trying to report your payment transaction to the merchant. It is advisable for you to contact the merchant and provide them with the Transaction ID TransactionID to verify that you will receive the product or service. TransactionID is the Transaction ID of the transaction. An error occurred while trying to report your payment transaction to the merchant. The result of the payment transaction may be viewed on the page below. It is advisable for you to contact the merchant and provide them with the Transaction ID to verify that you will receive the product or service. 13