XML Transaction API Into Secure Hosting

XML API into the SecureHosting transaction system

Summary

To provide an API into the current SecureHosting transaction system supporting the creation, refund, authorisation and detail capture of transactions through the UPG payment provider.

Interface

Calls will be made using XML (utf8 encoded) over a https connection to our servers.

The script to call will be:-

And each call should be posted using the variable name ‘xmldoc’.

XML Calls

The following pages now detail the specific xml required in order to perform the calls listed above. Examples have been included showing both the input and output xml files.

Transactions:

<?xml version="1.0"?>

<type>transaction</type>

<authtype>authorise</authtype>

</authentication>

cardexpiremonth>01</cardexpiremonth

cardexpireyear>06</cardexpireyear>

switchnumber>2</switchnumber

cardholdersname>SecureHosting</cardholdersname

cardholdersemail></cardholdersemail

cardholderaddr1>Address 1</cardholderaddr1

cardholdercity>City</cardholdercity

cardholderstate>State</cardholderstate

cardholderpostcode>Postcode</cardholderpostcode

</transaction>

<callbackdata>variable|value</callbackdata>

</callback>

<forename>Forename</forename>

<surname>Surname</surname>

</addtolists>

</emailmanager>

</request>

Result on Success: -

<?xml version="1.0"?>

<cv2avsresult>ALL MATCH</cv2avsresult>

<cardtype>Visa Debit</cardtype>

</result>

Result on Error: -

<?xml version="1.0"?>

<status>ERROR</status>

<statustext>ERROR_DESCRIPTION</statustext>

</result>

Notes:

Any fields can be passed and captured as part of the transaction, the standard field (node) names should be defined as those set up within the “Settings/Form Field Settings” menu within your Securehosting account.

The “authtype” node is only available for a “transaction” call and is optional it is only required if you wish to override the auth type that is used ie. If your account is set to authorise immediately but you have a transaction that you wish to put through on pre-auth as you have limited stock etc.

The types which can be defined are:- “authorise” (authorise payments immediately) and “pre_auth” (verify card/funds without debiting the card) ie.

<authtype>authorise</authtype>

Failed transactions will be returned with a status of ERROR, a “reason” node will return the transaction error message.

The callback and emailmanager parent nodes are optional.

Error Messages:

A number of predefined error messages maybe additionally returned when performing tasks. These errors should help any error debugging by more precisely documenting the problem.

DATABASE_ERROR – Problem connecting to database.

INVALID_LOGIN – Incorrect SH Reference, checkcode or password.

NO_XML_PASSED – No XML document passed.

BAD_XML_PASSED – Invalid XML passed.

DATA_ERROR – An error with the data passed, such as invalid transaction id for a refund.

CREDIT_ERROR – An error the credit system, check enough credits exist.

UPG_ERROR – Specific error with payment gateway.

TRANSACTION_ERROR – An error occurred with the payment, a further node called reason will contain more details.

Mail Order Transactions:

<?xml version="1.0"?>

</authentication>

cardexpiremonth>01</cardexpiremonth

cardexpireyear>06</cardexpireyear>

switchnumber>2</switchnumber

cardholdersname>SecureHosting</cardholdersname

cardholdersemail></cardholdersemail

cardholderaddr1>Address 1</cardholderaddr1

cardholdercity>City</cardholdercity

cardholderstate>State</cardholderstate

cardholderpostcode>Postcode</cardholderpostcode

</transaction>

<callbackdata>variable|value</callbackdata>

</callback>

<forename>Forename</forename>

<surname>Surname</surname>

</addtolists>

</emailmanager>

</request>

Please note:

The only difference between the XML calls for a normal transaction and a mail order transaction is the type element.

Refunds:

<?xml version="1.0"?>

<type>refund</type>

<password>testing</password>

</authentication>

</transaction>

</request>

Result on Success: -

<?xml version="1.0"?>

</result>

Result on Error: -

<?xml version="1.0"?>

<status>ERROR</status>

<statustext>ERROR_DESCRIPTION</statustext>

</result>

Error Messages:

A number of predefined error messages maybe additionally returned when performing tasks. These errors should help any error debugging by more precisely documenting the problem.

DATABASE_ERROR – Problem connecting to database.

INVALID_LOGIN – Incorrect SH Reference or password.

NO_XML_PASSED – No XML document passed.

BAD_XML_PASSED – Invalid XML passed.

DATA_ERROR – An error with the data passed, such as invalid transaction id for a refund.

CREDIT_ERROR – An error the credit system, check enough credits exist.

UPG_ERROR – Specific error with payment gateway.

Authorisations:

<?xml version="1.0"?>

<type>authorisation</type>

<password>testing</password>

</authentication>

</transaction>

</request>

Result on Success: -

<?xml version="1.0"?>

</result>

Result on Error: -

<?xml version="1.0"?>

<status>ERROR</status>

<statustext>ERROR_DESCRIPTION</statustext>

</result>

Notes:

“Amount” should be the authorisation amount, this can be either the full transaction amount or a partial amount.

Error Messages:

A number of predefined error messages maybe additionally returned when performing tasks. These errors should help any error debugging by more precisely documenting the problem.

DATABASE_ERROR – Problem connecting to database.

INVALID_LOGIN – Incorrect SH Reference or password.

NO_XML_PASSED – No XML document passed.

BAD_XML_PASSED – Invalid XML passed.

DATA_ERROR – An error with the data passed, such as invalid transaction id for an authorisation.

