Transport

Introduction

MerchantWare Transport 4 offers merchants the ability to accept credit cards without dealing with the complexities of becoming PCI compliant.

Transport 4 consists of the Transport Service, two payment pages, Transport.Web and Transport.Mobile, and uses MerchantWare to process credit card transactions. The TransportService receives transaction data, and generates a TransportKey to link to the data. Using the TransportKey, a developer can instruct the payment pages to retrieve the transaction data and provide a PCI-compliant interface for accepting credit card data over the Internet. Below is a sequence diagram illustrating how the system works.

Transport Sequence Diagram

Production Endpoints

Pages Address
Transport.Web https://transport.merchantware.net/v4/transportweb.aspx
Transport.Mobile https://transport.merchantware.net/v4/transportmobile.aspx
Service Endpoint Address
Transport Service https://transport.merchantware.net/v4/transportService.asmx

Testing Endpoints

Pages Address
Demonstration Page https://transport.merchantware.net/v4/test/testweb.aspx
Transport.Web https://transport.merchantware.net/v4/transportweb.aspx
Transport.Mobile https://transport.merchantware.net/v4/transportmobile.aspx
Service Endpoint Address
Transport Service https://transport.merchantware.net/v4/transportService.asmx
 

Transport.Web

The Transport.Web page is used to collect credit card information. It has been customized for data entry using a web browser on a workstation or laptop.

Page URL: https://transport.merchantware.net/v4/transportweb.aspx


Using the Webpage

The Transport.Web page retrieves transaction data using the transportKey generated by the Transport Service's CreateTransaction response. The token can be passed to the page using one of two methods.

Query String
The token may be passed to the Transport.Web page using the query string parameter transportKey. The following example shows a test server URL:

https://staging.merchantware.net/transportweb4/TransportWeb.aspx?transportKey=ac2c4b26-4733-4b6b-9fce-2c7ebc3315ac

Form Post
The token may be passed to the Transport.Web page using the form variable transportKey. The following example shows a simple form posting the transportKey variable to the test server URL:

<form id="Form1" method="post" action="https://staging.merchantware.net/transportweb4/TransportWeb.aspx">
  <input type="text" name="transportKey" id="transportKey" value="ac2c4b26-4733-4b6b-9fce-2c7ebc3315ac" />
  <input type="submit" value="Submit" />
</form>
						
 
 
 

Page Elements

The Transport.Web page contains two views: the Keyed view and the Swipe view.

Keyed View


  1. Logo: The area where the logo is displayed. The Merchantware logo is displayed if no logo image URL is provided in the transaction request. The logo border color can be changd using the LogoBorderColor DisplayColor setting.

  2. Data Entry: This section of the screen collects all of the information necessary to complete a transaction. Each text box has an information icon that contains a tooltip when the mouse is positioned on top of it.

  3. View Toggle: Allows the user to switch between keyed and swiped views. If the transaction was submitted with the EntryMode field set to KEYED, this option is not available.

  4. Transaction Details: Displays data from the transaction request. This section can be turned off by setting the HideDetails option to true in DisplayOptions.

  5. Tool Tip: Contains helpful information regarding the input that each textbox requires. These can be hidden by setting the HideTooltips option to true in DisplayOptions.

 

Swiped View


  1. Logo: The area where the logo is displayed. The Merchantware logo is displayed if no logo image URL is provided in the transaction request. The logo border color can be changd using the LogoBorderColor DisplayColor setting.

  2. Swipe Dialog: This section takes the place of the keyed information.

  3. View Toggle: Allows the user to switch between keyed and swiped views. If the transaction was submitted with the EntryMode field set to KEYED, this option is not available.

  4. Transaction Details: Displays data from the transaction request. This section can be turned off by setting the HideDetails option to true in DisplayOptions.

Transport.Mobile

The Transport.Mobile page is used to collect credit card information. It has been customized for data entry using a mobile or handheld device.

Page URL: https://transport.merchantware.net/v4/transportmobile.aspx


Using the Webpage

