Datacap TranCloud Quick Start Guide

Document created by Chris Jennings on Dec 27, 2016Last modified by Chris Jennings on Dec 27, 2016
Version 2Show Document
  • View in full screen mode

Get started with the TranCloud™ solution

The TranCloud solution powered by Datacap Systems, Inc. enables browser based integrated payment processing by incorporating TranCloud Service and TranCloud Appliance.  The TranCloud integration begins with communication to the TranCloud service, which is hosted by Datacap Systems. The TranCloud server maintains an active connection with the TranCloud appliance physically located within the merchant’s location.

 

This document provides you with the basics to order test equipment, configure your equipment for test mode, submit required admin function commands and how to easily process a EMV Credit Sale transaction.  For more in-depth API guidelines, please refer to the following specifications:

  • The MercuryPay Platform Integration Guide provides important information about the MercuryPay platform including how to process different types of transactions, admin functions, and additional processing features such as tokenization and encryption. Your Implementations Consultant will provide you with a copy of this guide.
  • The dsiTranCloud MercuryPay Platform Integration Supplement Guide provides details specific to the TranCloud integration running on our MercuryPay processing platform.
  • The dsiTranCloud Web Integration EMV Specification provides details specific to TranCloud integration. This guide can be requested from Datacap. Go to http://www.datacapsystems.com/pos-developer-contact-form to request a copy of the specification.

 

