Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
getting_started:windows:1.4.10_-_1.5.2 [2019/11/01 11:27]
branko
— (current)
Line 1: Line 1:
-====== Getting Started with Windows ====== 
  
-~~TOC~~ 
- 
-\\ 
-The %BRANDNAME SDK is a library for communicating with the %GATEWAYNAME Payment Gateway. It wraps a set of interfaces and logic that  connects the **Payment Gateway**, the **Card Reader Devices** and the client'​s side security. 
- 
-This page presents the basic steps to build your own solution using our SDK.  
-\\ 
- 
-<WRAP round box 100%> 
-**NEW DOCUMENTATION VERSION** 
- 
-This guide is applicable from SDK Version **__1.4.10__** and **__1.5.2__**. For older versions, use the menu navigation on the left side of this page. 
-</​WRAP>​ 
- 
-\\ 
-===== Step 01 - Download The Components ===== 
- 
-You can find our current supported version at the **[[:​sdk_versions:​windows|Download SDK Versions]]** page. 
- 
-<WRAP round box 100%> 
-**REMEMBER TO SELECT YOUR PLUGINS** 
- 
-Select the **Plugins** you'll be using in your application. That depends on the **Card Reader Devices** you are going to use. 
-If you don't want to start from scratch, also download the **Sample App** provided to the version. This App will give you a good start point for you POS project. 
- 
-</​WRAP>​ 
- 
-\\ 
-===== Step 02 - Create Your Project and Install the SDK ===== 
- 
-<WRAP round box 100%> 
-**REQUIREMENTS** 
- 
-This platform and version targets the .Net Framework 4.5.1 
-</​WRAP>​ 
- 
-The installation of the SDK is as easy as adding the %BRANDNAME SDK to your project. For that you need: 
- 
-  * **I)** ​ Extract the %BRANDNAMESDK.zip. 
-  * **II)** Copy **%coreSDKLibNameWINDOWS**, ​ **common.dll**,​ **rest-connector-wn.dll**,​ **NewtonSoft.Jsoon.dll** and **HashLib.dll** from the libraries downloaded folder to the application folder. 
-  * **III)** ​ In solution explorer, right click the project file and select Add reference. Find coresdk.dll,​ NewtonSoft.Jsoon.dll and HashLib.dll and click OK. 
-  * **IV)** ​  Add the payconfig.xml into your project. Select payconfig.xml,​ in the file properties select under “Copy to Output Directory” to “Copy Always”. Select under Build Action to “Content”. 
- 
-The **payconfig.xml** file contains URLs used to access the servers, so don't forget to add it to your project, or the communication is not going to happpen. 
- 
-If you want to start with the Sample App, just follow the steps of creating a new project from an existing source. Each IDE works in a different way, but when creating a new project, most offer an option to create based on an existing project or based on source files where you just have to point to a repository. This repository would be the decompressed folder of the Sample App in the last step of the previous section. 
- 
-\\ 
-===== Step 03 - Implement the CoreAPIListener ===== 
- 
-The application needs to implement the Core API Listener (CoreAPIListener) to interact with the SDK.  
- 
-On Windows this makes the most sense in the MainPage, as follows: 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-public sealed partial class MainPage : Page, CoreAPIListener{ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
-\\ 
- 
-For further reading on CoreAPIListener,​ consult the **[[sdk_documentation:​windows:​coreapilistener|Core API Listener]]** page at the **[[sdk_documentation:​windows|SDK Documentation]]** section. 
- 
-\\ 
-The **CoreAPIListener** interface contains all the methods used for interactions. 
- 
-If your application contains multiple views, instead of each view conforming CoreAPIListener interface and implementing all of its methods, you can use the following listeners, which are suited for your views. 
- 
-<code csharp> 
-CoreAPIDeviceListener 
-CoreAPIReportingListener 
-CoreAPISaleListener 
-CoreAPISecureCardListener 
-CoreAPISettingsListener 
-CoreAPIRefundListener 
-CoreAPIReversalListener 
-CoreAPIUpdateListener 
-CoreAPIErrorListener 
-CoreAPIMessageListener 
-</​code>​ 
- 
-\\ 
-Then, register the listeners implementing the interfaces above: 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.RegisterCoreAPIDeviceListener(this);​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-===== Step 04 - Initialise the Terminal ===== 
- 
-  * **I)** ​  You should use the Terminal (singleton instance) provided by the SDK. 
- 
-Where ''​%%this%%''​ is an object that implements the CoreAPIListener (i.e. this code snippet is done inside the MainPage) 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.Initialize(this);​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-The terminal can also be initialized without CoreAPIListener 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.Initialize(System.Reflection.Assembly.GetExecutingAssembly());​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-Also, to establish SSL/TLS connection to the server, you need to add the following piece of code. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-ServicePointManager.SecurityProtocol = SecurityProtocolType.Ssl3 | SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12;​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-  * **II)** ​ Now, set the Terminal Mode, (TEST, DEV or LIVE), depending on your needs. 
- 
-This is an easy one as well.  
-All you have to do is to set the terminal mode to the right type. 
- 
-The **Test Mode** should be used for development - It's going to make your app to use the gatewayTestUrl defined in payconfig.xml when communicating with the server. 
-Before initiate your Terminal, enable the Test Mode: 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
- 
-<code csharp> 
-Terminal.Instance.SetMode(CoreMode.TEST);​ 
-</​code>​ 
- 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-After finishing the development of your app, don't forget to change the mode again to go Live (**Live Mode**, that points to gatewayLiveUrl defined in payconfig.xml file). 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.SetMode(CoreMode.LIVE);​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-You still have one option: the **Dev Mode**. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.SetMode(CoreMode.DEV);​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-The Dev Mode is used to point to gatewayDevUrl defined in payconfig.xml file. The Dev Host usually contains unreleased features. 
- 
-\\ 
-  * **III)** ​ Now, set the Terminal Log Level (NONE, ERROR, TEST or FULL), depending on your needs. 
- 
-This is also an easy one. All you have to do is to set the terminal log level to the right type. 
- 
-  * **LEVEL_FULL**:​ This level will allow SDK to print all logs into the log file and the console. Level FULL will be default level for TEST or DEV mode. 
-  * **LEVEL_TEST**:​ This level will allow SDK to print logs which do no contain any sensitive data e.g. requests and responses to the server, tlv strings, emv tags, encrypted data, etc. Level Info will be default level for LIVE mode. 
-  * **LEVEL_ERROR**This level will allow SDK to print only errors. Any error that occurs in the SDK, any error that the server returns, any error that the device returns. No other logs such as events, method calls will be printed. 
-  * **LEVEL_NONE**:​ This level will disable logs in the SDK. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.SetLogLevel(LogLevel.LEVEL_FULL);​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-  * **IV)** Once the Terminal is created, initialize it. 
- 
-{gateway=docs.gochipnow.com}{gateway=gochip.payconexplus.com}{gateway=corepay.anywherecommerce.com}{gateway=docs.nuvei.com}{gateway=testdocs.gochipnow.com}{gateway=testgochippayconexpluscom.worldnettps.com}{gateway=testcorepayanywherecommercecom.worldnettps.com}{gateway=testdocsnuveicom.worldnettps.com} 
- 
-The arguments are the terminal ID and secret. These are credentials required to use a Terminal using the SDK. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.InitWithConfiguration(TERMINAL_ID,​ SECRET); 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-{/gateway} 
- 
-\\ 
-{gateway=bluechip.payconex.net}{gateway=testbluechippayconexnet.worldnettps.com} 
- 
-The arguments are the account ID and API access key. These are credentials required to use a Terminal using the SDK. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-Terminal.Instance.InitWithConfiguration(ACCOUNT_ID,​ API_ACCESS_KEY);​ 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-{/gateway} 
- 
-===== Step 05 - Handle the Initialisation Response ===== 
- 
-Once the Terminal is initialized,​ it is necessary to handle all response types. 
- 
-The Terminal initialization attempts to connect to the server and the response must then be verified. The SDK does that with the methods: **OnError** and **OnSettingsRetrieved**. 
- 
-==== Successful Response ==== 
- 
-If your initialization worked properly, without problems, your application is going to receive the response at the **OnSettingsRetrieved** method. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-public void OnSettingsRetrieved(CoreSettings settings) { 
- // ... 
-} 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
- 
-\\ 
-You need to use the argument returned to extract the response. 
- 
-==== Unsuccessful Response ==== 
- 
-If anything went wrong with the initialization,​ your application is going to receive an error at the **OnError** method. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> 
-<li data-code="​csharp">​ 
-</​html>​ 
-<code csharp> 
-public void OnError(CoreErrorType error) { 
- // ... treatment for initialization error 
-} 
-</​code>​ 
-<​html>​ 
-</li> 
-</ul> 
-</​div>​ 
-</​html>​ 
- 
-\\ 
-In the event of an error, your application can show the error text, a generic message or execute a particular action, based on the error. 
- 
-===== Step 06 - Plugin Installation ===== 
- 
-**For Ingenico devices** 
- 
-  * **I)** On 32 bit systems the environment variable “Path” should be set correctly to ensure all the RBA_SDK dlls in “Resources” folder can be found by the application. Copy the path to “Resources” folder(contains necessary DLLs) and add this path to your machine’s Environment System Variable "​PATH"​. 
-  * **II)** On 64 bit systems. RBASDK.DLL is a 32-bit library and it needs to be run in 32-bit compatibility mode on a 64-bit machine. To do this, copy all the dlls from “Resources” folder to “C:​\Windows\SysWOW64” folder. 
-  * **III)** Microsoft runtime libraries(msvcp100.dll,​ msvcp110.dll,​ msvcr100.dll,​ msvcr110.dll) should also be installed in the system if not already installed. You can either install ‘Microsoft Visual C++ Redistributable Package (x86)’ or you can manually copy these DLLs in “C:​\WIndows\SysWOW64” folder. 
-  * **IV)** Copy ingenico.dll and RBA_SDK_cs.dll from the extracted folder to the application folder. 
-  * **V)** In solution explorer right click the project file and click Add reference. Find ingenico.dll and RBA_SDK_cs.dll and click OK. 
-  * **VI)** Make sure the target is set to x86 architecture. 
- 
-**For Idtech devices** 
- 
-  * **I)** Copy all dll files from the extracted folder to the application folder. 
-  * **II)** In solution explorer right click the project file and click Add reference. Find idtech.dll and IDTechSDK.dll and click OK. 
-  * **III)** In solution explorer right click the project file and click Add Existing item. Find all other dll files and click Add. Select each dll file under properties select under "Copy to Output Directory"​ to "Copy Always"​. 
-\\ 
-  ​ 
-===== Step 07 - Initialize the Device ===== 
- 
-Now we can initialize the device using our Terminal. 
- 
-The **first** argument is a DeviceEnum corresponding to the device your application is going to use. The **second** argument is a connection type. The **third** argument is used when it's necessary to send details to establish the communication. 
- 
-**For Ingenico Devices** 
- 
-In this scpecific case, we have to inform the portName to be used. The "​portName"​ is a serial port where the device is connected to. 
- 
-<​html> ​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> <li data-code="​csharp">​ </​html>​ 
-<code csharp> 
-string[] ports = System.IO.Ports.SerialPort.GetPortNames();​ 
-</​code>​ 
-<​html>​ </li> </ul> </​div>​ </​html>​ 
- 
-\\ 
-So, after getting the list of port names, add one of them to a data object and use it to init the device. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-<a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> <li data-code="​csharp">​ </​html>​ 
-<code csharp> 
-Dictionary<​string,​ object> data = new Dictionary<​string,​ object>​();​ 
-data.Add("​portName",​ ports[0]); 
-Terminal.Instance.InitDevice(DeviceEnum.INGENICO,​ DeviceConnectionType.USB,​ data); 
-</​code>​ 
-<​html>​ </li> </ul> </​div>​ </​html>​ 
- 
-\\ 
-**For Idtech Devices** 
- 
-Just init the device. 
- 
-<​html>​ 
-<div class="​code_block">​ 
-<div class="​nav">​ 
-    <a data-code="​csharp">​Windows</​a>​ 
-</​div>​ 
-<ul> <li data-code="​csharp">​ </​html>​ 
-<code csharp> 
-Terminal.Instance.InitDevice(DeviceEnum.IDTECH,​ DeviceConnectionType.USB,​ null); 
-</​code>​ 
-<​html>​ </li> </ul> </​div>​ </​html>​ 
- 
-\\ 
-===== Step 08 - Implement Your Features ===== 
- 
-For further reading on how to execute transactions (Sale, Refund, Report, etc.) visit the section **[[transaction_flows:​default_mode|Default Mode]]** and explore the options. ​ 
- 
-Also, in case you are interested in working with different flow configurations,​ like a offline terminal, visit **[[transaction_flows:​offline_mode|Offline Mode]]**, or with unattended terminals, visit **[[transaction_flows:​polling_mode|Polling Mode]]**. More options are also available in **[[:​transaction_flows|Transaction Flows]]**. 
- 
-The following pages will assist you in understanding and implementing your features: 
- 
-  * **[[secure_card:​|Secure Cards]]**: if you want to store your customers'​ details in a safe way using tokens. 
-  * **[[sdk_documentation:​|SDK Documentation Reference]]**:​ documentation reference of the SDK platform code. 
-  * **[[understanding_the_sdk:​|Understanding the SDK]]**: a little more about how the SDK works. 
-    
-If you have questions, please talk to us using the **[[:​contact|Contact]]** link at the top (right side) of this page. We would love to help!