The Transport.Mobile page retrieves transaction data using the transportKey generated by the Transport Service's CreateTransaction response. The token can be passed to the page using one of two methods.

Query String
The token may be passed to the Transport.Mobile page using the query string parameter transportKey. The following example shows a test server URL:

https://staging.merchantware.net/transportweb4/TransportMobile.aspx?transportKey=ac2c4b26-4733-4b6b-9fce-2c7ebc3315ac

Form Post
The token may be passed to the Transport.Mobile page using the form variable transportKey. The following example shows a simple form posting the transportKey variable to the test server URL:

<form id="Form1" method="post" action="https://staging.merchantware.net/transportweb4/TransportMobile.aspx">
  <input type="text" name="transportKey" id="transportKey" value="ac2c4b26-4733-4b6b-9fce-2c7ebc3315ac" />
  <input type="submit" value="Submit" />
</form>
						

Page Elements

  1. Logo: The area where the logo is displayed. The Merchantware logo is displayed if no logo image URL is provided in the transaction request. The logo border color can be changed using the LogoBorderColor DisplayColor setting.

  2. Data Entry: This section of the screen collects all of the information necessary to complete a transaction. Each text box has an information icon that contains a tooltip when the mouse is positioned on top of it.

Response Parameters

The response parameters are a set of key-value pairs that are returned within the query string by the Transport web pages after a transaction is processed. If a Redirect Location was provided in the initial request, these values are appended to the end of the URL before the redirection is executed.

 

Fields

Name Description
Status The status of the transaction. To see valid statuses, click here.
RefID The unique id of the transaction. Use this to process a void, refund, or any other action that requires a token.
Token The unique id of the transaction. Use this to process a void, refund, or any other action that requires a token.
AuthCode The authorization code returned from the bank for the approved transaction.
CardType The type of card that was processed.
CardNumber The truncated number showing the last 4 digits of the card.
ExpDate The expiration date of the card that was processed. 
Note: Does not get returned when using IDTech encrypted card reader for swiped transactions.
AVS The AVS response code. To see valid AVS response codes, click here.
CVV The CVV2/CVC2/CID response code. To see valid CVV response codes, click here.
EntryMode The method used to collect the card information. To see valid entry modes, click here.
TransactionID The transaction id provided in the request.
ValidationKey The background color for text boxes where users enter information that do not have focus.
Cardholder The cardholder name, if provided in the request.
Address The street address submitted by the user for processing.
ZipCode The zip code submitted by the user for processing.
AmountApproved If partial authorization is enabled this will be the amount approved.
FsaCard Was an FSA card tendered? Will only be present in the response if FSA Healthcare amounts were specified in the create transaciton call.
 

Statuses

Name Description
APPROVED The transaction was approved.
DECLINED The transaction was declined.
DECLINED,DUPLICATE The transation was flagged as a duplicate. Set 'ForceDuplicate' flag to 'True' to process if valid.
FAILED The transaction was not processed. See attached message that follows for details. Example: 'Invalid login'.
REFERRAL The transaction was declined.
ERROR The transaction was not processed. Check 'ErrorFields' field in the URL for error message.
USER_CANCELLED The user cancelled the transaction.
 

AVS Response Codes

Code Description
X Exact: Address and nine-digit Zip match.
Y Yes: Address and five-digit Zip match.
A Address: Address matches, Zip does not.
Z 5-digit Zip: 5-digit Zip matches, address doesn’t.
W Whole Zip: 9-digit Zip matches, address doesn’t.
N No: Neither address nor Zip matches.
U Unavailable: Address information not available.
G Unavailable: Address information not available for international transaction.
R Retry: System unavailable or time-out.
E Error: Transaction unintelligible for AVS or edit error found in the message that prevents AVS from being performed.
S Not Supported: Issuer doesn’t support AVS service.
B Street Match: Street addresses match for international transaction, but postal code doesn’t. (Visa only)
C Street Address: Street addresses and postal code not verified for international transaction. (Visa only)
D Match: Street addresses and postal codes match for international transaction. (Visa only)
I Not Verified: Address Information not verified for International transaction. (Visa only)
M Match: Street addresses and postal codes match for international transaction. (Visa only)
P Postal Match: Postal codes match for international transaction, but street address doesn’t. (Visa only)
O No response sent.
5 Invalid AVS response.
 

