Table of Contents

  1. The API integration process in Detail
  2. Step 1: Build your Request XML
  3. Step 2: Submitting the Request XML
  4. Step 3: Parsing the Response
  5. Step 4: Refunds
  6. Step 5: Authorisations
  7. Step 6: Additional Transactions
  8. Step 7: Mail Order Telephone Order Transactions
  9. Step 8: Continuous Authority
  10. Step 9: Transaction Downloads
  11. Step 10: 3-D Secure API

The API integration process in Detail

The API integration works by allowing you to keep the customer on your system through the checkout process while processing the transactions with SecureHosting in the background. This allows you to provide a smoother, more complete checkout process to the customer. In addition to transaction processing, you can also perform other actions with the API like refunds which can provide a more advanced integration with SecureHosting.

Requirements

In order to build your API integration you will need knowledge in the structure and language that your website or payment system is written in. You and your website/payment will need access to the internet in order to submit the transactions. You will also need to consider the Payment Card Industry Data Security Standard (PCI:DSS) when your system captures card details. For more information, please see https://www.pcisecuritystandards.org/.

Step 1: Build your Request XML

The first thing you will need to do when building your API integration is to build the request XML string. In order to allow future flexibility of your code, we advise you code the building of the request XML string in its own function/method. Below is an example request XML string for a transaction:

<?xml version="1.0"?>
<request>
    <type>transaction</type>
    <authtype>authorise</authtype>
    <authentication>
        <shreference>SH200000</shreference>
        <checkcode>000000</checkcode>
    </authentication>
    <transaction>
        <cardnumber>4242424242424242</cardnumber>
        <cardstartmonth>01</cardstartmonth>
        <cardstartyear>10</cardstartyear>
        <cardexpiremonth>01</cardexpiremonth>
        <cardexpireyear>12</cardexpireyear>
        <cv2>424</cv2>
        <cardholdersname>Joe Bloggs</cardholdersname>
        <cardholdersemail>joe@bloggs.com</cardholdersemail>
        <cardholderaddr1>Address 1</cardholderaddr1>
        <cardholdercity>City</cardholdercity>
        <cardholderstate>State</cardholderstate>
        <cardholderpostcode>Postcode</cardholderpostcode>
        <transactioncurrency>GBP</transactioncurrency>
        <transactionamount>29.00</transactionamount>
        <transactiontax>4.50</transactiontax>
        <shippingcharge>5.00</shippingcharge>
        <secuitems><![CDATA[
            [pd1|sku1|Product 1|10.00|2|20.00]
        ]]></secuitems>
    </transaction>
</request>

The "type" node identifies the type of request we are performing, in this instance we are doing a transaction. The "authtype" tells our system whether to perform a fully authorised ("authorise") or pre-authorised ("pre_auth") transaction. The "authtype" node is optional, if it's not supplied, the SecureHosting system will use the default account setting. For more information on Pre-Authorisation, please see the Processing A Transaction section of the SecureHosting Users Guide.

The "authentication" node holds the required data to identify the account to process the request with. All transaction fields are placed inside a "transaction" node. Similar to the hosted form integration, the below nodes are required to perform a transaction:

  • transactionamount
  • transactioncurrency
  • cardnumber
  • cardexpiremonth (2 digit month)
  • cardexpireyear (2 digit year)
  • cv2 (security code on reverse of the card)

The below nodes are optional but we recommend supplying them with every transaction:

  • transactiontax
  • shippingcharge
  • cardholdersname
  • cardholdersemail
  • cardholderaddr1
  • cardholderaddr2
  • cardholdercity
  • cardholderstate
  • cardholderpostcode
  • cardholdercountry
  • cardholdertelephonenumber

If you wish to submit any additional data with a transaction, you just create additional child nodes to the transaction node. The node name you give the field is the field name our system will use to store the data.

Step 2: Submitting the Request XML

