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.

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 is an ActiveMerchant module implementing this API. You may access this from the main repository.

  • 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 "
    &amp;
    ” and “
    &lt;
    “. 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:

Contact iTransact

Please do not hesitate to contact us with any questions.

iTransact
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.

Search iTransact.com