XML Connection Method :: XML Transaction Processing

PLEASE NOTE

The xmltrans.cgi and vendor password version xmltrans2.cgi modules have been deprecated. We will continue to maintain working versions of those methods, but any updates will be made to the XML Connection method which utilizes API keys and different request structures. If you are integrating a new system to the gateway, we highly suggest that you use the information found HERE.

Uses

The xmltrans.cgi module can be used to originate Force, Preauth, and Sale transactions. It provides the same features as form based transactions such as:

Merchant and customer emails
Customized email text
Initialization of recurring transactions

Submission Details

URL

https://(OBTAIN DOMAIN FROM YOUR REP)/cgi-bin/rc/xmltrans.cgi

MIME Type

xmltrans.cgi is accessed with a HTTP POST and requires a CONTENT_TYPE header to be specified. Either 'application/x-www-form-urlencoded' or 'text/xml' must be used. If 'application/x-www-form-urlencoded' is sent then the HTTP body must contain valid form markup. See WW3 Form Spec for details. If 'text/xml' is used then the HTTP body should only contain the XML request.

XML Structures

SaleRequest

<SaleRequest>
  <CustomerData>
    <Email>name@domain.com</Email>
    <CustId>Your Unique ID</CustId>
    <BillingAddress>
      <Address1>100 This Street</Address1>
      <FirstName>John</FirstName>
      <LastName>Smith</LastName>
      <City>Yourtown</City>
      <State>NY</State>
      <Zip>55555</Zip>
      <Country>USA</Country>
      <Phone>230-555-1212</Phone>
    </BillingAddress>
    <!-- Optional Shipping Address -->
    <ShippingAddress>
      <Address1>100 This Street</Address1>
      <City>Thatcity</City>
      <FirstName>John</FirstName>
      <LastName>Smith</LastName>
      <State>NY</State>
      <Zip>55555</Zip>
      <Country>USA</Country>
      <Phone>231-555-1212</Phone>
    </ShippingAddress>
    <AccountInfo>
      <!-- Include either credit card or check info.  Not both. -->
      <!-- For Credit card transaction. -->
      <CardInfo>
  	<CCNum>5454545454545454</CCNum>
   	<CCMo>05</CCMo> <!-- CCMo must be two digits. -->
    	<CCYr>2002</CCYr> <!-- CCYr must be four digits. -->
	  <!-- CVV2 information is optional.  Pass only if your Gateway account requires it. -->
     	  <CVV2Number>123</CVV2Number>
     </CardInfo> 
      <!-- For Check transactions. -->
      <CheckInfo> 
        <ABA>124000054</ABA>
        <Account>12345</Account>
        <AccountType>business</AccountType> <!-- business or personal -->
	<!-- Optional -->
        <CheckNum>100</CheckNum>
	<!-- Optional -->
        <CheckMemo>Memo text here</CheckMemo>
      </CheckInfo> 
    </AccountInfo>
  </CustomerData>
  <TransactionData>
    <!-- AuthCode optional.  (INDICATES FORCE TRANSACTION) -->
    <AuthCode>12345</AuthCode>
    <!-- Preauth optional.  (INDICATES PREAUTH TRANSACTION) -->
    <Preauth/>
    <VendorId>gateway id here</VendorId>
    <VendorPassword>gateway password</VendorPassword>
    <!-- Optional.  This information will be saved on our servers and is
      available in the XML transaction report.  This is useful if you want
      to save your own transaction meta-data with a transaction.    -->
    <VendorData>
        <Element>
            <Name>repId</Name>
            <Value>1234567</Value>
        </Element>
    </VendorData>    
    <HomePage>www.this.com</HomePage>
    <!-- Optional -->
    <RecurringData>
      <RecurRecipe>test</RecurRecipe>
      <RecurReps>5</RecurReps>
      <!-- Optional (For Split Recurring) -->
      <RecurTotal>100.00</RecurTotal>
      <!-- Optional (For Split Recurring) -->
      <RecurDesc>test2</RecurDesc>
      <!-- Optional (For Split Recurring) -->
    </RecurringData>
    <!-- Optional.  Text here will be included in transaction confirmation emails. -->
    <EmailText> <!-- Up to 10 EmailTextItem elements allowed.-->
      <EmailTextItem>line1</EmailTextItem>
      <EmailTextItem>line2</EmailTextItem>
    </EmailText>
    <OrderItems>
      <Item>
        <Description>item1</Description>
	<Cost>5</Cost>
	<Qty>1</Qty>
      </Item>
    </OrderItems>
  </TransactionData>
</SaleRequest>

SaleResponse

The SaleResponse is essentially a duplicate of the information provided in the SaleRequest. Note that ALL fields are provided in the response even if they were not included in the request. Schema is shown here with demo data.