Having build the request XML string, you now need to submit it to the SecureHosting API interface for processing. The string is submitted to the API interface as the value of a POST header field called "xmldoc". This POST field is then posted to our API interface via an inline HTTP call like cURL or ActiveXObject( "MSXML2.ServerXMLHTTP.6.0 " ). The response body of the call will be the response XML. For example code, please see Appendix I.

Step 3: Parsing the Response

Once you've submitted your request XML to the SecureHosting API interface, the response XML is picked up from the response body. Below is an example of the response XML for a successful transaction:

<?xml version="1.0"?>
<result>
    <status>OK</status>
    <reference>1234567</reference>
    <transactiontime>23:59:59</transactiontime>
    <transactiondate>2005-06-10</transactiondate>
    <cv2avsresult>ALL MATCH</cv2avsresult>
    <cardtype>Visa Debit</cardtype>
</result>

The "status" node will have the value of either "OK" or "ERROR", it the status is OK you will received additional node with transaction information. If the status is error there will be an additional node with an error type value called "statustext". The different possible error types are:

  • DATABASE_ERROR – There has been a problem talking to our database. If you see this issue, please contact our support department.
  • INVALID_LOGIN – The authentication credentials supplied are invalid.
  • NO_XML_PASSED – No XML as been supplied inside the post header field "xmldoc".
  • BAD_XML_PASSED – The XML supplied is improperly formatted and cannot be parsed.
  • DATA_ERROR – There is a problem with the request data supplied.
  • CREDIT_ERROR – The account does not have enough transaction credits to perform the request.
  • UPG_ERROR – There's been an error talking to our gateway system.
  • TRANSACTION_ERROR – There is a transaction problem, an additional node called "reason" will contain a textual description of the error.

Here is an example of a failed transaction response:

<?xml version="1.0"?>
<result>
    <status>OK</status>
    <reference>1234567</reference>
    <transactiontime>23:59:59</transactiontime>
    <transactiondate>2005-06-10</transactiondate>
    <cv2avsresult>ALL MATCH</cv2avsresult>
    <cardtype>Visa Debit</cardtype>
</result>

Below is a PHP code example to parse the response XML:

$response = simplexml_load_string( $xmlResponse );
if( (string)$response->status == 'OK' ){
    $transactionId = (int)$response->reference;
} else {
    if( (string)$response->statustext == 'TRANSACTION_ERROR' ){
        $errorMessage = (string)$response->reason;
    } else {
        $errorMessage = (string)$response->statustext;
    }
}

Step 4: Refunds

Along with processing transactions, you can also perform refunds against transaction via the API interface. Below is an example of a refund request XML string:

<?xml version="1.0"?>
<request>
    <type>refund</type>
    <authentication>
        <shreference>SH200000</shreference>
        <password>password</password>
    </authentication>
    <transaction>
        <reference>1374617</reference>
        <amount>34.99</amount>
    </transaction>
</request>

The value of the "type" node is "refund", within the authentication node, we still have the account SH reference value, however instead of the checkcode, we require the account password inside a node called "password". Inside the transaction node, we only need to reference of the transaction you are refunding along with the amount you wish to refund. As refunds are only processed against transactions, if any card details are supplied, they will be ignored. As the refund request XML does not contain any sensitive card details, you can actually implement refunds through the API interface without bringing your website or payment system into scope of PCI:DSS.

The response XML string, if successful will only contain a status node with a value of "OK":

<?xml version="1.0"?>
<result>
    <status>OK</status>
</result>

The response on error is the same as the standard transaction error response.

Step 5: Authorisations

This step is only relevant to merchant who pre-authorise their transactions, for more information on pre-authorisation, please see the Processing Payments section of the SecureHosting User Guide.

When a transaction has been pre-authorised, it will not be settled until the SecureHosting system received a request to settle the transaction, the API authorisation call is that request through the API. In order to authorise a pre-authorised transaction, you will need to send the API the below XML string:

<?xml version="1.0"?>
<request>
    <type>authorisation</type>
    <authentication>
        <shreference>SH200000</shreference>
        <password>password</password>
    </authentication>
    <transaction>
        <reference>12345678</reference>
        <amount>10.00</amount>
    </transaction>