Before you begin

  1. Test credentials, test EMV PIN pads and test cards can be requested from Vantiv Integrated Payments Developer Integration team.
  2. A test TranCloud appliance can be ordered through Vantiv Integrated Payments.
    • Every TranCloud appliance (testing and production) is assigned a TranDeviceID (format is PT##########).
      • The TranDeviceID must be provided to your Vantiv Solution Consultant to pair with a MerchantID test account.
    • Datacap will register an account with the TranCloud service for all testing and production processing.
      • During the registration, you will receive a unique username and password to identify your
        TranCloud Ports copy.jpgapplication program to the TranCloud Service.

 

Setup TranCloud appliance

The TranCloud appliances can be setup in three simple steps:  

  1. Connect the appliance to a router to receive a Dynamic IP Address.
  2. Attach the appliance to power.
  3. Connect your EMV PIN pad via Serial cable to the TranCloud appliance or router for an Ethernet or WiFi connection. Only one serial PIN pad can be connected to a TranCloud Appliance.

 

 

 

Configure the TranCloud appliance and EMV PIN Pad

When you are ready start testing, you must first set the TranCloud appliance in TestMode. This instructs the TranCloud appliance to use the MercuryCert servers instead of production servers.

 

Example XML TestMode Command Request

<?xml version="1.0"?>
<TStream>
<Admin>
    <MerchantID>337234005</MerchantID>
    <TerminalID>001</TerminalID>
    <OperatorID>TEST</OperatorID>
    <UserTrace>Dev1</UserTrace>
    <TranCode>TestMode</TranCode>
    <SecureDevice>CloudEMV1</SecureDevice>
    <SequenceNo>0010010010</SequenceNo>
    <TranDeviceID>PT9999999999</TranDeviceID>
    <PinPadIPAddress>10.0.0.155</PinPadIPAddress>
    <PinPadIPPort>1200</PinPadIPPort>
</Admin>
</TStream>

 

Example Response

<?xml version="1.0"?>
<RStream>
    <ResponseOrigin>Processor</ResponseOrigin>
    <DSIXReturnCode>000000</DSIXReturnCode>
    <CmdStatus>Success</CmdStatus>
    <TextResponse>TEST MODE ENABLED</TextResponse>
    <SequenceNo>0010010010</SequenceNo>
    <UserTrace>Dev1</UserTrace>
</RStream>

 

After the TranCloud appliance is set in TestMode, you are ready to download the latest EMV parameters and security information for an PIN pad. The command request EMVParamDownload should be preformed when a new device is first installed, when a device is replaced or a requested by the service provider.

 

Example XML EMVParamDownload Request

<?xml version="1.0"?>
<TStream>
<Admin>
    <MerchantID>337234005</MerchantID>
    <TerminalID>001</TerminalID>
    <OperatorID>TEST</OperatorID>
    <UserTrace>Dev1</UserTrace>
    <TranCode>EMVParamDownload</TranCode>
    <SecureDevice>CloudEMV1</SecureDevice>
    <SequenceNo>0010010010</SequenceNo>
    <TranDeviceID>PT9999999999</TranDeviceID>
    <PinPadIPAddress>10.0.0.155</PinPadIPAddress>
    <PinPadIPPort>1200</PinPadIPPort>
</Admin>
</TStream>

 

Example Response

<?xml version="1.0"?>
<RStream>
    <ResponseOrigin>Processor</ResponseOrigin>
    <DSIXReturnCode>000000</DSIXReturnCode>
    <CmdStatus>Success</CmdStatus>
    <TextResponse>Success/TextResponse>
    <SequenceNo>0010010010</SequenceNo>
    <UserTrace>Dev1</UserTrace>
    <TranCode>EMVParamDownload</TranCode>
</RStream>

 

Ready the PIN pad

To reset and ready the EMV PIN pad device, the EMVPadReset command must be performed before every transaction to assure that no card is in the EMV PIN pad chip card reader. This command should also be performed at the end of any card related transaction to notify the cardholder to remove their card.

 

Example XML EMVPadReset Request

<?xml version="1.0"?>
<TStream>
<Transaction>
    <MerchantID>337234005</MerchantID>
    <TerminalID>001</TerminalID>
    <OperatorID>TEST</OperatorID>
    <UserTrace>Dev1</UserTrace>
    <TranCode>EMVPadReset</TranCode>
    <SecureDevice>CloudEMV1</SecureDevice>
    <SequenceNo>0010010010</SequenceNo>
    <TranDeviceID>PT9999999999</TranDeviceID>
    <PinPadIPAddress>10.0.0.155</PinPadIPAddress>
    <PinPadIPPort>1200</PinPadIPPort>
</Transaction>
</TStream>

 

Example Response

<?xml version="1.0"?>
<RStream>
    <ResponseOrigin>Client</ResponseOrigin>
    <DSIXReturnCode>000000</DSIXReturnCode>
    <CmdStatus>Success</CmdStatus>
    <TextResponse>Reset Successful.</TextResponse>
    <SequenceNo>0010010010</SequenceNo>
    <UserTrace>Dev1</UserTrace>
</RStream>

 

Process an EMV Sale

Step 1: Collect and Format Transaction Information

Utilizing an object model set parameters needed to process a transaction. The example below shows a credit sale transaction. The class object is then serialized to JSON represented as a string and then passed to the TranCloud server.

 

var tranCloudTransaction = new TranCloudTransaction();
tranCloudTransaction.TStream = new TStream();
tranCloudTransaction.TStream.Transaction = new Transaction();
tranCloudTransaction.TStream.Transaction.Account = new Account();
tranCloudTransaction.TStream.Transaction.Account.AcctNo = "SecureDevice";
tranCloudTransaction.TStream.Transaction.Amount = new Amount();
tranCloudTransaction.TStream.Transaction.Amount.Purchase = "1.11";
tranCloudTransaction.TStream.Transaction.InvoiceNo = "1234";
tranCloudTransaction.TStream.Transaction.MerchantID = "1234";
tranCloudTransaction.TStream.Transaction.OperatorID = "test";
tranCloudTransaction.TStream.Transaction.PartialAuth = "Allow";
tranCloudTransaction.TStream.Transaction.RefNo = "1234";
tranCloudTransaction.TStream.Transaction.SecureDevice = "ONTRAN";
tranCloudTransaction.TStream.Transaction.TranCode = "Sale";
tranCloudTransaction.TStream.Transaction.TranDeviceID = "XYZ";
tranCloudTransaction.TStream.Transaction.PinPadIPAddress = new IPAddress ();
tranCloudTransaction.TStream.Transaction.PinPadIPPort = new IPPort ();

var json = new JavaScriptSerializer().Serialize(tranCloudTransaction);

 

Step 2: POST Request to TranCloud

Using the .net libraries a web request is made to the TranCloud server POSTing the JSON above. Note that you need an API username and password from Datacap prior to executing this sample code.

 

var request = (HttpWebRequest)WebRequest.Create("https://trancloud.dsipscs.com");
request.Method = "POST";
request.ContentType = "application/json";

var username = "username";
var password = "password";
var encoded = System.Convert.ToBase64String(System.Text.Encoding.ASCII.GetBytes(username + ":" + password));
request.Headers.Add("Authorization", "Basic " + encoded);
request.Headers.Add("User-Trace", "testing TranCloud.MVC.CSharp");
request.ContentLength = json.Length;
using (var webStream = request.GetRequestStream())
using (var requestWriter = new StreamWriter(webStream, System.Text.Encoding.ASCII))
{
    requestWriter.Write(json);
}

 

Step 3: Process and Display Response

TranCloud communicated with the local IPTran LT™ Mobile, the IPTran LT™ Mobile drives the pinpad device which prompts for customer interaction, the IPTran LT™ Mobile forwards the transaction package to Mercury for authorization, and then the response bubbles back to TranCloud and the POS.

 

var tranCloudResponse = new JavaScriptSerializer().Deserialize<dynamic>(response);
var rstream = tranCloudResponse["RStream"];
var cmdResponse = rstream["CmdResponse"];
var tranResponse = rstream["TranResponse"];

var paymentResponse = new PaymentInfoResponse();
paymentResponse.AcqRefData = "";
paymentResponse.Amount = "1.11";
paymentResponse.CardholderName = "test test";
paymentResponse.CardType = tranResponse["CardType"];
paymentResponse.DisplayMessage = cmdResponse["TextResponse"];
paymentResponse.ExpDate = tranResponse["ExpDate"];
paymentResponse.MaskedAccount = tranResponse["AcctNo"];
paymentResponse.Token = tranResponse["RecordNo"];

 

View the C# example on GitHub

 

 

View Previous: Datacap Systems TranCloud Overview

Attachments

    Outcomes