Contents Welcome to Commerce SDK...5 Environment and Requirements for Commerce SDK...5 About This Release...6 What s in this Release?...6 Getting Started...6 Using the SDK...7 Explaining Commerce SDK s Architecture...8 Running the Sample Application...8 How to Get Commerce SDK Credentials...9 Performing a Transaction...9 Printing or Emailing a Receipt...12 Code Explanations...13 Transaction.begin...14 account.gettransactionprocessor()...17 Printing or Emailing a Receipt...18 Support Contacts...19
Welcome to Commerce SDK As a beta user of Commerce SDK, thank you for relying on us to support your payment system. The Commerce SDK will allow you to perform an EMV transaction using an Ingenico isc250 EMV-ready terminal as well as print receipts with the Star Micronics TSP650II printer. Let s look at some important information that is required to use Commerce SDK. Included in this SDK is This documentation Commerce SDK functionality Sample Java application that shows the usage of Commerce SDK Code snippets for initiating EMV transactions and printer transaction receipts Environment and Requirements for Commerce SDK Commerce SDK requires the following prerequisites: Java 1.7 32 bit (currently included in beta package) Windows 7+ USB Port Access (1 for isc250 + 1 for Printer) Direct Internet access 1. Software Development Kit. (n.d.). Retrieved June 30, 2015, from https://en.wikipedia.org/wiki/software_development_kit 5
About This Release This is an early, non-production release. Please report any issues or problems you encounter to CommerceSDKBetaFeedback@elavon.com. This release is intended for Developer use only. The only components in this release of the Commerce SDK that are functional are the EMV integration and the ability to perform EMV sales. What s in this Release? As mentioned, EMV integration and sales transactions are included. The devices that are supported include isc250 and the Star Micronics TSP650II printer. This release is for transactions that are supported through the Converge gateway (DEMO environment only). Getting Started You will be sent the following three files: 1. vcredist.zip 2. IngenicoUSBDrivers_2.60_setup.exe 3. ElavonCommerce.zip Unzip vcredist.zip. This will contain two redistribution files, one for 2012 and one for 2013. Install both files by double-clicking them. After installing the redistribution files, double-click IngenicoUSBDrivers_2.60_setup.exe. Please note, when you arrive at the below screenshot, you can click Next without entering any data. 6
Using the SDK Unzip the ElavonCommerce.zip to your computer s hard drive. This folder will contain all your working files for Commerce SDK. 1. jre7 - This folder contains all the Java 32-bit files and dependencies. 2. libs - This folder contains all of the jar dependencies for Commerce SDK. 3. nativelibs - This folder contains all the DLL dependencies for Commerce SDK. 4. desktop-sampleapp.bat - This batch file launches the sample application for learning Commerce SDK. 5. src.zip - This zip file contains the source code of the Desktop sample application. 7
Explaining Commerce SDK s Architecture The follow diagram shows how Commerce SDK interacts with your application, terminals, and Converge. As a 3rd Party Integrator you will need to create the Point of Sale (POS) application in the above image, providing the details required. The transaction information will then be passed by your application to Commerce SDK. Commerce SDK will then securely interact with the RBA Card Reader and transfer data to the Converge platform over the Web for authorization. Converge will send back a response, which Commerce SDK will then present back to your application. Your POS will also need to communicate with Commerce SDK to print receipts for your transactions. Please see Code Explanations on page 13 for more on what is specifically required from you. Running the Sample Application From your ElavonCommerce deployment folder, select the desktop-sampleapp.bat file. Desktop GUI will load. 8
From here you will need to get demo environment credentials in order to proceed. How to Get Commerce SDK Credentials In order to use Commerce, you will need Converge credentials. Converge is Elavon s omnipayments platform. For now, the process to acquire credentials requires calling or emailing Elavon support. The process to receive test credentials is as follows: 1. Call 800-377-3962 or e-mail techsupp@elavon.com 2. Be sure to say you are a Commerce SDK Beta Customer and need Converge Demo credentials. Support will ask for the following details: a. Your Company Name b. Primary Contact Name c. Primary Contact Number d. Primary Email Address 3. Within 24 hours after first contact, you will receive your test credentials. Please note, these test credentials will expire after 30 days. Performing a Transaction With your demo credentials, select Account from the top menu of the Desktop GUI application. On that menu, select Credentials and enter your demo environment credentials. 9
Now, select Account > Get Account Info to check your credentials. If the credentials are successful, you will see something close to this response: Tue Jul 07 09:49:20 EDT 2015 INFO: Get Account Info Tue Jul 07 09:49:21 EDT 2015 INFO: Account info retrieved: Tue Jul 07 09:49:21 EDT 2015 INFO: name:grove SERVICE Tue Jul 07 09:49:21 EDT 2015 INFO: currency:usd Tue Jul 07 09:49:21 EDT 2015 INFO: AccountListener accountdefaultcurrencydidchange USD Now, your deployment is prepared, connect your isc250 PIN pad via USB to the computer and to the printer. Now, in the Sample Application, select Transaction > Begin Transaction. You will have a pop-up asking for a transaction and tender type. Select your desired transaction and tender type and press OK. In the beta, only Transaction Type - SALE and Tender Type - CREDIT_CARD work. When you select OK, you ll be prompted to enter an amount for the transaction. Enter your desired value noting it is in minor units, meaning it assumes the last two digits are after a decimal place (e.g. 10000 = $100.00). Press OK to process this transaction. 10
Once you press OK, follow the instructions on the PIN pad. When you insert a card into the PIN pad, you will see the following result in the GUI. Finally, when the transaction has successfully finished, you will see the following. 11
Printing or Emailing a Receipt Select Transaction > Print Receipt or Transaction > Email Receipt. This will print or email the receipt. 12
Code Explanations The following code snippets (from the provided sample application) will cover the main processes of the SDK, namely beginning a transaction and printing or emailing a receipt. Please consult the source code inside of the src.zip to see the actual code. The majority of the transaction code is in Transaction.java. Before anything is done, the public class Transaction is created which contains the member variables that are required to initiate and complete an EMV transaction. 13
An important interface that must be implemented is the ECLTransactionProcessingListener. The functions declared in the ECLTransactionProcessingListener interface serve as callbacks during the processing of a transaction for Commerce SDK to provide progress updates, to notify of the completion of a transaction, to notify of the failure of the transaction, and to request information that Commerce SDK require to complete the transaction (such as a signature). In the sample code, you can see the provided implementation of the interface. Before starting a transaction, the application must have an instance of a transaction and of a tender. The sample app calls into Commerce SDK to request an instance of each of these interfaces based on the specific type. The supported types in this release are SALE and CREDIT_CARD. Now, we ll begin the transaction. Transaction.begin When the begin method is called, the user will be prompted for a transaction type and tender type. 14
Here we see the tender and transaction instances being requested from Commerce SDK. Commerce returns the instances. Now, we can begin processing the transaction. You will be prompted for the Amount Due, which is entered in minor units. Also, based on the transaction type, the user may be asked for Amount Tendered. After this step, all the information needed to process a transaction has been collected. processtransaction method is now called with the created ECLTenderInterface and ECLTransactionInterface. This method provides the implementation of the ECLTransactionProcessingListener protocol. 15
16
account.gettransactionprocessor() In the previous example, we can see how to pass values to Commerce. Let s focus on account. gettransactionprocessor(). When calling processtransaction, we pass three parameters: Transaction SALE (only one supported in Commerce SDK Beta currently) PRE_AUTH ACTIVATION RELOAD Tender: How are we paying (Cash, Credit, Debit) Listener: This parameter provides the implementation of the ECLTransactionProcessingListener protocol. You must provide a full implementation for ECLTransactionProcessingListener. For example, the shouldprovideinformation callback requires the integrator to include information like signature capture data, or a voice referral approval code. You should evaluate everything inside of ECLTransactionRequirementsInterface to determine what Commerce SDK expects. 17
Printing or Emailing a Receipt The printreceipt and emailreceipt methods both call a helper method which creates a receipt object based on an enumerated receipt output type. The helper method then calls the sendthereceipt method and passes the newly created receipt object and the receipt output type. sendthereceipt method contains an implementation of the ECLReciptProcessingListener protocol. For the receiptshouldprovidelocalizedpercentagetext override, you should return the amount in the figure parameter formatted as a percentage for the user s current locale. For the receiptshouldprovidelocalizedtext override, you should return a localized string for the ECLReceiptTextIdentifier using the user s current locale. These strings will be places on the receipt so you must provide for all possible values of the ECLReceiptTextIdentifier. For the receiptshouldprovidelocalizedminorunitstext override, you should return the amount in the amountinminorunits parameter formatted as a monetary value using the currencycode parameter. 18
Support Contacts Please contact CommerceSDKBetaFeedback@elavon.com for any issues that may arise with your Commerce SDK beta experience. 19