</request>

The value of the "type" node is "authorisation", within the authentication node, we still have the account SH reference value, however instead of the checkcode, we require the account password inside a node called "password". Inside the transaction node, we only need to reference of the transaction you are authorising along with the amount you wish to settle. As authorisations are only processed against transactions, if any card details are supplied, they will be ignored. As the authorisation request XML does not contain any sensitive card details, you can actually implement authorisations through the API interface without bringing your website or payment system into scope of PCI:DSS.

The response XML string, if successful will only contain a status node with a value of "OK":

<?xml version="1.0"?>
<result>
    <status>OK</status>
</result>

The response on error is the same as the standard transaction error response.

Step 6: Additional Transactions

An “Additional Transaction” is a new transaction processed with the card details from a previous transaction. This type of transaction allows returning customers to use the same card they used on their last transaction. The way this works is by supplying a reference to the last transaction instead of the card details. If you do not supply values for the card details in the various nodes, we will use the details from the previous transaction.

The only exception to this is the security code (CVV or CV2) on the reverse of the card. Due to PCI:DSS it cannot be stored by any party but you can supply it in the request XML string, if you are able to obtain it from the cardholder anew. It is not mandatory to supply the CV2 number with an additional transaction but recommended to achieve higher authorisation rates and benefit from lower bank fees. Below is an example of an additional transaction request XML string:

<?xml version="1.0"?>
<request>
    <type>additional</type>
    <authentication>
        <shreference>SH200000</shreference>
        <checkcode>000000</checkcode>
    </authentication>
    <transaction>
        <reference>12345678</reference>
        <currency>GBP</currency>
        <transactionamount>29.00</transactionamount>
        <transactiontax>4.50</transactiontax>
        <shippingcharge>5.00</shippingcharge>
        <secuitems><![CDATA[
            [pd1|sku1|Product 1|10.00|2|20.00]
        ]]></secuitems>
        <cv2>123</cv2>
    </transaction>    
</request>

Responses are the same as normal transactions.

Step 7: Mail Order Telephone Order Transactions

If you wish to build your own virtual terminal system, you will need to ensure when processing your transactions, that your bank understands the transaction is a MOTO (Mail Order Telephone Order) transaction. The reason for this is because your bank will have different requirements in order to classify a transaction as secure, e.g. 3-D Secure is often required for internet transactions, but impossible for MOTO transactions. Also, if your account has been configured to process your MOTO transactions to a different MID from your eCommerce transactions, we will need to know it's a MOTO transaction.

To identify a transaction as MOTO, you send us a normal transaction XML string; however, the value of the "type" node will be "moto":

<?xml version="1.0"?>
<request>
    <type>moto</type>
    <authtype>authorise</authtype>
    <authentication>
        <shreference>SH200000</shreference>
        <checkcode>000000</checkcode>
    </authentication>
    <transaction>
        <cardnumber>4242424242424242</cardnumber>
        <cardstartmonth>01</cardstartmonth>
        <cardstartyear>10</cardstartyear>
        <cardexpiremonth>01</cardexpiremonth>
        <cardexpireyear>12</cardexpireyear>
        <cv2>424</cv2>
        <cardholdersname>Joe Bloggs</cardholdersname>
        <cardholdersemail>joe@bloggs.com</cardholdersemail>
        <cardholderaddr1>Address 1</cardholderaddr1>
        <cardholdercity>City</cardholdercity>
        <cardholderstate>State</cardholderstate>
        <cardholderpostcode>Postcode</cardholderpostcode>
        <transactioncurrency>GBP</transactioncurrency>
        <transactionamount>29.00</transactionamount>
        <transactiontax>4.50</transactiontax>
        <shippingcharge>5.00</shippingcharge>
        <secuitems><![CDATA[
            [pd1|sku1|Product 1|10.00|2|20.00]
        ]]></secuitems>
    </transaction>
</request>

Step 8: Continuous Authority

