XML API Connection Method

The XML API features allows submission of transaction requests using API key credentials. Using this system, merchants and resellers can submit orders, voids, etc. through any their gateway accounts.

Uses

This module can be used to originate Authorization, Sale, Refund, Credit, Force, Postauth, Retry and Void transactions. It can also be used to request transaction status data and the details of recurring transactions. Recurring transactions can also be updated using this module. It provides the same features as form based transactions such as:

• Merchant and customer emails
• Customized email text
• Transaction Meta-Data

Authentication is handled using the combination of a username and a HMAC digest. A HMAC digest verifies both the authenticity and data integrity for a request payload. Our implementation is based on HMAC-SHA-1 using a 160 bit key. By using a signature based authentication scheme we can validate who generated an API request and ensure that the request was not altered using a man-in-the-middle attack. This digest must be calculated and passed through in the request by the merchant. This is probably the hardest part of the integration but we have provided example code for most major web development languages.

For detailed information, please download the gateway documentation.

Supported API Requests

Transaction Requests

AuthTransaction

This action is used to generate sale transactions and preauthorizations. This also contains the instructions to originate a transaction and set it to recur automatically.

BatchClose

This action is used to generate batch settlements. This also allows for testing batch settlements.

CreditTransaction

This action will generate a credit/refund transaction for a transaction that was not originally processed through the gateway.

PostAuthTransaction

This action will generate a postauth (capture) for a previously run preauth transaction.

TranCredTransaction

This action will a generate a refund for a previously run transaction.

TranForceTransaction

This action will generate a force (capture) for a previously failed transaction.

TranRetryTransaction

This action will generate a sale transaction from a previously failed or successful transaction.

VoidTransaction

This action will void any sale, credit, or refund transaction if processed prior to the daily batch settlement.

TransactionStatus

This action is used to determine the status of a request that was interrupted for some reason.

Recurring Requests

AuthTransaction

This action is used to originate a transaction and set it to recur automatically.

RecurUpdate

This action is used to modify the transaction information and recurring commands for a recurring transaction.

RecurDetails

This action is used to query for details on an existing recurring transaction.

API Libraries - Extended Examples

• Ruby - There has been an ActiveMerchant patch submitted that has a module implementing this API. It has been accepted but in not yet included in an official release. Until the new version of active_merchant gem is released, you may access this Gemfile
   
  gem 'activemerchant', :git => "git://github.com/Shopify/active_merchant.git"
   
  The 'itransact' module is compatible with PaymentClearing's interface.
• Perl - This module was created and submitted by a user. Please read more here. iTransact does not provide technical support for this module.
• PHP - We have created a small project that can send a sale request using this API. It is available at the following github repo.

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

 

 

---