CVV Response Codes

Code Description
M CVV2/CVC2/CID Match
Y CVV2/CVC2/CID Match
N CVV2/CVC2/CID No Match
P Not Processed
S Issuer indicates that the CV data should be present on the card, but the merchant has indicated that the CV data is not present on the card.
U Unknown / Issuer has not certified for CV or issuer has not provided Visa/MasterCard with the CV encryption keys.
X Server Provider did not respond.
 

Entry Modes

Code Description
0 UNKNOWN - This value is reserved.
1 KEYED - A transaction keyed in using data read by a person off of a card.
2 SWIPED - A transaction activated from data swiped through a magnetic reader.
3 AUTHORIZATION - A transaction keyed in with a phone or offline authorization from a processor.
4 PROXIMITY - A transaction activated from a contactless reader.

Transport Web Services

The Transport web service allows merchants to send non-credit card transaction data over the internet in a secure manner.


Service Information


Methods

CreateTransaction

Stores transaction data and options for later use and returns a reference to the data in the form of a token.

SOAPAction http://transport.merchantware.net/v4/CreateTransaction
Name Type Size Description
merchantName String 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteID String 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey String 1-160 The software key or password for the site accessing a Merchantware account.
request TransportRequest -- A TransportRequest object containing the transaction data.

A TransportResponse is returned.

Sample Request Packet (raw):

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
    <CreateTransaction xmlns="http://transport.merchantware.net/v4/">
    <merchantName>Zero Inc.</merchantName>
    <merchantSiteId>00000000</merchantSiteId>
    <merchantKey>00000-00000-00000-00000-00000</merchantKey>
    <request>
        <TransactionType>SALE</TransactionType>
        <Amount>1.23</Amount>
        <ClerkId>ABC123</ClerkId>
        <OrderNumber>ABC123</OrderNumber>
        <Dba>Zero Brands</Dba>
        <SoftwareName>ABC Software</SoftwareName>
        <SoftwareVersion>1.0.0.0</SoftwareVersion>
        <AddressLine1>123 Main Street</AddressLine1>
        <Zip>02110</Zip>
        <Cardholder>Visa Test Card</Cardholder>
        <LogoLocation>https://server.com/image.jpg</LogoLocation>
        <RedirectLocation>https://server.com/redirectPage.aspx</RedirectLocation>
        <TransactionId>ABC123</TransactionId>
        <ForceDuplicate>false</ForceDuplicate>
        <CustomerCode>ABC123</CustomerCode>
        <PoNumber>ABC123</PoNumber>
        <TaxAmount>.05</TaxAmount>
        <DisplayColors>
            <ScreenBackgroundColor>000000</ScreenBackgroundColor>
            <ContainerBackgroundColor>000000</ContainerBackgroundColor>
            <ContainerFontColor>000000</ContainerFontColor>
            <ContainerHelpFontColor>000000</ContainerHelpFontColor>
            <ContainerBorderColor>000000</ContainerBorderColor>
            <LogoBackgroundColor>000000</LogoBackgroundColor>
            <LogoBorderColor>000000</LogoBorderColor>
            <TooltipBackgroundColor>000000</TooltipBackgroundColor>
            <TooltipBorderColor>000000</TooltipBorderColor>
            <TooltipFontColor>000000</TooltipFontColor>
            <TextboxBackgroundColor>000000</TextboxBackgroundColor>
            <TextboxBorderColor>000000</TextboxBorderColor>
            <TextboxFocusBackgroundColor>000000</TextboxFocusBackgroundColor>
            <TextboxFocusBorderColor>000000</TextboxFocusBorderColor>
            <TextboxFontColor>000000</TextboxFontColor>
        </DisplayColors>
        <DisplayOptions>
            <AlignLeft>false</AlignLeft>
            <NoCardNumberMask>false</NoCardNumberMask>
            <HideDetails>false</HideDetails>
            <HideMessage>false</HideMessage>
            <HideTooltips>false</HideTooltips>
            <UseNativeButtons>false</UseNativeButtons>
        </DisplayOptions>
        <EntryMode>Undefined or Keyed or Swiped or KeyedSwiped</EntryMode>
        <TerminalId>00000000</TerminalId>
        <EnablePartialAuthorization>false</EnablePartialAuthorization>
    </request>