Continuous authority is supported through the API; however, it does not use the advanced functionality of the automated recurring payments feature. The continuous authority API is for users who wish to take full control for their subscription transactions, the CA API system offers you the ability to process CA payments however it is the responsibility of the merchant to regulate the transaction values and frequencies. Please be aware as a rule of thumb the banks expect CA payment to be a predictable transaction amount on a regular or predictable frequency, any deviation from this can be viewed as an abuse of the merchant's CA acquiring account. You must also only ever process a CA transaction on a card provided you have obtained full authorisation and authentication against that card via your normal merchant account, the CA API system covered this by only allowing you to process a manual CA transaction when we have records of a successful authorised transaction to take the card details from.

Below is an example of a request XML string:

<?xml version="1.0"?>
    <request>
        <type>manual_ca</type>
        <authentication>
            <shreference>SH200002</shreference>
            <checkcode>607666</checkcode>
        </authentication>
        <transaction>
            <ca_trannum>10000003</ca_trannum>
            <last_trannum>12345678</last_trannum>
            <amount>10.00</amount>
        </transaction>
    </request>

The required nodes are the "shreference" and "checkcode" to identify the account and the "amount" to know how much to process. Either the "ca_trannum" or the "last_trannum" must be supplied but they do not both need to be supplied together. The "ca_trannum" is for an existing CA reference if one exists, if a CA reference does not yet exist and this is the first CA payment to the card then send us the transaction reference of the previous transaction in the "last_trannum" node. We will then create a CA reference to be stored and used going forward.

The below XML is returned on success:

<?xml version="1.0"?>
    <result>
        <status>OK</status>
        <statustext>Reference: 12345678</statustext>
        <reference>12345678</reference>
        <ca_trannum>10000003</ca_trannum>
        <transactiontime>23:59:59</transactiontime>
        <transactiondate>2005-06-10</transactiondate>
    </result>

The result on failure is the same as a normal transaction apart from the below additional errors:

  • MANUAL_CA_DISALLOWED – The manual CA system must be turned on for individual accounts, please contact support.
  • NO_AMOUNT – No amount has been passed in the XML
  • INVALID_REFERENCE – No valid transaction can be obtained from the "ca_trannum" or the "last_trannum".
  • SUBSCRIPTION_ERROR – There has been an error processing the subscription, please contact support.

Step 9: Transaction Downloads

This feature is provided as an additional reporting tool to advanced integrations into SecureHosting. The feature provides you with the ability to download your transactions in XML format allowing you to parse the data and import it into any custom platform within your control. We advise the following requirements for this feature:

  • eCom Standard or Premium account
  • One-off set up fee of £50 (ex VAT)
  • Good understanding of one or more programming language
  • An understanding of object orientated programming

How does it work?

The transaction data is capture from SecureHosting by calling a URL within your application and reading the response body. Within the URL you call you must pass a series of fields using query string format, the response body will be XML string for your application to parse.

Base URL

The base URL (before the query string) is:

  https://www.secure-server-hosting.com/secutran/transaction_xml.php

Required Fields

Field Name Description Example
shref SecureHosting account number SH212345
checkcode Second level security check code 123456
actpasswd SecureHosting account password Password01
transcsv CSV file setting 1, 2 or 3

Transaction range fields

A transaction range must be supplied in order to return your transaction; you can specify the range either by date or by transaction ID

Field Name Description Example
transfrom Transaction ID range, lower value 12345678
transto Transaction ID range, upper value 87654321
datefrom Transaction date range, lower value 2011-01-01
dateto Transaction date range, upper value 2011-01-31

Optional Fields

In addition to the require fields you can also send in some additional fields to vary the transactions being returned.

Field Name Description Example
page Page listing 1
tranresult Successful or failed transactions 0 (failed) or 1 (successful)

The response

The response you will receive back will always be in XML format and it will always be the within response body. If the request is successful then the XML root node will be called "transactions", however if there has been an error then the root node will be "error".

Response on success

Below is an example response for a successful request:

<?xml version="1.0"?>
    <transactions>
        <fieldstofind>
            <field name="transactiontime"/>
            <field name="transactiondate"/>
            <field name="transactionamount"/>
            <field name="transactioncurrency"/>
            <field name="cardholdersname"/>
            <field name="cardholdersaddr1"/>
            <field name="cardholderpostcode"/>
        </fieldstofind>
        <data>
            <transaction>
                <fields>
                    <transactionid>13374878</transactionid>
                    <transactiondate>2011-05-12</transactiondate>
                    <transactiontime>16:07:10</transactiontime>
                    <transactionamount>5.00</transactionamount>
                    <transactioncurrency>GBP</transactioncurrency>
                    <cardholdersname>Test Tran</cardholdersname>
                    <cardholderpostcode>B77 5DQ</cardholderpostcode>
                </fields>
                <orderitems>
                    <item>
                        <description>87654321</description>
                        <price>5.00</price>
                        <qty>1</qty>
                        <totalprice>5.00</totalprice>
                    </item>
                </orderitems>
            </transaction>
        </data>
    </transactions>

The path" \transactions\fieldstofind" will contain a child node called "field" for every field being requested, the name of the field will be found in the attribute "name". Each transaction being returned will be under the path "\transactions\data\transaction", with a "transaction" node for each individual transaction.

The response will only ever contain 50 transactions, if there are more than 50 within the transaction range then the download feature will use the page listing feature to split the response into pages of 50, you use the field "page" in the request to return different pages.

If the current page you are requesting is not the last page in the range, an additional node called "nexttransaction" will be available as a child of "transactions". If the current page is the last in the range, the "nexttransaction" node will not be returned.

Response on error

Below is an example of an error response:

<?xml version="1.0"?>
    <error>missing or invalid sh reference</error>

The different error messages that can be returned are:

  • missing or invalid sh reference
  • missing or invalid check code
  • no account password
  • invalid sh reference/password combination
  • Csv Download Not Authorised
  • no csv file type supplied
  • invalid transaction range
  • no transaction range

Step 10: 3-D Secure API

What is the 3-D Secure Transaction API

The 3-D Secure API is a method of processing 3-D Secure transactions with SecureHosting while capturing the card details within your website.

How Does It Work?

The way the 3-D Secure API works is your payment system will capture all of the customer's card details in your website then send the details directly from your system to our API interface. The API will then return a HTML page for your system to output to the client browser. This HTML page will redirect the customer to their card issuing bank's page via our platform. When the customer is redirected back to our system, we will perform the transaction with the merchant acquiring bank before instantly redirecting them back to your website.

The reason we have to perform a redirect, unlike the standard transaction API, the nature of 3-D Secure requires the customer to be redirected to their card issuing bank's page for authentication. In order for the SecureHosting system to support this redirect and the transaction, the customer must be redirected to the SecureHosting system between going to and from the card issuing bank's page. The SecureHosting system will attempt to make these redirects appear instant in order to maintain the perspective that the customer's transaction is being processed by your site.

Requirements

As your website will be capturing and handling card details, it will be in scope for PCI:DSS. For information on your website's requirements for PCI:DSS we advise you review the PCI Security Standards website ( https://www.pcisecuritystandards.org/) or contact your Qualified Security Assessor.

Submitting a Transaction

To submit a transaction, you will need to build up the transaction request data, this data is an XML formatted string which contains all the transaction data. The XML string will be used for the value of the POST element "xmldoc".

The XML doc field along with an additional field called "script_location" are then posted to the API interface https://www.secure-server-hosting.com/secutran/3dsecure_api.php. The value of the field "script_location" will be the URL of where we will need to redirect the customer back to after the transaction is complete.

Request Data

Below is an example of an XML request for a standard eCommerce transaction:

