Sage Payment Solutions

Credit Card Processing Integration

Reference Guide
10/11

 2011 Sage Payment Solutions, Inc. All rights reserved. Sage, the Sage logos, and the Sage product and service names mentioned herein are registered trademarks or trademarks of Sage Payment Solutions, Inc., or its affiliated entities. For additional assistance on this and other products and services, visit our Web site at: www.sagepayments.com.

Table of Contents
Integrating Sage Exchange Desktop vs. Sage Exchange Virtual Desktop .................................. 3
Understanding unique identifiers ................................................................................................................................. 3 Additional considerations - SEVD .................................................................................................................................. 3 Additional considerations - SED .................................................................................................................................... 4

Understanding Functionality .................................................................................................. 4 Accessing the XML Messaging Document ............................................................................... 7 Understanding Common Sage Exchange Desktop/Payment Issues.......................................... 8
Installation and usage ................................................................................................................................................... 8 Card swiping device setting requirements .................................................................................................................... 8

Sage Exchange Desktop Installation ..................................................................................... 11

Reference Guide

Integrating Sage Exchange Desktop vs. Sage Exchange Virtual Desktop

Sage Exchange Desktop (SED) is a Microsoft Windows based-application created by Sage Payment Solutions that must be installed per-user on each workstation where you want to process payments. Sage Exchange Virtual Desktop (SEVD) is a web-based application hosted by Sage Payment Solutions that you access via a web browser/Internet connection. Both applications use the same XML message formats; however, request and response delivery varies between the two applications. SEVD requires the request XML to be posted to its entry page. Since it is hosted in a web browser it is disconnected from the integrated application and can either post XML response data back over Secure Socket Layer (SSL) to a URL provided in the XML request. Alternately, the integrated application can poll SEVD for the response after sending a request via a transaction or vault status query using the user-defined unique identifier provided in the request. SED is tightly coupled with the integrated application and uses the same communications channel to send request and response data. After sending a request (via a call into the SDK), the integrated application receives the response when the SDK call returns.

Understanding unique identifiers

Both Vault and transaction XML requests have a user-defined unique identifier field, which tags the request with a user-defined data element that can be used to later query the response data: In SED, an integrated application can use the unique identifier to query a Vault or transaction response in order to recover communication disruptions. In SEVD, the unique identifier can be used to query the response when polling is implemented or in the event a response postback is not received. Although it is a user-defined field, it is important to make this value unique to be successful in later identifying the response data.

Additional considerations - SEVD

Review this list of additional considerations if you integrate your application with SEVD: Use one of the following methods to integrate with SEVD: o Postback - Available with no UI, this function allows the calling application to request the transaction results be posted to a specific URL. This method requires a web site to expose a URL that can handle/process the postback data. The data is sent over SSL and requires the receiving web site to have a valid SSL certificate and be reached on the Internet from the Sage Payment Services postback server. A transaction can take up to 15 minutes to complete based on user interactions in the SEVD; therefore, postback response handling should allot for this interaction time. or o Redirect - Available only without a UI, allows the calling application to request the merchant be redirected to a specified URL after completion of a SEVD transaction. We cannot redirect if a merchant closes SEVD without completing the transaction.

Reference Guide

SEVD uses SSL to capture data securely. To prevent cross-domain issues and SSL security warnings it is important not to host it in a framed environment. Doing so could require a PA-DSS or PCI audit. A transaction can take up to 15 minutes to complete based on user interactions in the SEVD. Polling for a response should allot for this interaction time.

Additional considerations - SED

Use the Vault when a transaction has a recurring component to avoid repeated requests for card holder data. It is not to be used to minimize user interaction with SED. Doing so could result in improper transaction processing or the inability to use other functionality later.

Understanding Functionality
This section describes the functionality available in Sage Exchange Desktop (SED) and Sage Exchange Virtual Desktop (SEVD) to help you choose which functions to code for your application.

Vault-only account
An account that consists of a Merchant ID/Merchant Key combination that the integrated application can use to access the Sage Payment Solutions gateway to store/update/access credit cards. Vault-only accounts cannot process credit cards. Note: Global Unique Identifier (GUID) functionality allows you to create (with UI), view/update (with UI), and delete (without UI) credit card numbers. You can process of GUIDs using a Vault-only or active processing account.

Get Payment (or Sale)

The process of securing a portion of the cardholders credit pending settlement (which can occur automatically or be manually initiated by the merchant). This may be done with a UI or without (if you have a GUID). This is different from an Authorization Only in that the Get Payment/Sale amount will actually settle (if set up to do so automatically), whereas an Authorization requires a capture to subsequently capture.

Get Multiple Payment