</CreateTransaction>
</soap:Body>
</soap:Envelope>

Sample Return Packet (raw):

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
    <CreateTransactionResponse xmlns="http://transport.merchantware.net/v4/">
    <CreateTransactionResult>
        <TransportKey>21EC2020-3AEA-1069-A2DD-08002B30309D</TransportKey>
        <ValidationKey>38A52BE4-9352-453E-AF97-5C3B448652F0</ValidationKey>
        <Messages>
            <Message>
                <Field/>
                <Information/>
            </Message>
            <Message>
                <Field/>
                <Information/>
            </Message>
        </Messages>
    </CreateTransactionResult>
</CreateTransactionResponse>
</soap:Body>
</soap:Envelope>

Data Structures

1 DisplayColors Provides customization of certain display elements on the Transport.Web and Transport.Mobile pages.
2 DisplayOptions Provides additional customization features for the Transport.Web page. These values are ignored by the Transport.Mobile page.
3 MessageList Contains an array of Message objects. Each Message object represents an unit of information, usually related to a particular field in the TransportRequest structure.
4 TransportRequest Encapsulates the results of a retail batch operation in the Merchantware system.
5 TransportResponse Encapsulates the results of a CreateTransaction request.

1 DisplayColors

The DisplayColors structure provides customization of certain display elements on the Transport.Web and Transport.Mobile pages. All of the fields in the DisplayColors structure must be a valid hexadecimal HTML color code in RRGGBB format.

Fields

Name Type Size Description
screenBackgroundColor string 6 The background color of the screen.
containerBackgroundColor string 6 The background color of all standard display boxes.
containerFontColor string 6 The color of the text within all standard display boxes.
containerHelpFontColor string 6 The color of help and tooltip text within all standard display boxes.
containerBorderColor string 6 The border color for all standard display boxes.
logoBackgroundColor string 6 The background color for the box that contains a merchant-supplied logo.
logoBorderColor string 6 The border color for the box that contains a merchant-supplied logo.
tooltipBackgroundColor string 6 The background color for hovering tooltips.
tooltipBorderColor string 6 The border color for hovering tooltips.
tooltipFontColor string 6 The font color for hovering tooltips.
textboxBackgroundColor string 6 The background color for text boxes where users enter information that do not have focus.
string string 6 The border color for text boxes where users enter information that do not have focus.
textboxFocusBackgroundColor string 6 The background color for text boxes where users enter information that have focus.
textboxFocusBorderColor string 6 The background color for text boxes where users enter information that have focus.
textboxFontColor string 6 The color of the text within a textbox.

2 DisplayOptions

The DisplayOptions structure provides additional customization features for the Transport.Web page. These values are ignored by the Transport.Mobile page.

Fields

Name Type Description
alignLeft boolean Aligns all of the content left instead of the default alignment of centered.
noCardNumberMask boolean Allows credit card numbers to display in plain text rather than masked and hidden when being entered manually.
hideDetails boolean Hides the transaction detail information from being displayed.
hideDowngradeMessage boolean Hides the downgrade message.
hideMessage boolean Hides all instructional messages to the user.
hideTooltips boolean Hides informational tooltips from the user.
useNativeButtons boolean Uses buttons on the web pages that are native to the user’s operating system instead of the default styled images.

3 MessageList

The MessageList structure contains an array of Message objects. Each Message object represents an unit of information, usually related to a particular field in the TransportRequest structure.