<?xml version="1.0"?>
<request>
    <type>transaction</type>
    <authtype>authorise</authtype>
    <authentication>
        <shreference>SH2XXXXX</shreference>
        <checkcode>XXXXXX</checkcode>
    </authentication>
    <transaction>
        <cardnumber>4242424242424242</cardnumber>
        <cardstartmonth>01</cardstartmonth>
        <cardstartyear>04</cardstartyear>
        <cardexpiremonth>01</cardexpiremonth>
        <cardexpireyear>06</cardexpireyear>
        <cv2>424</cv2>
        <cardholdersname>SecureHosting</cardholdersname>
        <cardholdersemail>blackhole@upg.co.uk</cardholdersemail>
        <cardholderaddr1>Address 1</cardholderaddr1>
        <cardholdercity>City</cardholdercity>
        <cardholderstate>State</cardholderstate>
        <cardholderpostcode>Postcode</cardholderpostcode>
        <currency>GBP</currency>
        <transactionamount>34.99</transactionamount>
        <transactiontax>3.50</transactiontax>
        <shippingcharge>1.00</shippingcharge>
        <secuitems><![CDATA[[1129||Laptop|350.00|1|350.00]]]></secuitems>
    </transaction>
</request>

When the customer is returned to your site following a successful transaction, the below data is returned inside the POST header as form fields:

  • status – "OK"
  • reference – 8 digit Integer
  • transactiontime – {00:00:00}
  • transactiondate – {0000-00-00}
  • cardtype – String, varying length
  • cv2avsresult – String, varying length
  • threedsresult – String, varying length
  • threedsenrolment – Sting, 1 character
  • threedsautheitcation – String, 1 character
  • xmlresult – XML string, similar formatted string as the response for the standard API

The below data is returned upon a failed transaction:

  • status – String, varying length
  • statustext – String, varying length
  • threedsresult – String, varying length
  • threedsenrolment – String, 1 character
  • threedsautheitcation – String, 1 character
  • xmlresult – XML string, similar formatted string as the response for the standard API

The 3-D Secure API also supports the "additional" transaction type. Please see the standard transaction API Step 6 of the API Integration Process for more details.

Enrolment Check

As the 3-D Secure API involved redirecting the customer, you can perform a call to the Secure Hosting platform to check the enrolment status of a customer's card before performing the transaction.

This check provides you with the option to check the enrolment status of a card before performing a 3-D Secure transaction, if you decide you do not wish to perform a 3-D Secure transaction you can fall back to the standard API.

This call is made in a similar fashion to a 3D secure API transaction. An XML string is posted to the 3-D Secure API for the enrolment check, the response is XML.

Below is an example of an enrolment check XML string:

<?xml version="1.0"?>
<request>
    <type>3dscheckenrolled</type>
    <authentication>
        <shreference>SH2XXXXX</shreference>
        <checkcode>XXXXXX</checkcode>
    </authentication>
    <transaction>
        <cardnumber>4242424242424242</cardnumber>
        <cardstartmonth>01</cardstartmonth>
        <cardstartyear>04</cardstartyear>
        <cardexpiremonth>01</cardexpiremonth>
        <cardexpireyear>06</cardexpireyear>
        <currency>GBP</currency>
        <transactionamount>34.99</transactionamount>
    </transaction>  
</request>

The response XML is formatted as below:

<?xml version="1.0"?>
<result>
    <status>OK</status>
    <enrolled>Y</enrolled>
</result>

The different possible values for the enrolled status are:

  • Y – The card is enrolled into the scheme
  • N – The card is not yet enrolled by the card issuing bank into the scheme
  • U – We have been unable to determine the enrolment status of the card

The below XML will be returned if there is an error performing the enrolment check:

<?xml version="1.0"?>
<result>
    <status>ERROR</status>
    <statustext>ERROR_DESCRIPTION</statustext>
</result>

The different possible error descriptions that can be returned from the enrolment call are:

  • 3DSECURE_CALL_FAILED – Problem calling the 3-D Secure service
  • 3DSECURE_ERROR – An error was returned from the 3-D Secure check, a further node called reason will contain more details
  • 3DS_NON_MAESTRO – This is an error response which will only be sent for a non-Maestro card when 3-D Secure is set to Maestro only within your account

For a code example for processing a transaction with the 3-D Secure API, please see Appendix J.