<SaleResponse>
  <CustomerData>
    <Email>name@domain.com</Email>
    <BillingAddress>
      <Address1>100 This Street</Address1>
      <City>Yourtown</City>
      <FirstName>John</FirstName>
      <LastName>Smith</LastName>
      <State>NY</State>
      <Zip>55555</Zip>
      <Country>USA</Country>
      <Phone>230-555-1212</Phone>
    </BillingAddress>
    <ShippingAddress>
      <Address1>100 This Street</Address1>
      <Address2>Building 3</Address2>
      <City>Thatcity</City>
      <FirstName>John</FirstName>
      <LastName>Smith</LastName>
      <State>NY</State>
      <Zip>55555</Zip>
      <Country>USA</Country>
      <Phone>231-555-1212</Phone>
    </ShippingAddress>
    <AccountInfo>
      <!-- For Credit card transactions. -->
      <CardInfo>
        <CCLastFour>5454</CCLastFour>
        <CCName>Mastercard</CCName>
      </CardInfo> 
      <!-- For Check transactions. -->
      <CheckInfo> 
        <AccountType>Business</AccountType>
        <CheckNum>100</CheckNum>
        <CheckMemo>Memo text here.</CheckMemo>
      </CheckInfo> 
    </AccountInfo>
  </CustomerData>
  <TransactionData>
    <Status>OK</Status> <!-- Will be one of: ERROR, FAIL, FAILED, OK -->
    <!-- ErrorCategory will be one of :
	AVS_FAILURE - Transaction will be automatically voided.
	CVV2_FAILURE - Transaction will be automatically voided.
	INTERNAL_ERROR - Something unexpected happened.
	PROCESSOR_ERROR - Something such as DECLINED, etc .
	PROCESSOR_FAIL - 
	REQUEST_FORMAT - Request received has an invalid format.
	REQUEST_VALIDATION - XML content is invalid.
    -->
    <ErrorCategory></ErrorCategory>
    <!-- ErrorMessage could be anything. -->
    <ErrorMessage></ErrorMessage>
    <!-- Authorization code received from processing network. -->
    <AuthCode>12345</AuthCode>
    <!-- AVSResponse is actual AVS response received from processing network. -->
    <AVSResponse>A</AVSResponse>
    <!-- AVSCategory will be one of :
	address - Address Matched
	address_postal - Address and postal patched
	address_zip5 - Address and five digit zip matched
	address_zip9 - Address and nine digit zip matched
	address_ok_postal_format_error - Address matched, postal format error
	global_non_participant - International with no AVS support
	international_address_not_verified - International with no AVS support
	no_match - No address or postal match
	no_response - No response
	not_allowed - Not allowed
   	postal - Postal match
   	postal_ok_address_format_error - Postal matched, address format error
   	service_not_supported - AVS service not supported for card
   	unavailable - AVS service unavailable.
   	zip5 - Five digit zip matched
   	zip9 - Nine digit zip matched
	-->                  
    <AVSCategory>Address</AVSCategory>
    <!-- CVV2Response is actual CVV response received from the processing network. -->                
    <CVV2Response>M</CVV2Response>
    <TimeStamp>20021003172303</TimeStamp>
    <!-- TestMode indicates the test status of your gateway account. 0=off 1=on -->
    <TestMode>0</TestMode>
    <Total>100</Total>
    <XID>10000</XID>
    <RecurringData>
      <RecurRecipe>test</RecurRecipe>
      <RecurReps>5</RecurReps>
      <RecurTotal>100</RecurTotal>
      <RecurDesc>test2</RecurDesc>
    </RecurringData>
  </TransactionData>
</SaleResponse>

SaleResponse

This response is returned when an invalid response structure or mime type is sent

		
<?xml version="1.0" standalone="yes"?>
<GatewayFailureResponse>
<Status>FAILED</Status>
<ErrorCategory>REQUEST_FORMAT</ErrorCategory>
<ErrorMessage>Unexpected mime type: </ErrorMessage>
</GatewayFailureResponse>

Considerations

The XML Connection method is not activated on a gateway account by default. If a merchant desires to use the XML Connection method, an XML activation request needs to be sent to the sales rep.
There are certain characters such as '&' and '<' that may not appear in a XML request unless they are part of the actual XML structure. These characters have to be 'escaped' by using the forms " & " and " < ". More information about XML markup can be found at http://www.w3.org/TR/REC-xml/#syntax.
We suggest that you do not try and create XML structures by simply appending to a string with print statements. Using a XML generation library will ensure that you do not accidentally create badly formatted documents due to user input. The disadvantage of using a library is that it will take a little longer to code. If you do not use a library you need to make sure that any XML node text you are adding that is coming from a user gets escaped as described above. If you do not escape these characters you will have transactions occasionally fail due to a bad XML structure.
Here are some suggested XML generation libraries for different development environments. This is by no means an authoritative list and there are other good libraries available:

Java - ECS
Perl - XML::Generator
PHP - DOM
Ruby - REXML
.NET, C# - XMLTextWriter

Sidebar Heading

Sidebar Subheading

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin vitae lacus et massa viverra dictum.

Sidebar Subheading

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin vitae lacus et massa viverra dictum