This function allows you to process multiple UI and non-UI payments in a single XML request. The Multi-Payment window automatically opens for any request that includes UI type payments. This window consists of a grid that you must use to indicate the number of payments in the request and each payment type. You can use this function to prepare your application to process multiple payments.

Recurring Payment
Available only without a UI - Allows users to set up a recurring payment for a merchant without a UI. Note: Sage Exchange Desktop is a called application that does not originate requests; therefore, if a recurring payment is set up, the integrated application must query to confirm the payment was processed. If the recurring payment function is handled by the integrated application, a Get Payment transaction would be processed on the date the payment needs to be made. The recurrence of the payment would be handled by the integrated application.

Reference Guide

Void
This functions is available only without a UI and is used when a merchant wants to cancel a Get Payment transaction before settlement. Processing a Void removes the credit hold for the amount of the authorization on the cardholders card (freeing up their credit line) and the transaction from the merchants batch so that it does not settle.

Level II or Level III with Get Payment

Provides the ability to add additional transaction data required for processing Level II or Level III commercial card transactions.

Credit (or Refund)

Available with and without a UI, a credit can only be processed if the original transaction has already settled. Credits (without reference) are processed when the original transaction was not run via the Gateway/processor.

Credit by Reference
Available with and without a UI, a credit by reference can only be processed if the original transaction has already settled and was originally processed via the Gateway/processor.

Authorization Only
Available with or without a UI, this function is used where the merchant is only looking to secure the credit hold but is not in the position to ship goods/render services. Authorizations typically expire after seven days (depending on the industry). Once the authorization has expired, the ability to capture it expires as well and a new authorization must be run.

Capture
Available with or without a UI, this function is used with an unexpired authorization to solidify the sale so that it can settle (either automatically or manually depending on the merchant setup).

Force
Available with and without a UI, this function allows merchants to get an authorization number via phone/offline and Force the transaction using the authorization information. This is useful in situations where online processing is not possible due to Internet/connectivity issues. It is possible for a merchant to make up an authorization number and process a Force; however, if the authorization is not valid the merchant will receive a chargeback.

Batch Inquiry
Available without a UI only, used to obtain the transaction net and transaction count of the current open batch that is awaiting settlement.

Batch Close
Available without a UI only, used to settle transactions in the current open batch that is awaiting settlement. Sales, Captures, Forces and Credits all qualify for settlement. Batch close is available with or without transaction net and transaction count verification.
Reference Guide 5

Account Query
Available with no UI only, used to get the status and services available for a particular merchant account. This can then be used to determine which features in Sage Exchange Desktop can be used with a merchant account.

Vault Status Query

Available with no UI only, used to get the status of a Vault operation processed through the Sage Exchange Desktop by using the user defined Vault ID provided during a previous Vault operation. In the event of a communication failure in which the response was not received this can be used to determine if the platform received and processed the operation or if the operation needs to be run again.

Transaction Status Query

Available with no UI only, used to get the status of a transaction processed through the Sage Exchange Desktop by using the user defined transaction ID provided during a previous payment. In the event of a communication failure (in which the response was not received) this can be used to determine if the platform received and processed the transaction or if the transaction needs to be run again. This can be used to prevent duplicated transactions. If post transaction logic is required this can also provide additional information such as the current state of the transaction (settled, expired, or voided).

User Interface
Available with and without a UI, the Sage Exchange Desktop user interface can be configured to hide/disable fields and also bypass the post authorization analysis (like the AVS and CVV failure Void prompt).

Application ID
Required by all integrated applications, the Application ID must never be shared with third parties or applications. The Application ID identifies the calling application, version, and its certification as a valid integrated solution. The value is obtained from Sage Payment Solutions through a registration/certification process.

Language ID
Specifies the language to be used when displaying a graphical user interface (GUI), the default is en-US for US English. The values are derived from the lower case 2 letter language code from ISO 699-1 and the two letter upper case from ISO 3166. For example, fr-CA is French Canadian.

Card Swipe
Clear Text wedge readers and the Magtek encrypted reader are available for merchants to purchase as plug-andplay devices. The i3070 debit/credit/EMV terminal with USB cable is available only in Canada. You can use this type of reader only if you are integrating using Sage Exchange Desktop. You can use a generic keyboard input device or a wedge reader if you are integrating using Sage Exchange Virtual Desktop. Note: All Application IDs default to the Clear Text reader; however, the merchant can change this setting.

Reference Guide

CVV Prompt
Available only with a UI, allows the calling application to request a Card Verification Value (CVV) prompt to capture the CVV when the transaction is being processed silently by the calling application. Note: CVVs cannot be saved under any circumstances.

Expiration Date Prompt

