Vantiv Integrated Payments

Transcription

1 Vantiv Integrated Payments Installation Best Practices 11/10/2017

2 Contents Overview... 2 Installation Best Practices Recommended tripos Direct Installation Options Configuration Settings: Dealer Letter and Merchant Setup Sheet Device Set Up: USB or IP Validate Lane/Device Configurations Validate tripos is Ready!... 7 Additional Resources on our developer network: Vantiv O.N.E. developer.vantiv.com... 8 FAQ tripos Direct Installation Frequently Asked Questions... 8 Final Summary: Your tripos Installation Configuration Checklist... 8 Appendix: Install Methods... 9 Silent Install using the Command-Line... 9 Install using the tripos Setup Wizard Preserving tripos.config Settings When Updating Versions The tripos.config file The tripos.config Backup preservation process logic Finalizing the tripos.config backup Logging of the Install Process P a g e

3 Overview The purpose of this document is to outline technical details on the tripos Direct installation procedures and to supply POS developers with specific tripos Direct installation best practices. This document is intended for ISVs who have completed a tripos Direct certification and who are building out their own POS specific implementation documentation. Please contact certification@vantiv.com for ISV technical, integration or installation questions. Installation Best Practices 1. Recommended tripos Direct Installation Options There are two options to incorporate the tripos installation into your POS Install: Silent Install/Command-line: package the tripos installation with your software installation processes for a consistent and streamlined install. We highly recommended running the installer from the command-line. Details on the Silent Install available here. Setup Wizard: the tripos Setup.exe enables the tripos installation with screen prompts for insertion of initial tripos configuration details. Details on running the tripos Setup.exe available here. The tripos Setup.exe is available within the tripos SDK (Software Development Kit) from our MFT (Managed File Transfer) site for development. IMPORTANT: Do not use this site to distribute the tripos SDK for merchant installs. Vantiv hosts new versions which could cause issues if not properly tested with your POS application. 2. Configuration Settings: Dealer Letter and Merchant Setup Sheet When your merchant account is enrolled with Vantiv, you will receive a Dealer Letter with merchant account details. Steps 1-4, outlined in the example letter below, are used to access your merchant credentials. You will use this information to configure the merchant settings. 2 P a g e

4 Example Dealer letter/var Sheet: 3 P a g e

5 Example Merchant Setup Sheet: 3. Default tripos Location, Authentication, Settings and Configurations The following information explains the default settings and configuration within the tripos.config file. If these defaults have been programmatically altered during or after your installation process, please note this in your installation instructions. a. Default tripos.config location: 1. C:\Program Files\Vantiv\triPOS Service\triPOS.config (32-bit) 2. C:\Program Files (x86)\vantiv\tripos Service\triPOS.config (64-bit) b. developerkey and developersecret The installer creates two entries for the developerkey and developersecret for each install of tripos. These are used to authenticate requests sent to tripos; they do not expire. These can be set to any value as long as the developerkey is unique within the file. 4 P a g e

6 developerkey: This is the key that is transmitted in the clear part of the header with each request to tripos developersecret: This is the secret that is used to sign each request to tripos We recommend using a GUID as a value for these entries. c. Default Settings/Configurations Make sure you carefully review all the settings within the tripos.config file. Each field impacts the cardholder experience and how transactions process through the POS. Validate and confirm the following key settings: Default Setting Configuration Notes acceptorid accountid Credential obtained from your Merchant Setup Sheet. accounttoken <testmode>true</testmode> <allowpartialapprovals>true</ allowpartialapprovals> <isemvsupported>false</ isemvsupported> <istipallowed>false</istipallowed> <marketcode>retail</marketcode> Determines if hitting Cert/Test or Production platform. Must be set to "false" to process in Production. Enables Partial Approval support; a card brand requirement. Must be set to "true" for card-present merchants. Determines if EMV is supported. Must be set to "true" to process EMV. NOTE: If using Express as a Gateway to another processor, it is important to first confirm with your account representative that EMV is supported. Determines if tipamounts are applied to the transactionamount. Must be set to "true" for the tip to be applied to the total transactionamount. Indicates the industry of the POS. Make sure this matches the appropriate vertical. Example: Retail, FoodRestaurant, etc. (Other market codes found in the tripos.config file) 5 P a g e

