XML API Connection
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.
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
- 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.
- This action will generate a credit/refund transaction for a transaction that was not originally processed through the gateway.
- This action will generate a postauth (capture) for a previously run preauth transaction.
- This action will a generate a refund for a previously run transaction.
- This action will generate a force (capture) for a previously failed transaction.
- This action will generate a sale transaction from a previously failed or successful transaction.
- This action will void any sale, credit, or refund transaction if processed prior to the daily batch settlement.
- This action is used to determine the status of a request that was interrupted for some reason.
- This action is used to originate a transaction and set it to recur automatically.
- This action is used to modify the transaction information and recurring commands for a recurring transaction.
- 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”
- 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.
- 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:
Please do not hesitate to contact us with any questions.
PO Box 999
314 South 200 West
Farmington UT 84025-0999
Phone: (801) 298-1212
Fax: (801) 298-9789
For technical assistance, please submit a ticket via the iTransact Support Center.