Available only with a UI, allows the calling application to present a GUID UI with the ability only to change the expiration date and masking the card information (except the last 4 digits).

Accessing the XML Messaging Document

XML messaging for all of the functions above (with the exception of card swipewhich does not require integrator coding) is detailed in the XML Messaging specification document included in the All Integrators subfolder within the Sage Payment Solutions Integration Documents folder you received after completing the registration process. This document is periodically updated; therefore, it is recommended you make sure that you have the most recent version of the document before working on your integration. Contact Technical Support at sdksupport@sagepayments.com to ensure that you have the latest version of this document.

Reference Guide

Understanding Common Sage Exchange Desktop/Payment Issues

This section details some common issues encountered by the Sage Payment Solutions Support team.

Installation and usage

Anti-Virus applications that are known to have issues with the Sage Exchange Desktop installation are: o o o Trend-Micro Norton Internet Suite and Norton Personal McAfee Note: Issues with anti-virus and firewall settings can prevent Sage Exchange Desktop from installing. Try to install Sage Exchange Desktop using the zip file install located at: https://www.sageexchange.com/install/setup.zip. The web URLS to be added to the safe zone in Anti-virus software and Firewall settings are: o o sagepayments.net sageexchange.com

We advise adding the following files to the safe zone in the anti-virus software: o o Sageexchange.exe SpsModuleSdkCl.dll

SDK Component of Sage Exchange Desktop needed for Automatic Updates for Next Available Version - We have seen issues where merchants are required to manually check for updates in Sage Exchange Desktop in order to receive any necessary advancements or corrections. Our recommendation is to have both components of Sage Exchange Desktop (the Desktop application and a COM component (SDK)) installed together along with the install of the Sage application for an all-in- one installation package.

Card swiping device setting requirements

When a card reader or physical terminal are used with an integration, the merchant must be educated on the setting requirements in Sage Exchange Desktop: o The card readers (Cleartext or Sage Payment Services Encrypted Magtek Magensa) require the merchant to access the settings and make a selection for either Cleartext or Magensa. The i3070 is supported only for Canadian merchants. If using this device, right-click the SE icon in the Window System Tray and select Settings to open the Sage Exchange Settings dialog box, where you must select the device under the Hardware node. Additionally, you must install the i3070 drivers found at: https://www.sageexchange.com/install. You can use this type of reader only if you are integrating using Sage Exchange Desktop. You can use a generic keyboard input device or a wedge reader if you are integrating using Sage Exchange Virtual Desktop.

Reference Guide

Legacy hardware usage: o Although many of the card readers in use by the Sage integrated merchants may work with the Sage Exchange Desktop, the data collected via the track swipe may cause processing issues due to incompatibility. The Cleartext device setting was intended for legacy hardware. We recommend offering the merchant the Magensa SPS Encrypted card reader to avoid issues with swiped transactions. This device has a special encryption specifically for Sage Payment Services, which requires ordering through us directly.

CVV and Track Data requirements: o If both the CVV and Track Data are being passed to the gateway, they must be sent it separate fields of data. Submitting track data alone will not include the CVV during the request. In order for the transaction to process as a Retail transaction, not only does the track data need to be processed, but the request must be sent to the appropriate operation on the gateway. We offer specific posting methods for Retail Swiped, Retail Keyed, Retail Debit, MOTO, and eCommerce. If a swiped transaction is sent to the MOTO operation, the transaction will be processed as key entered instead of swiped although track data was present.

Matching data fields - There have been mistakes in the past where an integration may not been setup correctly with routing data to the corresponding field for the transaction request. Please ensure that all data values are setup to route to the correct gateway field so all data will be properly displayed on the transaction record. Debit transactions cannot be voided - Since a debit transaction is a real-time deduction from a customers bank account, the transaction cannot be voided after authorization. The merchant must settle the sale and issue a credit.

Common integration coding errors

Decline/Error codes - There are two different types of decline codes generated by either the gateway or processor (front-end): o Processor Declines - These codes vary in length depending on the front-end used on the merchant account. TSYS (Vital) - 6 digit codes generally starting with a series of 4 zeros Paymentech - 3 digit codes First Data - 2 digit codes Gateway Declines - All codes are 6 digits in length and begin with a 9, 7, 6 or 0

o o o o

We recommend developers set up actions for each code so the merchant is informed of what occurred and the next course of action required to attempt authorization. These codes are rarely changed, but please refer to the Online Support Center or Development Connection website for the most up to date documentation. http://www.sagepayments.net/developer/ or https://support.sagepayments.com/ics/support/default.asp?deptID=20000.
Reference Guide 9

Level I, II, and III transaction options