Fields

Name Type Description
field string The field to which the error message pertains.
information string The text of the message.

Notes

  •  If no messages are generated by the Transport Service, an empty MessageList is returned in the TransportResponse.
  •  The Field property may not be populated depending on the nature of the error.

4 TransportRequest

The TransportRequest structure encapsulates a request to create a retail transaction in the Merchantware system.

Fields

Name Type Size Description
transactionType string 4-10 The transaction type for this transaction. Valid values are SALE, LEVEL2SALE, FORCESALE, and PREAUTH.
Forced sales are not supported with Transport.Mobile.
amount decimal 0-99,999.99 The desired amount for the transaction.
clerkID string 1-50 A unique ID for the user running the transaction. POS can send the server ID, clerk ID, employee ID, register ID or any other ID that identifies the user or system running the transaction.
orderNumber string 1-8 The order or invoice number associated with the transaction.
dba string 1-50 The business name for the merchant as it should appear to the customer.
softwareName string 1-50 The name of the software application sending the request.
softwareVersion string 1-25 The version number of the software application sending the request.
addressLine1 string 1-25 The street address associated with the payment card for use in address verification system (AVS) checks. To maintain backward compatibility, this field will accept and truncate data longer than 25 characters.
zip string 5, 9 or 10 The ZIP Code associated with the payment card for use in address verification system (AVS) checks.
cardholder string 1-100 The cardholder name as it appears on the payment card.
logoLocation string 1-512 An SSL-secured URL pointing to an image file representing the merchant's logo. The logo may be up to 430 pixels wide.
redirectLocation string 11-1024 An SSL-secured URL to which users will be redirected upon error or successful processing of a transaction. See Notes section for more information.
transactionId string 1-25 The merchant-defined identifier for the transaction.
forceDuplicate boolean -- Override duplicate protection and allow the transaction to process normally.
customerCode string 1-50 Required for LEVEL2SALE transactions. The merchant-defined identifier for the customer involved in the transaction.
poNumber string size Required for LEVEL2SALE transactions. The customer-defined identifier declaring a purchase order for the transaction.
taxAmount decimal 0-20,000 Required for LEVEL2SALE transactions. The declared tax amount of the transaction.
displayColors DisplayColors -- Provides customization of certain display elements on the Transport.Web and Transport.Mobile pages.
displayOptions DisplayOptions -- Provides additional customization features for the Transport.Web page. These values are ignored by the Transport.Mobile page.
entryMode EntryMode --  
AuthorizationCode string 6 Authorization code for Forced Sales.
TerminalId string 0-16 Terminal ID to uniquely identify the terminal to the processor. The terminal ID must contain all numeric characters. For more information about the TID value that should be used for merchants, please contact our Integrations Team at integrations@cayan.com
EnablePartialAuthorization boolean -- Enable partial authorization functionality in TransportWEB. Must be set to true to enable partial authorizations. If false or left unspecified TransportWEB will decline if unable to capture the full requested amount. 

5 TransportResponse

The TransportResponse structure encapsulates the results of a CreateTransaction request.

Fields

Name Type Description
transportKey string (GUID) A GUID used by the Transport.Web and Transport.Mobile pages to reference and load the transaction request.
validationKey string (GUID) A GUID that can be used to match up a redirected response with its
messages MessageList Contains any error messages generated by the request.

Notes

  •  The TransportKey and ValidationKey fields will be empty if any messages are generated by the request.

Enumerations

1 EntryMode

The EntryMode enumeration describes the method by which a merchant is expected to provide his/her credit card information. This enumeration is used to set the default view of the Transport.Web web page.

Enumeration Values

Name Description
Undefined The merchant has not defined an entry mode. In this case, KeyedSwiped is used by default.
Keyed The merchant must use a keyboard to enter card data. No option to swipe a card is provided.
Swiped The merchant may use a card reader to collect card data.
KeyedSwiped The merchant may use a keyboard to enter card data. The merchant is provided the ability to swipe a card as an alternative.