AUTH_ERROR – An error performing the authorisation, such as the original transaction > 28 days.

CREDIT_ERROR – An error the credit system, check enough credits exist.

UPG_ERROR – Specific error with payment gateway.

Additional Payments:

<?xml version="1.0"?>

<type>additional</type>

</authentication>

<secuitems<![CDATA[[123||example|34.99|1|34.99]]]</secuitems>

<cardholdersname>SecureHosting</cardholdersname>

<cardholderaddr1>Address 1</cardholderaddr1>

<cardholderaddr2>Address 2</cardholderaddr2>

<cardholderstate>State</cardholderstate>

<cardholdercountry>Country</cardholdercountry>

<cardholderpostcode>Postcode</cardholderpostcode>

</transaction>

<callbackdata>variable|value</callbackdata>

</callback>

</request>

Result on Success: -

<?xml version="1.0"?>

<cv2avsresult>ALL MATCH</cv2avsresult>

<cardtype>Visa Debit</cardtype>

</result>

Result on Error: -

<?xml version="1.0"?>

<status>ERROR</status>

<statustext>ERROR_DESCRIPTION</statustext>

</result>

Notes:

If you leave any of the following fields blank the values from the original transaction will be used:-

cardholdersname, cardholderaddr1, cardholderaddr2, cardholdercity, cardholderstate, cardholdercountry, cardholderpostcode

Please note as with a normal transaction any field can be passed and captured as part of the additional transaction, the standard field (node) names should be defined as those set up within the Form Field Settings.

Failed transactions will be returned with a status of ERROR, a “reason” node will return the transaction error message.

The callback nodes are optional.

Error Messages:

A number of predefined error messages maybe additionally returned when performing tasks. These errors should help any error debugging by more precisely documenting the problem.

DATABASE_ERROR – Problem connecting to database.

INVALID_LOGIN – Incorrect SH Reference, checkcode or password.

NO_XML_PASSED – No XML document passed.

BAD_XML_PASSED – Invalid XML passed.

DATA_ERROR – An error with the data passed, such as invalid transaction id for a refund.

CREDIT_ERROR – An error the credit system, check enough credits exist.

UPG_ERROR – Specific error with payment gateway.

TRANSACTION_ERROR – An error occurred with the payment, a further node called reason will contain more details.

Order TrackingSet Status:

<?xml version="1.0"?>

<type>setstatus</type>

<password>testing</password>

</authentication>

<status>Payment Processed</status>

</transaction>

</request>

Result on Success: -

<?xml version="1.0"?>

</result>

Result on Error: -

<?xml version="1.0"?>

<status>ERROR</status>

<statustext>ERROR_DESCRIPTION</statustext>

</result>

Notes:

If the order status doesn’t already exist, it will be created. The field is case insensitive.

Error Messages:

A number of predefined error messages maybe additionally returned when performing tasks. These errors should help any error debugging by more precisely documenting the problem.

DATABASE_ERROR – Problem connecting to database.

INVALID_LOGIN – Incorrect SH Reference or password.

NO_XML_PASSED – No XML document passed.

BAD_XML_PASSED – Invalid XML passed.

DATA_ERROR – An error with the data passed, such as invalid transaction id for the update.

Order Tracking Get Status:

<?xml version="1.0"?>

<type>getstatus</type>

<password>testing</password>

</authentication>

<passwordfield>cardholdersemail</passwordfield>

</transaction>

</request>

Result on Success: -

<?xml version="1.0"?>

cardholdersname>SecureHosting</cardholdersname

cardholdersemail></cardholdersemail

cardholderaddr1>Address 1</cardholderaddr1

cardholdercity>City</cardholdercity

cardholderstate>State</cardholderstate

cardholderpostcode>Postcode</cardholderpostcode

purchaseditems

<item>

code>001</code>

</item>

</purchaseditems>

<field1>value1</field1>

<field2>value2</field2>

</extrafields>

</transaction>

</result>

Result on Error: -

<?xml version="1.0"?>

<status>ERROR</status>

<statustext>ERROR_DESCRIPTION</statustext>

</result>

Error Messages:

A number of predefined error messages maybe additionally returned when performing tasks. These errors should help any error debugging by more precisely documenting the problem.

DATABASE_ERROR – Problem connecting to database.

INVALID_LOGIN – Incorrect SH Reference or password.

NO_XML_PASSED – No XML document passed.

BAD_XML_PASSED – Invalid XML passed.

DATA_ERROR – An error with the data passed, such as invalid transaction id for the update.

INVALID_PASSWORD – Incorrect transaction reference or password relating to transaction.

Appendix 1: PHP Transaction Example

$xmlfile = "./api_transaction.xml";

$xmldoc = file_get_contents($xmlfile);

$post_vars = "xmldoc=".urlencode($xmldoc);

$ch = curl_init();

curl_setopt ($ch, CURLOPT_URL, "

curl_setopt ($ch, CURLOPT_POST, 1);

curl_setopt ($ch, CURLOPT_POSTFIELDS, $post_vars);

curl_setopt ($ch, CURLOPT_HEADER, 0);

curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);

curl_setopt ($ch, CURLOPT_TIMEOUT, 15);

$xml_text = trim(curl_exec ($ch));

if ($xml_text == "") print (date("Y-m-d H:i:s")." XML Doc Empty");

if (curl_error($ch)) print (date("Y-m-d H:i:s")." cURL Call Failed - ".curl_error($ch));

curl_close ($ch);

print $xml_text;

Transaction XML APIPage 1 of 12