7 4. Device Set Up: USB or IP The following instructions explain how to set up your merchant's peripheral device within the tripos.config file. Note that we will use "device" in this document to refer to your peripheral PIN pad hardware. In the tripos.config file and in other tripos documentation, there are references to "terminal" and "Terminal ID". "Terminal" refers to the lane or workstation where tripos is installed. To change the settings programmatically use the available endpoints documented under port}/api/help on the machine where tripos is installed. ({listening port} here is specific to the port you have assigned if other than the default of 8080.) Please reference our sample USB and IP lanes within the local tripos.config. These are commented out "< - -" within the lane section. Once the device(s) are appropriately set up in the tripos.config file, stop and restart the service on the local machine where tripos is installed for the changes to take effect. Specific Set Up for USB Devices 1. For USB devices, download and distribute the appropriate EMV device driver with your application or host on your own site. (Device drivers are located on our MFT product download page where you initially accessed the SDK.) 2. Install the device driver. 3. Validate COM (Communications) port by going into the Windows Control Panel > Hardware and Sound > View Devices and Printers. 4. Update the tripos.config file with the appropriate "<comport>". 5. Make sure the "databits", "parity", "stopbits", "baudrate" in the tripos.config file match the Port Settings in Device Manager. 6. Start > Device Manager > Ports > (Select Device) > Right Click > Properties > Port Settings Specific Set Up for IP Address Devices 1. Obtain the device IP address. 2. Update the tripos.config file with the appropriate IP Address and IP Port. ipaddress The IP address of where the tripos service is located, most installs will be ipport The IP port that is being used by the EMV device, most installs will be P a g e

8 5. Validate Lane/Device Configurations The following configurations must be completed for each terminal using a tripos device: 1. Lane ID This is the lane to which the tripos device is assigned. This must be unique per terminal. Each terminal with an EMV device attached has a specific Lane ID which will be used to identify from which terminal an EMV transaction was executed. Example: Terminal 1 will use Lane ID 1, Terminal 2 will use Lane ID Terminal ID The Terminal ID will be the same as the Merchant number that is ed to the merchant when they board the account. IMPORTANT: If you have multiple devices in a tripos.config file, make sure to use the same terminalid or each device will have a separate batch. Example: Terminal 1 will use terminalid "0001", Terminal 2 will use terminalid "0001". 3. Driver Make sure the driver is correct based on the device being used: a. "VeriFoneFormAgentXpi" = VeriFone Mx915/Mx925 b. "VeriFoneXpi" = VeriFone Vx805 c. "VeriFoneCXpi" = VeriFone Vx805, Vx690 (CXPI) d. "IngenicoRba" = Ingenico Devices 4. Description Use the description configuration to identify the merchant's specific workstation or device, as in "Bar1" or "Front register". 5. Idle Screen Set the <message> or <image> you would like the device to display when not in use. NOTE: <image> is currently only supported with VeriFone Mx devices at this time. Please reference our Knowledge Base article for more information: 6. Validate tripos is Ready! To validate that tripos is successfully installed: 1. Go to port}/api/help on the workstation with tripos Installed. If tripos is installed you will be able to see the Version on this page in addition to accessing the Swagger Documentation and Release Notes. ({listening port} here is specific to the port you have assigned if other than the default of 8080.) 2. Go to Windows Services and validate that you have the tripos.net service running. 7 P a g e

9 Additional Resources on our developer network: Vantiv O.N.E. developer.vantiv.com tripos Direct Release Notes: tripos Integration Guide: Express Interface Specification Guide: FAQ tripos Direct Installation Frequently Asked Questions To join our developer community where you can post questions and/or add comments please create an account at developer.vantiv.com and join us here: 1. My device was working and seems to have disconnected and is no longer communicating with tripos. How do I correct this? Stop and restart the tripos service within the Windows Services menu. 2. Who should my merchants contact if they are having trouble with processing? Merchants may reach out directly to our Tech Support team at for assistance. 3. Who should I contact to add functionality or to get more information on best practices with tripos? Contact certification@vantiv.com for any technical/integration questions related to the POS. 4. What is lane "9999" and do I need this in my tripos.config? This is a "test lane" that is added to the tripos.config file to validate that the POS is communicating with the tripos service. This can be removed. Final Summary: Your tripos Installation Configuration Checklist Right OS? the install will only work on: o Windows 7 (Professional/Enterprise 32/64 bit). o Windows 8.1 (Professional/Enterprise 32/64 bit). o Windows 10 (Professional/Enterprise 32/64 bit). 8 P a g e

10 Listening port open? (default = 8080) allow the following IP port ranges: o to Port 443. o to Port 443. o to Port 443. o to Port 443. Is COMMTYPE correct? on reboot validate o USB = COMMTYPE:USB o IP = COMMTYPE: TCPIP COMM values match? be sure they are the same on reboot: o USB device ComPort in Device Manager = COM value in tripos.config file o IP Device Device IP Address = IP Address tripos.config file Be sure Anti-Virus isn t blocking check on computer: o View Anti-Virus logging Call Tech Support for help and have: o Verbose log o tripos.config file Please contact certification@vantiv.com for ISV related technical, integration or installation questions. Appendix: Install Methods Silent Install using the Command-Line tripos can be installed silently through the command-line. Below is a sample command: /q This tells the installer to run silently so that it does not display any UI components. USERCOMPANY This is the company name that will be displayed on the PIN pad s welcome message. INSTALLFOLDER Use this optional argument to change the default install folder path where you would like tripos to be installed. 9 P a g e

