====== XCharge Component v2.12.0 ====== ===== Download ===== [[http://www.usaepay.com/topics/xCharge2120.zip|Download xCharge2120.zip (2.28MB)]] ===== Component Overview ===== The USA ePay XCharge installation package includes both an Active-X (.dll) COM component and Active-X COM (.ocx) control version of the XCharge transaction component. Both have identical properties and methods. **IMPORTANT NOTE: For ASP & ASP.NET projects you __MUST__ use the .dll component version, using the control version may lead to IIS server instability.** There are ASP, ASP.NET, Access, VB, VB.NET, C#, and C++ examples for the .dll component version. There are Access, VB, VB.NET, C#, and C++ examples for the .ocx control version. Some may find the control version easier to use for desktop applications. The choice is yours. The USA ePay XCharge component provides an easy to use Active-X COM interface for running server to server processing. If you are developing your site using ASP or using Visual Basic applications to process your transactions then it is highly recommended that you use this component rather than the client side method. Not only will it provide a more consistent interface to your customers, but it will also prevent manipulation of order data. When using an ASP script, the basic flow will go something like: - Customer enters credit card data on merchant's server - Script on merchants server takes customer data and populates the required properties of USAePay XCharge Component - Merchant's server tells USAePay transaction to process (Process method) - XCharge component sends transaction via SSL encrypted HTTP connection to USAePay for authorization - XCharge component reads response from USAePay - XCharge component populates response properties - Merchant's script interprets the results and displays the corresponding response to the customer ==== System Requirements ==== You will need a Windows NT, 2000, XP, 2003 or 2008 system to use this component. The installation program should install any needed dependencies. On Windows 2008, you have to place the files in an alternate folder and register them from that folder using the command line. Placing the DLLs in the %System%/System32 folder won’t work. To compile the VB samples you must have Microsoft Visual Basic 6.0. To compile the C++ samples you must have Microsoft Visual C++ 6.0 or higher. The C# samples require Microsoft Visual C# 2003 or Microsoft Visual Studio .NET 2003. The VB.NET samples require Microsoft Visual VB.NET 2003 or Microsoft Visual Studio .NET 2003. The ASP.NET Visual Studio .NET 2003 samples require Microsoft Visual Studio .NET 2003 and IIS 4.0 or higher. The ASP.NET [[http://www.asp.net/webmatrix/default.aspx?tabIndex=4&tabId=46|Web Matrix]] samples require [[http://www.asp.net/webmatrix/default.aspx?tabIndex=4&tabId=46|Web Matrix]] and [[http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&displaylang=en|version 1.1 of the Microsoft .NET Framework]] installed. The ASP.NET aspx samples require IIS 4.0 or higher and [[http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&displaylang=en|version 1.1 of the Microsoft .NET Framework]] installed. The Access samples require Microsoft Access 2000 or higher. ==== Merchant Email Receipts ==== (primarily used in conjunction with client-side with simple redirection) To enable merchant receipts for the component you must edit the source you are using. This is done by logging into www.usaepay.com. Click on "Settings". Edit your source by clicking on the pencil next to its name. Enter your email address into the Merchant Receipt box. You may enter several email addresses separated by commas. ===== ASP Examples ===== ==== 1) Sale ==== The most common transaction is a Sale. The customer's card will be authorized for the amount specified and placed in the batch for settlement. Once the batch is settled, the funds will be transferred to the merchant's account. //Please note: unless the merchant has configured their batch to auto close, they will need to log into usaepay.com to close their batch.// <% Set XCharge1 = Server.CreateObject("USAePayXChargeCom2.XChargeCom2") XCharge1.Command = sale XCharge1.Sourcekey = "Ju0e3By6Vb5z9B2oAJUD2v40ADf4qhc5" 'This allows fraud blocking on the customers IP address XCharge1.IP = Request.ServerVariables("REMOTE_ADDR") XCharge1.Testmode = True 'Change this to False for the transaction 'to process XCharge1.Card = "4005562233445564" 'Card number, no dashes, no spaces XCharge1.Exp = "0408" 'Expiration date 4 digits XCharge1.Amount = "1.00" 'Charge amount in dollars XCharge1.Invoice = "1234" 'Invoice number. must be unique. XCharge1.TransHolderName = "Max Powers" 'Name of card holder XCharge1.Street = "456 Sunny Lane" 'Street address XCharge1.Zip = "95130" 'Zip code XCharge1.Description = "Online Order" 'Description of charge XCharge1.CVV2="435" 'CVV2 code Response.Write "

Please wait one moment while we process your card...


" Response.Flush XCharge1.Process If XCharge1.ErrorExists = True Then Dim XError Response.Write "ERRORS:
" For Each XError In XCharge1.Errors Response.Write "Error Code: " & XError.ErrorCode Response.Write " Error Text: " & XError.ErrorText & "
" Next End If Response.Write "
" Response.Write "
" Response.Write "" Dim strResponseStatus Select Case XCharge1.ResponseStatus Case Approved strResponseStatus = "Approved" Case Declined strResponseStatus = "Declined" Case Verification strResponseStatus = "Verification" Case Error strResponseStatus = "Error" End Select Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "
" Response.Write "Transaction Results:" Response.Write "
Status: " & strResponseStatus & "
Authorization Code: " & XCharge1.ResponseAuthCode & "
Reference Number: " & XCharge1.ResponseReferenceNum & "
Batch Reference #: " & XCharge1.ResponseBatch & "
AVS Result: " & XCharge1.ResponseAVS & "
AVS Result Code: " & XCharge1.ResponseAVSCode & "
CVV2 Result: " & XCharge1.ResponseCVV2 & "
CVV2 Result Code: " & XCharge1.ResponseCVV2Code & "
VPAS Result Code: " & XCharge1.ResponseVPASCode & "
Result Test: " & XCharge1.ResponseResult & "
Response Error: " & XCharge1.ResponseError & "
Response Error Code: " & XCharge1.ResponseErrorCode & "
ACS URL: " & XCharge1.ResponseACSURL & "
Payload: " & XCharge1.ResponsePayload & "
Is Duplicate: " & XCharge1.ResponseIsDuplicate & "
Converted Amount: " & XCharge1.ResponseConvertedAmount & "
Converted Amount Currency: " & XCharge1.ResponseConvertedAmountCurrency & "
Conversion Rate: " & XCharge1.ResponseConversionRate & "
Customer Number: " & XCharge1.ResponseCustNum & "
" ' Clear the component instance from memory set XCharge1 = Nothing %> ==== 2) Auth Only ==== The Auth Only transaction is extremely useful for companies that do not ship their products right away. The component will authorize the charge but instead of putting the charge into the merchant's batch, the charge is placed on the Queued Transactions screen. The merchant then has up to 30 days (depending on their bank) to "capture" the transaction. This allows a merchant to verify that the customer's card is good and that they have the funds available. The merchant then captures the charge once they have shipped the merchandise. There are two ways in which the transaction can be moved from the queued transactions screen to the current batch: 1) the merchant can log into www.usaepay.com and go to the queued transactions screen and select capture; 2) the transaction can be captured via the component. If you are planning on capturing the transaction via the component, make sure to record the value of the ResponseReferenceNum property. (See Capture Example) <% Set XCharge1 = Server.CreateObject("USAePayXChargeCom2.XChargeCom2") XCharge1.Command = authonly 'This tells the server to queue the transaction after 'authorizing it. XCharge1.Sourcekey = "Ju0e3By6Vb5z9B2oAJUD2v40ADf4qhc5" 'This allows fraud blocking on the customers IP address XCharge1.IP = Request.ServerVariables("REMOTE_ADDR") XCharge1.Testmode = True 'Change this to False for the transaction 'to process XCharge1.Card = "4005562233445564" 'Card number, no dashes, no spaces XCharge1.Exp = "0408" 'Expiration date 4 digits XCharge1.Amount = "1.00" 'Charge amount in dollars XCharge1.Invoice = "1234" 'Invoice number. must be unique. XCharge1.TransHolderName = "Max Powers" 'Name of card holder XCharge1.Street = "456 Sunny Lane" 'Street address XCharge1.Zip = "95130" 'Zip code XCharge1.Description = "Online Order" 'Description of charge XCharge1.CVV2="435" 'CVV2 code Response.Write "

Please wait one moment while we process your card...


" Response.Flush XCharge1.Process If XCharge1.ErrorExists = True Then Dim XError Response.Write "ERRORS:
" For Each XError In XCharge1.Errors Response.Write "Error Code: " & XError.ErrorCode Response.Write " Error Text: " & XError.ErrorText & "
" Next End If Response.Write "
" Response.Write "
" Response.Write "" Dim strResponseStatus Select Case XCharge1.ResponseStatus Case Approved strResponseStatus = "Approved" Case Declined strResponseStatus = "Declined" Case Verification strResponseStatus = "Verification" Case Error strResponseStatus = "Error" End Select Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "
" Response.Write "Transaction Results:" Response.Write "
Status: " & strResponseStatus & "
Authorization Code: " & XCharge1.ResponseAuthCode & "
Reference Number: " & XCharge1.ResponseReferenceNum & "
Batch Reference #: " & XCharge1.ResponseBatch & "
AVS Result: " & XCharge1.ResponseAVS & "
AVS Result Code: " & XCharge1.ResponseAVSCode & "
CVV2 Result: " & XCharge1.ResponseCVV2 & "
CVV2 Result Code: " & XCharge1.ResponseCVV2Code & "
VPAS Result Code: " & XCharge1.ResponseVPASCode & "
Result Test: " & XCharge1.ResponseResult & "
Response Error: " & XCharge1.ResponseError & "
Response Error Code: " & XCharge1.ResponseErrorCode & "
ACS URL: " & XCharge1.ResponseACSURL & "
Payload: " & XCharge1.ResponsePayload & "
Is Duplicate: " & XCharge1.ResponseIsDuplicate & "
Converted Amount: " & XCharge1.ResponseConvertedAmount & "
Converted Amount Currency: " & XCharge1.ResponseConvertedAmountCurrency & "
Conversion Rate: " & XCharge1.ResponseConversionRate & "
Customer Number: " & XCharge1.ResponseCustNum & "
" ' Clear the component instance from memory set XCharge1 = Nothing %> ==== 3) Capture ==== This command allows you to capture a previously authorized charge. A practical example of this would be a shopping cart that implements an order management system. When a customer places an order the transaction is authorized and then queued. The merchant logs into the shopping cart and moves the order to "Shipped". The shopping cart would then tell USAePay to capture that transaction. To capture the transaction via the component, you must have the value of the ResponseReferenceNum property returned during the original authorization. This value should be stored on the merchant's server. <% Set XCharge1 = Server.CreateObject("USAePayXChargeCom2.XChargeCom2") XCharge1.Command = capture XCharge1.Sourcekey = "Ju0e3By6Vb5z9B2oAJUD2v40ADf4qhc5" 'This allows fraud blocking on the customers IP address XCharge1.IP = Request.ServerVariables("REMOTE_ADDR") XCharge1.Testmode = True 'Change this to False for the transaction 'to process XCharge1.RefNum = "MyResponseRefNum" 'This is where you would put the value of 'the ResponseReferenceNum property from a 'previous transaction. Response.Write "

Please wait one moment while we capture the charge...


" Response.Flush XCharge1.Process If XCharge1.ErrorExists = True Then Dim XError Response.Write "ERRORS:
" For Each XError In XCharge1.Errors Response.Write "Error Code: " & XError.ErrorCode Response.Write " Error Text: " & XError.ErrorText & "
" Next End If Response.Write "
" Response.Write "
" Response.Write "" Dim strResponseStatus Select Case XCharge1.ResponseStatus Case Approved strResponseStatus = "Approved" Case Declined strResponseStatus = "Declined" Case Verification strResponseStatus = "Verification" Case Error strResponseStatus = "Error" End Select Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "" Response.Write "
" Response.Write "Transaction Results:" Response.Write "
Status: " & strResponseStatus & "
Authorization Code: " & XCharge1.ResponseAuthCode & "
Reference Number: " & XCharge1.ResponseReferenceNum & "
Batch Reference #: " & XCharge1.ResponseBatch & "
AVS Result: " & XCharge1.ResponseAVS & "
AVS Result Code: " & XCharge1.ResponseAVSCode & "
CVV2 Result: " & XCharge1.ResponseCVV2 & "
CVV2 Result Code: " & XCharge1.ResponseCVV2Code & "
VPAS Result Code: " & XCharge1.ResponseVPASCode & "
Result Test: " & XCharge1.ResponseResult & "
Response Error: " & XCharge1.ResponseError & "
Response Error Code: " & XCharge1.ResponseErrorCode & "
ACS URL: " & XCharge1.ResponseACSURL & "
Payload: " & XCharge1.ResponsePayload & "
Is Duplicate: " & XCharge1.ResponseIsDuplicate & "
Converted Amount: " & XCharge1.ResponseConvertedAmount & "
Converted Amount Currency: " & XCharge1.ResponseConvertedAmountCurrency & "
Conversion Rate: " & XCharge1.ResponseConversionRate & "
Customer Number: " & XCharge1.ResponseCustNum & "
" ' Clear the component instance from memory set XCharge1 = Nothing %> ===== Troubleshooting ===== If you are having trouble getting the component initialized or getting the sample code to run then here are some solutions you can try. ------ **PROBLEM**: When trying to use the component in a ASP page or when running the sample ASP scripts included with the component I get an "ActiveX component can't create object" or "Invalid ProgID" error. **RESOLUTION**: These errors may occur if the component or one of it's dependencies isn't registered fully on the system. For the component to function the Visual Basic 6 runtime must be installed and the files "XChargeCom2.dll" (installed to windows\system32 directory) and "wodhttp.dll" (installed to windows\system32 directory) must be registered. You should run the latest version of the installation program to resolve this problem or alternatively can manually register the component in the registry by following the procedure below: - Start a command prompt (click on your start menu, type "cmd.exe" and enter in the run text box). - Navigate to your windows system32 directory. By default this directory is called \winnt\system32 on Windows 2000 systems or \windows\system32 on Windows XP or Windows 2003 systems. - Type the following commands at the command prompt: - regsvr32 /u XChargeCom2.dll - regsvr32 /u wodhttp.dll - regsvr32 wodhttp.dll - regsvr32 XChargeCom2.dll ------ **PROBLEM**: When I try to use the sample ASP scripts or when I try to include the file "xcenums.inc" in my ASP script the following error occurs: Active Server Pages, ASP 0126 (0x80004005) The include file 'xcenums.inc' was not found. **RESOLUTION**: This error occurs because the web server isn't able to locate the file for inclusion. You must provide the full virtual path in your include statement for IIS to properly locate the file. So, for example, if the file was located at the URL: "http://www.mywebsite.com/scripts/payments/xcenums.inc" then your include statement should look like this: ------ **PROBLEM**: I am using Ensim WEBppliance Pro for Windows and am unable to get the XCharge component to run on my web server ("ActiveX component can't create object" or "Invalid ProgID" error). **RESOLUTION**: Ensim WEBappliance Pro imposes a requirement that you must give explicit NTFS permission to WEBappliance to any Active-X component you wish to run under IIS. You can grant the appropriate permission to WEBappliance Pro to run the XCharge component by following this procedure: - Start a command prompt (click on your start menu, type "cmd.exe" and enter in the run text box). - Navigate to your windows system32 directory. By default this directory is called \winnt\system32 on Windows 2000 systems or \windows\system32 on Windows XP or Windows 2003 systems. - Type the following commands at the command prompt: - regsvr32 /u XChargeCom2.dll - regsvr32 /u wodhttp.dll - Create a directory to hold the components, in this example we'll create a folder called components on the root of c drive. - Move the files XChargeCom2.dll and wodhttp.dll from the windows system32 directory to the folder you created in the previous step. - Start another command prompt (click on your start menu, type "cmd.exe" and enter in the run text box). - Navigate to the directory you moved the files to and run the following commands at the command prompt: - regsvr32 XChargeCom2.dll - regsvr32 wodhttp.dll - Navigate to a directory a level above the folder you created (In our example this would be the root of c drive) and run the following commands (replacing the word components with name of the folder you created): - cacls components /t /e /r webppliance_siteadmins - cacls components /t /e /g webppliance_siteadmins:R This removes the webppliance_siteadmins:N permission and thus gives the webppliance_siteadmins access to read this folder and all it's subfolders. ------ **PROBLEM**: I can not get the XCharge component to work in ASP.NET. **RESOLUTION**: Since the ASP.NET has to use COM Interop to use the XCharge component make sure any ASP.NET project you create that uses the XCharge component has the aspCompat property/attribute set to true. ------ **PROBLEM**: When attempting to install the XCharge component I receive the following error: "This setup requires Internet Information Server 4.0 or higher for configuring IIS Virtual Roots. Please make sure that you have IIS 4.0 or higher." **RESOLUTION**: You can safely click the Ignore button to complete installation. This error is normal for computers that don't have IIS installed. The only consequence of clicking the ignore button is that an IIS virtual roots for the ASP.NET example applications will not be created. ------ **PROBLEM**: I get the following error when opening the example Microsoft Visual Studio 2003 ASP.NET solution file: "Visual Studio.NET has detected that the specified Web server is not running ASP.NET version 1.1" **RESOLUTION**: Make sure of the following. * You have IIS 4.0 or higher installed and running properly. * You have Microsoft Visual Studio 2003 installed and running properly. * You have at least version 1.1 of the .NET framework installed. * If all the above is true, try the following: * Using the command prompt navigate to your .NET framework directory. The framework directory should be located under windows directory, for example "C:\WINDOWS\Microsoft.NET\Framework\v1.xx.xx" (where xx.xx is the latest version of the .NET framework installed on your machine). In the that directory run the following command: **aspnet_regiis -i** ------ **PROBLEM**: When attempting to run ASP code you get error E50021 - Unable to verify the first certificate. **RESOLUTION**: Make sure the file %SystemRoot%\system32\wodcerts.txt exists and the account that the XCharge component is running under has read access to it. ------ **PROBLEM**: When attempting to run ASP code you get error E50027 - Certificate not trusted. **RESOLUTION**: Make sure you are running the latest version of the component which includes the most up to date version of the file %SystemRoot%\system32\wodcerts.txt. ===== Reference ===== ==== Read/Write Properties ==== ^Property ^Description^ |SourceKey |Source Key generated by the Merchant Console at www.usaepay.com.| |Pin |If a source pin code is set in the merchant console then the Pin property is required to have the same value. This value is used to send a MD5 encoded validation hash.| |MD5Key |This optional property can be as simple as a timestamp or it can contain any randomly generated data. When a merchant console pin is set then this optional string is added to the MD5 encoded validation hash to increase the uniqueness of the hash string sent.| |IgnoreDuplicate |Set to TRUE if you would like to override the duplicate transaction handling.| |AuthCode |Authorization Code obtained "offline" (ie telephone authorization). Only required when "Command" is set to 5-postauth.| |RefNum |The value of "ResponseReferenceNum" property received when a transaction was authorized via either the 0-sale or 3-authonly commands. Required when the "Command" property is set to 2-cvoid or 4-capture.| |Command |Command to run. Possible values are: //0-sale//, //1-credit//, //2-cvoid//, 3-authonly, //4-capture//, //5-postauth//, //6-check//, //7-checkcredit//, //8-creditvoid//. Default is //0-sale//.| |Card |Credit Card Number with no spaces or dashes| |Exp |Expiration Date in the form of MMYY with no spaces or punctuation| |Amount |Charge amount without $. The "Amount" property should include the total amount to be charged, including sales tax.| |AmtCurrency |Currency of the Amount property. Required if using a MCP based account. Must be one of the 3 digit numeric codes found [[http://wiki.usaepay.com/developer/currencycode|here.]]| |Tax |The portion of Amount that is sales tax.| |NonTaxable |Set to TRUE if transaction is not taxable. (optional, platform dependent).| |Clerk |Optional property indicating the clerk/person processing transaction, for reporting purposes.| |Terminal |Optional property indicating the terminal used to process transaction, for reporting purposes.| |Table |Optional property indicating the restaurant table, for reporting purposes.| |Tip |Portion of charge amount (Amount property value) that is for gratuity (tip).| |Shipping |Portion of charge amount (Amount property value) that is for shipping charges.| |Discount |The amount of any discounts that were applied.| |Subtotal |The amount of the order before tip, shipping, discount and tax were applied. Subtotal + Tip + Shipping - Discount + Tax must equal Amount. If Subtotal property is not set then it will be ignored.| |Invoice |Unique ticket, invoice or order number. 10 digits.| |OrderID |Order identifier. This property can be used to reference the order for which this transaction corresponds to. This property can contain up to 64 characters and should be used instead of the Invoice property when orderids longer than 10 digits are needed.| |Ticket |Obsolete, included for backward compatibility. Use "Invoice" instead.| |PONum |Customer purchase order number. Only required for commercial cards.| |TransHolderName |Name on card / Name of checking account owner.| |Street |Street address for use in AVS check.| |Zip |Zipcode for AVS check.| |Description |Optional description of transaction.| |CVV2 |CVV2 data for Visa.| |CustEmail |Customer's Email address (optional)| |CustID |Unique customer id.| |CustReceipt |Send a customer receipt. Note, this will override the source setting. (defaults to FALSE). This overrides the setting for the merchant and source.| |IP |The IP address of the client requesting the transaction. This is used in many of the fraud modules (optional).| |Software |Allows application developers to stamp their application name and version number on to each transaction. Used to assist customers with trouble shooting. Not Required.| |TestMode |If set to TRUE then the transaction will be simulated but not actually processed. (defaults to FALSE). | ==== Electronic Check Transactions ==== To process checks through the component, the merchant must have an account with one of the supported check processors. Please contact support to setup an account or if you have any questions about adding support for check processing. The properties required for processing checks are: SourceKey, Routing, Account, Amount, TransHolderName and identification information. Identification info can either be SSN (social security number) or DLNum and DLState. ^Property ^Description^ |Routing |Bank Routing number. Required when "Command" is set to 6-check or 7-checkcredit.| |Account |Checking Account Number. Required when the "Command" property is set to 6-check or 7-checkcredit.| |DLNum |Driver's License Number. Required for check transactions if not using "SSN".| |DLState |Driver's License Issuing State. Required for check transactions if not using "SSN".| |CheckNum |Optional Check number value.| ==== Recurring Billing ==== The component supports adding customers to a recurring billing cycle automatically. The Recurring property has to be set to a value of TRUE in order for the customer to be added automatically into the Recurring Billing section of the Merchant Console vTerminal. The customer will only be added if the initial charge goes through; therefore the card is charged for the first payment and if approved, is added to the recurring billing cycle. The initial charge and the recurring charge can be different values by using the Amount property as the initial charge and RecurringBillAmount as the recurring charge. If the RecurringBillAmount property is not set then the value of the Amount property will also be the recurring charge. ^Property ^Description^ |Recurring |If set to TRUE the system will enter the transaction as a recurring billing entry after the transaction has been approved. (defaults to FALSE).| |RecurringBillAmount |Sets the amount to charge on each cycle. If this property is left blank then the "Amount" property will be used instead. This is NOT the "initial" charge or "setup" charge, this is the "recurring" charge. The value of the "Amount" property is the initial charge.| |RecurringSchedule |How often to repeat the transaction. Possible values are: //0-daily//, //1-weekly//, //2-biweekly//, //3-monthly//, //4-bimonthly//, //5-quarterly//, //6-annually//, //7-biannually//. Default is //3-monthly//.| |RecurringNumLeft |Number of times to repeat transaction. If the recurring billing should go on indefinitely, set this to *. The default is *.| |RecurringStartDate |When to start the recurring schedule. Default is tomorrow. Must be entered in YYYYMMDD format. If RecurringStartDate is set to next then the date of the next billing cycle will be used. For example if today is 1/10/2004 and RecurringSchedule is set to 3-monthly then RecurringStartDate will be set to 2/10/2004.| |RecurringEndDate |When to end the recurring schedule. Default is no expiration. If both "RecurringEndDate" and "RecurringNumLeft" are specified, transaction will stop when the earliest condition is met. Must be entered in YYYYMMDD format.| ==== Recurring Billing Methods ==== ^Property ^Description^ |SetRecurringCustom |Optional. Takes two input parameters, an index (valid values are 0 through 19), and a string value. Used for storing custom data. This data is stored in the customer record, not the transaction.| |GetRecurringCustom |Expects one input parameter specifying an index (valid values are 0 through 19), this retrieves the value previously set by the SetRecurringCustom method.| ==== Cardholder Authorization (Verified By Visa and Mastercard SecureCode) ==== This component supports VPAS (Verified by Visa) and UCAF (Mastercard Securecode) with both an integrated authentication system and support for third party verification. Using the integrated solution provides a quick and easy method for developers to support Verified by Visa and Mastercard Secure Code without having to deal with the complicated XML messaging formats required. To use the integrated solution, the merchant must first have an account with Cardinal Commerce. If the merchant does not have an account, but requests authentication, the transaction will be handled as if the cardholder is not enrolled in the Verified by Visa and/or Mastercard Secure Code Program. The following is the process that must be used when using the integrated solution: - Merchant's site collects card holder information - Merchant's site sends an authorization command with the CardAuth property set to TRUE - Component checks to see if the cardholder is enrolled in the Verified by Visa and/or Mastercard Secure Code program. If the cardholder has not set a password then the transaction is approved or declined as usual (component will set ResponseStatus property to 0 - Approved or 1 - Declined). If the cardholder does have a password then the component will set the ResponseStatus property to 2 - Verification indicating that the merchant's site needs to prompt the user for a password. The component will also set the ResponseACSURL and ResponsePayload properties. - Merchant's site must send the customers browser to the url contained in the ResponseACSURL property with three get values: PAReq set to the value in ResponsePayload property, TermUrl set to the url on the merchant's site that will continue the transaction, MD set to some identifying information such as order number that will allow the order to continue. - Customer enters their username and password. If authentication is successful they will be sent back to TermUrl with the variable PaRes set. - Merchant's sends a second authentication request with the component identical to the one sent in step 2 except that the Pares property is set the value of PaRes. - Component sets the response properties including the approved or declined status as normal. If using a third party verification system or if implementing the Cardinal Commerce API on the merchant's side, simply pass XID, CAVV and ECI with the authentication request. Mastercard Secure Code only uses the CAVV property. ^Property ^Description^ |CardAuth |When set to TRUE enables Cardholder Authentication. The merchant must have a Cardinal Commerce account enabled. If they don't have an account, then this property will be ignored and the transaction will be processed normally (without authorization). Defaults to FALSE.| |Pares |Cardholder authentication payload. When using the integrated authentication system. The authentication response received from the independent authentication site.| |XID |XID value received from third party authenticator. Only needed if NOT using the component authentication system.| |CAVV |CAVV value received from third party authenticator. If you support CAVV but customer did not participate you must set this value to -1. This flags our system that you support VbV/MC Secure Code. Only needed if NOT using the component authentication system.| |ECI |ECI value received from third party authenticator. Only needed if NOT using the component authentication system.| ^Billing Address Properties^^ |BillFName | | |BillLName | | |BillCompany | | |BillStreet | | |BillStreet2 | | |BillCity | | |BillState | | |BillZip | | |BillCountry | | |BillPhone | | |Email | | |Fax | | |Website | | ^Shipping Address ^Optional^ |ShipFName | | |ShipLName | | |ShipCompany | | |ShipStreet| | |ShipStreet2| | |ShipCity| | |ShipState| | |ShipZip| | |ShipCountry| | |ShipPhone| | ==== Card Present Transactions ==== ^Property ^Description^ |CptCardPresent |Set this property to TRUE to enable card present mode. If the CptMagStripe property is set, then CptCardPresent will be automatically set to TRUE.| |CptMagStripe |Mag stripe data read from card. Can include Track 1, Track 2 or both.| |CptTermType |The type of terminal being used. Possible values are: //0-POS// (cash registers), //1-StandAlone// (self service terminals), //2-Unattended// (gas pumps), //3-TermTypeUnknown//, Default is //3-TermTypeUnknown//.| |CptMagSupport |Support for mag stripe reader. Possible values are: //0-MagSupportYes//, //1-MagSupportN//o, //2-MagSupportUnknown//, //3-MagSupportContactless//. Default is //2-MagSupportUnknown// unless magstripe has been sent.| |CptContactless |Set to TRUE if the CptMagStripe property was set via a contactless swiper (default is FALSE).| ==== Methods ==== ^Function ^Description^ |CheckData |Checks data for formatting or syntactical errors and populates the Errors property collection with error codes and descriptions of any problems found. This method runs automatically when the Process method is called. Returns FALSE if no errors were found, otherwise returns TRUE.| |Process |Submits the transaction.| ==== Read-Only Properties ==== ^Property ^Description^ |Errors |Collection of Error objects containing Error numbers (.ErrorCode) and descriptions (.ErrorText) of ANY errors found. You must use a loop to iterate through the Errors property collection as shown in the sample code. Click HERE to see a list of possible errors codes and text that you may receive from the component.| |ErrorExists |Returns TRUE if there are any errors in the Errors property collection, otherwise the property is FALSE.| |Version |Version number of XCharge component.| ==== Read-Only Response Properties ==== ^Property ^Description^ |ResponseStatus |Status of the transaction. The possible values are: //0-Approved//, //1-Declined//, //2-Verification//, //3-Error//| |ResponseAuthCode |Authorization number.| |ResponseResult |Transaction result.| |ResponseReferenceNum |Transaction reference number.| |ResponseBatch |Batch reference number. This will only be returned when the Command property is set to 0-sale or 3-authonly.| **Warning: The batch number returned is for the batch that was open when the transaction was initiated. It is possible that the batch was closed while the transaction was processing. In this case the transaction will get queued for the next batch to open.** |ResponseAVS |The result of the AVS check in human readable format.| |ResponseAVSCode |Address Verification System Result Codes | |ResponseCVV2 |The result of the CVV2 check in human readable format.| |ResponseCVV2Code |Card ID Result Codes | |ResponseVPASCode |Verified by Visa or Mastercard SecureCode result code.| |ResponseError |Error description if transaction is declined or there is an error.| |ResponseErrorCode |A numerical error code from the gateway.| |ResponseACSURL |Verification url to send cardholder to. Sent when the ResponseStatus property is 2-verification (cardholder authentication is required).| |ResponsePayload |Authentication data to pass to verification url. Sent when the ResponseStatus property is 2-verification (cardholder authentication is required).| |ResponseIsDuplicate |Indicates whether this transaction is a folded duplicate or not. 'Y' means that this transaction was flagged as duplicate and has already been processed. The details returned are from the original transaction. Set the IgnoreDuplicate property to override the duplicate folding.| |ResponseConvertedAmount |Amount converted to merchant's currency, when using a multicurrency processor.| |ResponseConvertedAmountCurrency |Merchant's currency, when using a multicurrency processor.| |ResponseConversionRate |Conversion rate used to convert currency, when using a multicurrency processor.| |ResponseCustNum |Customer reference number assigned by gateway. Returned only if the Recurring property is set to TRUE.| ===== Error List ===== ===== General Syntax Errors ===== ^Error Number ^Error Text ^ |E1001 |Transaction not processed yet. | |E1002 |Source key is required. | |E1003 |Reference number is required. | |E1004 |Credit card number is required. | |E1005 |Expiration date is required. | |E1006 |Amount is required. | |E1007 |Card/Check holder name is required.| |E1008 |Street address is required.| |E1009 |Zipcode is required.| |E1010 |Value of ResponseError property.| |E1013 |Bank routing number is required.| |E1014 |Checking account number is required.| |E1015 |Identification information is required. Identification info can either be SSN (social security number) or DLNum (Drivers License Number) and DLState (Drivers License Issuing State).| |E1016 |Value of ResponseErrorCode property.| ===== Communication Related Errors ===== ^Error Number ^Error Text ^ |E1011 |Error reading from card processing gateway.| |E1012 |Error parsing data from card processing gateway.| |E20001 |Item not found in Headers collection.| |E20002 |File not found.| |E20003 |File read error.| |E20005 |Could not create file.| |E20006 |Could not write to file.| |E20007 |Unsupported proxy type.| |E20008 |Server response invalid.| |E20009 |Cannot change host information at this time.| |E20010 |Operation invalid in this state.| |E20011 |Could not set Content-Type header. Is it already set to some other value?| |E20013 |SSL handshake was not successful and was shut down. Possible bad implementation of SSL on the server side.| |E20014 |SSL handshake failed:| |E30040 |Proxy server has closed the connection.| |E30041 |Proxy server rejected supplied login credentials.| |E30042 |Proxy Hostname not set.| |E39999 |License key missing. You can not use this component in design environment.| ===== Certificate Related Errors ===== ^Error Number ^Error Text ^ |E50000 |Certificate ok| |E50002 |Certificate error: Unable to get issuer certificate.| |E50003 |Certificate error: Unable to get CRL (Certificate revocation list).| |E50004 |Certificate error: Unable to decrypt certificate signature.| |E50005 |Certificate error: Unable to decrypt CRL (Certificate revocation list) signature.| |E50006 |Certificate error: Unable to decode issuer public key.| |E50007 |Certificate error: Certificate signature failure.| |E50008 |Certificate error: CRL (Certificate revocation list). signature failure.| |E50009 |Certificate error: Certificate not yet valid;| |E50010 |Certificate error: Certificate has expired.| |E50011 |Certificate error: CRL not yet valid.| |E50012 |Certificate error: CRL has expired.| |E50013 |Certificate error: Certificate does not have 'before' field.| |E50014 |Certificate error: Certificate does not have 'after' field.| |E50015 |Certificate error: CRL does not have 'last update' field.| |E50016 |Certificate error: CRL error in 'next update' field.| |E50017 |Certificate error: Out of memory while reading certificate.| |E50018 |Certificate error: Depth zero self signed certificate.| |E50019 |Certificate error: Self signed certificate in chain.| |E50020 |Certificate error: Unable to get issuer certificate locally.| |E50021 |Certificate error: Unable to verify the first certificate. Make sure the file %SystemRoot%\system32\wodcerts.txt exists and the account that the XCharge component is running under has read access to it.| |E50022 |Certificate error: Certificate chain too long.| |E50023 |Certificate error: Certificate revoked.| |E50024 |Certificate error: Invalid Cartificate Authority.| |E50025 |Certificate error: Path length exceeded.| |E50026 |Certificate error: Invalid certificate purpose.| |E50027 |Certificate error: Certificate not trusted. Make sure you are running the latest version of the component which includes the most up to date version of the file %SystemRoot%\system32\wodcerts.txt.| |E50028 |Certificate error: Certificate rejected.| |E50029 |Certificate error: Subject issuer mismatch.| |E50030 |Certificate error: Authority and subject key identifier mismatch.| |E50031 |Certificate error: Authority and issuer serial number mismatch.| |E50032 |Certificate error: Key usage does not include certificate signing.| |E50050 |Certificate error: Application verification failure.| ===== Change Log ===== ver. 2.12.0 (10/10/2007): * Updated documentation. * Changed gateway URL to https://secure.usaepay.com/gate.php to reflect newly installed SSL certificate. * Added IgnoreDuplicate, AmtCurrency, CheckNum, and CptContactless properties. * Added ResponseIsDuplicate, ResponseConvertedAmount, ResponseConvertedAmountCurrency, ResponseConversionRate, and ResponseCustNum response properties. * Added 8-creditvoid option to the Command property enumeration. * Added SetRecurringCustom and GetRecurringCustom methods. * Documented the -1 flag option for VbV/MC Secure code transactions (applies to CAVV property). * Added 3-MagSupportContactless option to the CptMagSupport property enumeration. * Updated wodhttp.dll component to 1.5.4. * Updated xcenums.inc to include creditvoid and MagSupportContactless constants. * Updated all examples to reflect new response properties and command enumerations. ver. 2.9.5 (9/18/2006): * Updated documentation. * Added Clerk, Terminal, and Table properties. * Updated wodhttp.dll component to 1.4.6. ver. 2.9.3 (11/15/2005): * Updated documentation. * Updated errorslist.html documentation. * Added Tip, Shipping, Discount, OrderID, Subtotal and NonTaxable properties. * Added ResponseVPASCode and ResponseErrorCode response properties. * Added next option to the RecurringStartDate property. * Updated wodhttp.dll component to 1.3.8. * Added Access and VB.NET control and component examples. * Updated all examples to reflect new response properties. ver. 2.8.6 (09/21/2004): * Updated documentation. * Updated errorslist.html documentation. * Updated wodcerts.txt to include information for USAePay's new server certificate. If you are experiencing error E50027: Certificate not trusted make sure you have run the latest install that includes this updated certificate data file. ver. 2.8.5 (09/13/2004): * Because of several architectural changes made to the control, this version of the XCharge control is not binary compatible with previous versions. The new control has a new file name, GUID, and ProgID. You should remove/uninstall any previous version of the control you may have in any existing projects and use the new version instead. * Added Active-X .dll version of XCharge component. For ASP or ASP.NET projects you MUST use the Active-X .dll component version. * Removed Destroy method. It is no longer needed. * Updated xcenums.inc to include CptTermTypeType and CptMagSupportType constants. * Removed ASP examples for control, added ASP, ASP.NET, VB, C#, and C++ examples for .dll component. Updated all other examples. * Updated wodhttp.dll component to 1.2.1.8. * Updated errorslist.html documentation. * Fixed typo so that the prefix Reponse is correctly spelled as Response for the following properties: ResponseAVS, ResponseAVSCode, ResponseCVV2 and ResponseCVV2Code. ver. 2.8.0 (08/14/2004): * Added Destroy method. * Added card present support with new properties: CptCardPresent, CptMagStripe, CptTermType, CptMagSupport. * Added Software property. * Added ResponseBatch response property. * Updated wodhttp.dll component to 1.2.1.5. * Updated errorslist.html documentation. * Updated VB, ASP, C#, C++, and ASP.NET examples. * Added ASP.NET Web Matrix sale charge example. * Added ASP.NET barebones aspx sale charge example. * Various small bug fixes. ver. 2.7.0 (01/27/2004): * Added new ResponseAVSCode and ResponseCVV2Code properties. * Added Pin and MD5Key properties, implementing new source pin feature. * Added C# (C Sharp) and ASP.NET examples. * Updated VB and ASP examples. * Updated wodhttp.dll component to 1.2.0.7. * Fixed occurrence of error "E1004 : Credit Card Number is required." when "Command" property is set to 6-check. ver. 2.5.4 (01/24/2004): * Fixed credit command not working under certain circumstances. ver. 2.5.3 (11/13/2003): * Changed the method the installation program uses to register the required components, the older method was causing the control to not be fully registered for use under IIS under some Windows 2000 server configurations. * If you're getting a "ActiveX component can't create object" or "Invalid ProgID" error we recommend you download and install this version of the control or newer to fix this problem. * Alternatively you can try this hot fix: - Start a command prompt (click on your start menu, type "cmd.exe" and enter in the run text box). - Navigate to your Windows system32 directory . - Type the following commands at the command prompt: - regsvr32 /u xcharge.ocx - regsvr32 /u wodhttp.dll - regsvr32 wodhttp.dll - regsvr32 xcharge.ocx ver. 2.5.2 (10/22/2003): * Added support for biannually value in RecurringSchedule property. ver. 2.5.1 (10/15/2003): * Complete re-write of XCharge control. It is recommended you uninstall and cease use of any previous version of this control. This control is NOT compatible with previous versions. * You may still download version 2.2 by [[http://www.usaepay.com/topics/xCharge22.zip|clicking here]].