Currently Sage Exchange Desktop only supports Level I and II transaction data. Level III transactions are only supported via our VT3 interface or if the calling application elects to send the Level III in the XML request. o Level I - This consists of normal transaction data such as credit card number, expiration date, amount of charge, and billing information. Level II - Including all requirements from Level I, the request must also contain the customer number (purchase card number), order ID, and tax amount. Note: The Gateway will generate an order ID if one is not provided during authorization. o Level III - This type may also require a higher transaction amount and is only supported for Visa and MasterCard. In addition to all requirements from Level I and II, it must include line item detail which consists of product/service information and the merchant tax ID and/or customer tax exempt status.

The data submitted on each transaction can affect the qualifying transaction rate for the merchant. Most merchants process both regular consumer and purchase credit cards and it is in their best interest to provide all required information to receive the lowest possible fees.

Authorization types
Both Sale and Authorization Only transactions will allow a merchant to authorize funds on a credit card; however, there are differences between these transactions: Sale - This is considered a captured authorization which is ready for settlement immediately. The transaction will expire after 7 calendar days from the gateway open batch if not settled. If the merchant is setup for automatic settlement, any Sale transactions in the open batch will be processed for payment. The merchant does not have the option of adjusting the transaction prior to settlement. Authorization Only - This type will obtain an authorization on the card, but in order for the transaction to be settled, it must be converted to a PriorAuth with an offline PostAuth or Force request. The transaction will expire after 7 calendar days from the gateway open batch if not settled. If the merchant is setup for automatic settlement, the Auth Only must be converted to a PriorAuth for the settlement to process the transaction. This transaction type allows for one adjustment prior to settlement, which occurs during the transaction conversion.

These types are also similar in some areas because they will both authorize an amount on the card immediately and the authorization code is valid for 30 calendar days. If the original transaction expired after the first 7 days, it can be processed as an offline Force request with the original authorization code.

Processing best practices

Review these best practices for card authorization/validation: It is recommended to obtain a new authorization code after the original authorization expires from nonsettlement over the first 7 calendar days to avoid higher transaction rates; however, a merchant will not only be charged for the first and second authorization fee, they will also be charged a misuse of authorization fee for either an expired or voided transaction.

Reference Guide

10

When using the Vault to store credit card data, it is recommended to first process a $0.01 authorization to verify if the card is valid and to confirm if the billing information on file matches the customers bank. This is an excellent method for avoiding the storage of invalid card information and may prevent unnecessary declines. After you validate the card, then you would submit a request to store the card information in the Vault for future processing and then void the $0.01 from the batch.

Snapshot of Interchange qualification requirements

Each Interchange category has different requirements in order to hit that category. Visa and MasterCard also handle it differently. Below are a couple of category examples of amount requirements and adjustment tolerance. CPS Retail/CPS Retail Debit: o For consumer cards the auth and settlement amount dont have to match, and they dont have a tolerance % for adjusting the transaction amount. For Debit cards the auth and settlement amount have to match or they will go to EIRF.

MC equivalent category Merit III/Merit III Debit: o o o Both credit and debit are treated the same 10% transaction tolerance (25% for barbers /beauty salons) Restaurants, fast food, bars, limousines and taxis, and airline transactions are exempt from the tolerance.

Settlement Timelines: o CPS Retail has a 2 day settlement window, otherwise it will downgrade to EIRF, EIRF has a 3 day settlement window, otherwise it will go to Standard. Most VISA categories have a 2 day settlement window, except for the Passenger transport which have an 8 day window. Note: This is from Sale to settlement though, not from Auth to settlement. There are 7 days to settle an Auth Only transaction, but as soon as the Auth Only is switched to a PriorAuth, there are only 2 days left to settle. Although the settlement must still be within the 7 days of authorization. So if the Auth Only is switched to a PriorAuth on the 6th day, there is only one day left to settle that transaction.

Sage Exchange Desktop Installation

Sage Exchange Desktop is comprised of two components; the Desktop application and the SDK API. The SDK API requires administrative rights to be installed and is only installed once per computer. The Desktop component is installed per-user. You can install the SDK API by either letting the Desktop install handle this as a prerequisite (this will require an administrator to run the desktop install) or by using the separate SDK API install MSI. Installing the SDK API MSI by itself allows you to remove the administrator requirement to perform the Desktop install. This is ideal in situations in which several users of a single computer are going to use the Sage Exchange Desktop. An administrator will install the SDK API one time on the computer and then each user is free to install the Desktop application if needed. See Installation Guide in the document included in the Sage Exchange Desktop Integrator subfolder within the Sage Payment Solutions Integration Documents folder you received after completing the registration process.
Reference Guide 11