11 The following tripos.config values can be set through command-line arguments during the silent install. Details and descriptions on these arguments are available in the tripos Integration Guide available at 10 P a g e

12 Install using the tripos Setup Wizard 1. The tripos installer is packaged within the tripos SDK.zip files. Double-click on tripos Setup.exe to launch the setup wizard. 2. The first screen is the TRIPOS SOFTWARE LICENSE AGREEMENT: 3. To select a custom installation directory, click Options and enter the desired location. The default installation paths are: 64-bit machine: C:\Program Files (x86)\vantiv\tripos Service 32-bit machine: C:\Program Files \Vantiv\TriPOS Service 4. Review the End User License Agreement and click I agree to the terms and conditions, then click Install. 5. The next screen is Configuration Information. Enter your Express credentials here. All fields are required to continue with installation. These credentials can be edited later by manually editing the tripos.config file in Admin mode. 11 P a g e

13 Note: For a list of each field, see the table of arguments under Silent Install in the previous section or review the full argument descriptions in the tripos Configuration section in the tripos Integration Guide on Vantiv O.N.E.: Click Next to reach the Completed the tripos Setup Wizard screen. 5. Click Finish to reach the Setup Successful screen. 12 P a g e

14 Preserving tripos.config Settings When Updating Versions The tripos.config file The tripos.config file contains the Express credentials, lane configuration and transaction-related settings. After installing tripos for the first time, you will use the tripos.config file to customize individual merchant setting or establish a custom config build that is maintained from merchant to merchant and across tripos versions. In order to preserve your custom tripos.config settings when updating to a newer version, tripos automatically creates a backup configuration file. With versions and greater, the installer can find and use your most recently created backup to produce a new tripos.config file that contains your preserved settings from your previous custom version as well as any new tripos settings. Regardless of the installer s capabilities, it is always recommended to create a backup of the tripos.config file to save your settings in case of an error. The tripos.config Backup preservation process logic To preserve the most recent backup, the installer preservation process logic goes through the following steps: 1. Reviews the registry for the directory of the previous version 2. Attempts to find all backup files named "tripos.config.2" 3. If more than one backup file is found, the installer selects the most recently created backup to use during the upgrade. 4. If no previous install path is found in the registry, or that directory does not contain any backups, the installer checks for backups in the current install directory 5. If a backup is found, the installer preserves these values before continuing to finalize the new tripos.config. 6. If a backup is not found, or it does not contain a supported version node, the installer continues to finalize the new tripos.config. Finalizing the tripos.config backup Once the backup config file is identified, the installer processes the command-line arguments that were passed in during the install or upgrade. 1. The command-line arguments take precedence over even the preserved settings, and are mapped directly into the tripos.config. Example: if your resulting tripos.config at this stage has an "allowpartialapprovals" value of "true", and you pass the argument "ALLOWPARTIALAPPROVALS=false" during the upgrade, the final value in the new tripos.config will be false. 2. The command-line argument map to the parallel configuration values in the tripos.config file except for the developer and lanes sections: The developer section in the tripos.config file may contain multiple sets of developer credentials but the installer only allows one set of developer key and secret to be passed in 13 P a g e

15 during install or upgrade. Additional developer credentials will need to be added directly to the tripos.config file and not included in the command-line arguments. Similarly, the lanes section in the tripos.config may contain multiple serial and IP lanes. The installer only allows one set of serial lane settings to be passed as command-line arguments. 1. If one or more lane setting is NOT null, the installer collects all of the lane argument values into one serial lane, which we will refer to here as the installer lane. 2. If the LANEID of the installer lane is found in the tripos.config file, the installer replaces the lane in the file with the entire installer lane (if some installer lane values are empty, they are written into the file as empty). 3. If the LANEID of the installer is not found in the file, or is empty, the installer inserts the entire installer lane into the file as a new serial lane. The installer does not perform validation on the command-line arguments that are passed during install or upgrade. If the command-line arguments contain invalid values or a misconfigured lane, tripos may not be able to start successfully, and the upgrade or install will fail. Make sure to fully test your command-line arguments in a test environment to verify that they are valid. Logging of the Install Process It is recommended to run the installer from the command-line (either silent or manual) to take advantage of the logging that occurs throughout any installer process. To capture the logs, run the following command to launch the installer: "tripos Setup.exe" l log.txt The -l (lowercase L) argument specifies that the logs are to be written to the file specified as the second argument, log.txt. To install silently, add the /q argument as illustrated below: "tripos Setup.exe" /q l log.txt In either case, this command will produce two logs files. One is called log.txt (or the name you ve provided in the command) which holds the logs of the executable Bootstrapper that wraps the.msi installer. The second log is called log_000_tripos.txt which contains the bulk of the installer s logs. Here, you can follow the process and custom actions that execute throughout the installation or upgrade. 14 P a g e