Table of Contents

  1. Step 1: Redirecting the Customer
  2. Step 2: Building a Payment Page
  3. Step 3: Building a Confirmation Page
  4. Step 4: Building Product Data
  5. Step 5: Securing Your Checkout
  6. Step 6: Requesting Callbacks
  7. Step 7: Continuous Authority
  8. Step 8: PayPal Support

The Hosted Form Integration Process in Detail

The Hosted Form integration will work as the final page of your website’s checkout process; this means the customer only has to be redirected away from your website for as little time as possible. After the customer has completed their basket and entered all the required information into your website, e.g. name and address, the customer is then redirected to the payment page located on the SHP website.

Step 1: Redirecting the Customer

The first step of integrating into the SecureHosting system is to redirect the customer to the payment page hosted on the SecureHosting website. The redirect is performed using a HTML form POST to the generic payment page parser:

<form action="https://www.secure-server-hosting.com/secutran/secuitems.php" method="post">

With this form, the one required field you must include tells our system which payment page to use; as the payment page parser is generic it will not automatically know to grab your payment page. The one required field is called "filename", the value of this field must include your account's SH reference value and the file name of your payment page in the below format. The input field itself is usually a hidden field as it has no relevant value to the customer:

<input type="hidden" name="filename" value="SH200000/payment.html" />

Along with the one required field, you will also want your website to post a series of additional fields from your shopping cart as they allow you to dynamically configure the checkout page:

  • shreference – Your account login reference
  • checkcode – A second unique identifier for the account
  • transactionamount – The total amount to be processed against the card
  • transactioncurrency – The ISO 4217 alpha-3 currency code the transaction is to be processed in, please note, SecureHosting will not perform any currency conversions.
  • shippingcharge –The amount of shipping the customer has been charged, this will not be added to the transaction amount.
  • transactiontax – The amount of tax the customer has been charged, please note, SecureHosting does not perform any tax calculations for you.

If your website's checkout process captures the customer's information before redirecting the customer, the customer's details can be sent in the below fields so they can be captured and stored with the transaction:

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

If you want to send any additional fields to the SecureHosting system with your transaction, you can add them to the form. The field name you use will be the field name our system captures and stores the data in. While you can send as many fields as you require, within reason, the limit on the size of the field value is 255 characters, anything longer will be truncated. You should only send fields to Secure Hosting that are required for your checkout process. All information supplied to Secure Hosting as part of a checkout will be inspected by our Web Application Firewall in order ensure you and your customers are kept as safe as possible while using our service.

Test 1: Customer Redirect

In order to test your redirect form, you must first build your payment page template, detailed within the next section of this document. The reason you must complete the next step before testing is because the redirect is to the payment page, if no payment page has been built and uploaded the SecureHosting account, the parser will return an error.

Once you have built up your redirect form and uploaded your payment page template you can run the first integration test!

To test the redirect, simply submit the redirect form from your website, if your payment page appears with all the transaction and customer data in the page then the test has been successful and you are 50% of the way to completing a basic integration.

Troubleshooting

If your payment page does not appear as expected, then something is wrong.

Error Cause Fix
You must pass a filename to the script. Your redirect form does not contain a "filename" field. Add a field to your redirect form called "filename" with the relevant value.
The file template.html does not exist. The value of the "filename" is incorrectly formatted. The format of the "filename" field is "SH200000/template.html"
The file SH200000/template.html does not exist. Your payment page template has not been uploaded to your account. Upload your payment page template via the File Manager interface within the client control panel.
None of my customer's details appear in the payment page The redirect form is not submitting the customer's data with the correct field names. Correct the field names within the redirect form.
The dynamic fields have not been written into the payment page template correctly. Correct the payment page template to use the syntax "$fieldname" directly in the raw HTML, no server side tags.

Step 2: Building a Payment Page

The second step when integrating your website into the SecureHosting platform is to build a payment page. The payment pages within the SecureHosting platform work on a HTML template basis, this allows the payment pages to be designed, built and styled using well established, standardised formats (HTML, CSS, JavaScript, etc). You upload the HTML templates into your SecureHosting account via the File Manager interface, the template is then used by the generic payment page parser to output a payment page to the customer's browser. For more information about the File Manager interface, please see the File Manager section of the SecureHosting Users Guide.

The filename of your payment page template is not set by the SecureHosting system; you can define your own filename(s) allowing you to optionally have multiple payment pages which allows you to have multiple payment pages for other purposes (files must have either a .html or .htm extension. This is case insensitive). The way our payment page parser knows which payment page to use when you redirect your customer is via the "filename" field in the redirect form, this allows your website to choose which payment page it wishes to use for the customer.

Along with the "filename" field, you can post as many additional fields to your payment page as required to assist with configuring your checkout, or simply pass data to be captured with the transaction. In order to use those fields within the payment page, within the HTML template you would use the "$fieldname" syntax directly in the raw HTML, no service side tags or coding. If a field with the relevant field name has been posted from the redirect form to the payment page, the "$fieldname" text will be replaced with the value of the field supplied. If not field has been supplied then the parser will blank out the "$fieldname" text. As an extension of this, if you want to forward the value of a form field from your redirect form to the transaction, you can use the below syntax to forward individual field values:

<input name="fieldname" value="$fieldname" />

To forward the value behind without it being seen, you would make this a hidden input, to allow the customer to modify the field you can make it a text input. To repopulate drop down or multiple select boxes, we would advise using JavaScript within the head of the page, code similar the below example:

onload = function(){
    var preSelect = new Array( 'field1' =&gt; '$field1', 'field2' =&gt; '$field2' );
    for( var fieldName in preSelect ){
        var selectField = document.getElementsByName( fieldName )[0];
        for( var i = 0; i &lt; selectField.options.length; i++ ){
            if( selectField.options[i].value == preSelect[fieldName] ){
                selectField.selectedIndex = i;
            }
        }
    }
};

We would advise having knowledge of JavaScript or other Object Orientated languages before using this. For further information regarding JavaScript and how to use it, please have a look at W3 Schools tutorial: http://www.w3schools.com/js/.

Within your payment page, in order for it to perform it's required function of capturing the sensitive payment card details and submitting them, you will need to build a HTML form within the template which will submit the transaction information to one of our transaction scripts:

<form action="https://www.secure-server-hosting.com/secutran/transactionsi1.php" method="post">

Please see Appendix B for a list of all transaction scripts.

It is essential that the POST method is used on this form as the SecureHosting transaction scripts will not accept transaction details via any other method.

The minimum, required fields that this form must post are:

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

The below fields are not strictly required, however we strongly advise always submitting them:

- transactiontax
- shippingcharge
- cardstartmonth (2 digit month)
- cardstartyear (2 digit year)
- cardholdersname
- cardholdersemail (required for confirmation emails if you are using them)
- cardholderaddr1 \*
- cardholderaddr2
- cardholdercity
- cardholderstate
- cardholderpostcode \*
- cardholdercountry
- cardholdertelephonenumber

* Required for the card issuing bank's Address Verification System.

Any additional fields you submit will be captured and stored using the field name they were submitted with.

As the payment pages work from a HTML template which is built by you, you've got the opportunity to design and style the page how you like; you can include your own CSS files, images and even external JavaScript files. The way to do this, in order to prevent client browser security warnings, you can upload the images, CSS and JavaScript file into your SecureHosting account through the File Manager. You can then address the files using the below path and replacing the account SH reference and file name:

https://www.secure-server-hosting.com/secutran/secureforms/sh200000/image.gif

Test 2: Submit a Payment

Once you are successfully redirecting the customer to the payment page, the next step is to submit a transaction form the payment page. To perform this test, once you've been redirected to the payment page you can complete the payment form with one of the test card numbers found within Appendix C.

After submitting the transaction, have a look at the new transaction within the client control panel. If all the transaction fields are displayed correctly within the control panel then you have successfully completed a basic integration into the SecureHosting system! Congratulations!

After you have completed the basic integration, there are further features of the platform which you can optionally integrate into.

Troubleshooting

If the payment details do not appear in the client control panel or you receive the following error messages, something is wrong:

Error Cause Fix
SH reference not supplied.
SH reference field empty. The payment form is not submitting the account SH reference. Make sure the payment form contains an input field called "shreference" which contains the account SH reference.
Checkcode not supplied.
Checkcode field empty. The payment form is not submitting the account check code. Make sure the payment form contains an input field called "checkcode" which contains the account check code.
Merchant Implementation Error - Incorrect client SH reference and checkcode combination The SH reference and checkcode submitted with the transaction are not correct for the account. Make sure the SH reference and check code values are correct.
Merchant Implementation Error - Invalid Transaction Amount. The transaction amount is not of a valid format. Ensure the transaction amount value submitted is formatted as a currency amount with no symbol, for example 10.00.

Step 3: Building a Confirmation Page

After a transaction has been processed by the SecureHosting system, it does not automatically redirect customers back to your website, it outputs a confirmation page. The default confirmation page outputted by the SecureHosting system looks like this:

Screenshot

Using the Confirmation/Error Page Settings within the SecureHosting client login system, you are able to insert your own company logo along with your own text at either the top or bottom of this page.

Alternatively you can build and design your own confirmation page using the same HTML template style as the payment page, this allows you to style the confirmation page to match the design style of your website or perform required actions like redirecting the customer back to your site. Unlike the payment pages, the file name of the confirmation page is set by the SecureHosting system; the file name must be "htmlgood.html". This ensures the SecureHosting system can adequately identify a customised confirmation page within your account.

All the fields submitted from your payment form will be available within the confirmation page using the "$fieldname" syntax allowing you to display the customer's details on the confirmation page. In addition to the field submitted by your payment form, the below fields are generated by our system:

- $authcode – Auth code returned by the bank
- $cv2avsresult – Result of the CV2 and AVS checks
- $trancdtp – Card type identified from the card number
- $trannum – The transaction ID of the customer's transaction
- $transactiondate – The date of the transaction formatted as yyyy-mm-dd
- $transactiontime – The time of the transaction formatted as hh:mm:ss

In addition to building a confirmation page, there is also an error page within the platform which can be designed and styled in the same fashion as the confirmation page. The default transaction error page looks like this:

Screenshot

If you wish to upload your own transaction error page, the file name for the HTML template is "htmlbad.html". The system generated fields within the error page are:

- $tranerrdesc – A description of the type of error (e.g. Payment Failed)
- $tranerrdetail – Details of the error where applicable (e.g. Card Declined)
- $posted\_fields – A collection of hidden HTML field fields, a hidden field for each form field posted from the payment form.

When the customer has a transaction error, after displaying the relevant error message to the customer, you may wish to redirect them back to their payment page in order to retry their transaction. This can be achieved by building a HTML form within the error page that will rebuild the checkout page for them. The form in the error page will post the customer back to the payment page parser, you can use the "$posted_fields" variable to build up the form fields and add in your own submit button:

<form action="https://www.seure-server-hosting.com/secutran/secuitems.php" method="post">
    $posted_fields
    <input type="submit" value="Go Back" />
</form>

In order to ensure the correct file name field value is populated into the return form, you need to forward the "filename" field value through the payment form otherwise the return form will not be able to specify the payment page template for the payment page parser. To forward the "filename" value in the payment form, you must use the below hidden input field:

<input type="hidden" name="filename" value="$backfile" />

Step 4: Building Product Data

With your customer's transaction, you will most likely need the SecureHosting system to store what the transaction was for so you can review your transactions. To do this, the SecureHosting system has a product string format which allows you to build up a list of products to send with the transaction. The name of the product string is the "secutiems" product string and it's built up using the below format:

[pd1|sku1|Product 1: size medium|10.00|2|20.00][pd2|sku2|Product 2: BOGOF|15.00|2|15.00]

Each product within the string is encased in square brackets, "[]". Within each product there are 6 fields separated by a single pipe symbol "|". The different fields that must be present within the product and the order in which they are assembled is:

1. Product code – String, optional, leave blank if not required.
2. SKU Code – String, optional, leave blank is not required.
3. Product description – String, required.
4. Unit price – Currency, required, format 0.00.
5. Quantity – Integer, required.
6. Line total – Currency, required, format 0.00.

Each product must have 6 fields, even if the first two fields are blank, if there are not 6 fields, the product data will be rejected by the SecureHosting system. To supply multiple product simple append a new product, inside its own set of square brackets on the end of the existing products to build 1 long string which must be submitted in a field called "secuitems".

To display the products on your payment, confirmation or transaction error pages, you use some non-standard HTML tags unique to the SecureHosting platform. You have a loop start tag and a loop end tag:

<loopstart:shoplst>
<!—Some HTML -->
<loopend>

For each product in the product string, our system will repeat the code inside the loop for each product allowing you to visually display each product the customer has purchased. Between the loopstart and loopend tags, there are also 6 additional fields which can be included into the HTML code, each of which will be replaced with relevant value from that product:

- $itemcode – Product code
- $itemskew – SKU code
- $itemdesc – Product description
- $itempric – Unit price
- $itemquan – Quantity
- $itemtota – Line total

Step 5: Securing Your Checkout

In order to secure your checkout from being modified, the SecureHosting system has a feature called Advanced Secuitems Security.

What is the Advanced Secuitems Security System?

The Advanced Secuitems Security System allows merchants to secure their checkout against on-the-fly, inline modifications while the customer has been redirected to our site.

How Does It Work?

The way the security system works is be generating a unique hashed value using a combination of the fields you wish to secure and a secure pass phrase. This unique hash is then added to the redirect and payment forms which process the payment. If the customer attempts to modify one of the now protected fields, our system will identify this and prevent the customer from submitting their payment.

Requirements

As the integration for this system requires development to your shopping cart or other type of payment system, you will need to be a capable developer of the language your site/system is written in (e.g. Php, ASP.NET).

Advanced Secuitems Setup

Before you can start integrating the Advanced Secuitems Security System into your site, you first need to configure and activate it from within the client control Panel. Please note: do not activate the security system on a live site, to do so will prevent all customers from making a payment until your integration has been successfully completed. We advise performing this integration either before going live or on a test account.

The configuration settings for the Advanced Secuitems Security System are located within the Advanced Settings page of the client control panel. Below is a description of each of the setting:-

Activate advanced secuitems security

This tick box setting turns the security system on or off, check the box to turn it on.

List of fields to be encrypted

Our system cannot assume the fields it's being asked to protect, here you must define the list of fields by entering them in the form of a comma separated list (no spaces). You do not need to include the "secuitems" product string as this is included by default.

A phrase to be used to further encrypt your data sent through secuitems

In addition to the fields being protected, we also use a pass phrase, this is defined here. The phrase must be between 6 and 9 characters long.

The full URL referrer of your shopping cart

When generating the unique hash, your system makes a call to our system; this field is used by our system to ensure the call to our system comes from your system. You must define the referrer URL for the call from your system. This must include the protocol as part of the URL ("http://").

Generating the Unique Hash

Within the final stage(s) of your shopping cart/payment system you will need to make a call to the SecureHosting platform in order to generate the unique hash to be added to the checkout. The call will be made to the script:

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

The fields that need to be posted are:

- shreference – The account SH reference number
- secuitems – The SecureHosting secuitems product string
- secuphrase – The additional phrase used generate the unique hash
- Any additional fields are added to the posted fields using the same field name as they would be submitted under.

The response body of the call to our system with either contain one of the error messages listed below or it will be formatted like this:

<input type="hidden" id="secuString" name="secuString" value="9c84f49209fe9cdcb3efbac2dd2c23c8" />

This hidden form field is then to be added to your redirect form when redirecting the customer to your payment page on our server.

For some example code to call the SecureHosting system to generate a unique hash, please see Appendix H.

Payment Page

The template driven payment page will need to have the following hidden form field element adding to its form. Please note, the below field names are case sensitive:

<input type="hidden" id="secuString" name="secuString" value="$secuString" />

Error Responses

Here is a table of the possible error responses that can be received when generating the unique hash and what they mean:

Error Message What it means
SH Reference value not passed The shreference has not been supplied
Secuitems value not passed The secuitems product string has not been supplied
Advanced Secuitems not activated in Merchant Administration Area. The Advanced Secuitems Security System has not been activated within the client control panel
Advanced Secuitems Secure Phrase does not match that set in Merchant Administration Area. The additional phrase supplied with the request does not match the phrase configured within the client control panel
Referral Check Failed The referrer of the request does not match the URL configured within the client control panel
Value for {field} set in account area but not posted. A one of the fields configured within the client control panel is missing from the request
An error has occurred. Please contact Support An error in the process of generating the unique hash has occurred

Step 6: Requesting Callbacks

What are callbacks?

Callbacks from the SecureHosting platform are requests from our servers to your server(s) to notify your system that we've processed a transaction. These requests are independent of the customer's client browser session and do not involve a redirect. Typical uses of the callbacks would be to update an order stored within your shopping cart/payment system to mark it as complete and to potentially update your stock management.

Requirements

As the integration for this system requires development to your shopping cart or other type of payment system, you will need to be a capable developer of the language your site/system is written in (e.g. Php, ASP.NET).

Requesting a Callback

To request a callback from the SecureHosting system, you only need to supply 2 additional fields with the transaction, "callbackurl" and "callbackdata". With these two fields, our system will be able to build up a query string of data and send the data to your payment system via a HTTP GET request.

The hidden field "callbackurl" that needs to be added to your payment form should contain the path to the script within your system where you want us to send the data. Please note: this path should contain the path to the script only, no query strings.

The hidden field "callbackdata" contains a name value pair string of data, each element of the string should be separated by a pipe symbol "|":

field1|value1|field2|value2|field3|value3

If you want to return data entered by the customer from within the payment form, you can use the "#fieldname" syntax:

cardholdersname|#cardholdersname|cardholdersemail|#cardholdersemail

If you are generating the value for the callback fields from your website and sending them to SecureHosting when redirecting the customer, you will need to add the below hidden form fields to your payment form:

<input type="hidden" name="callbackurl" id="callbackurl" value="$callbackurl" />
<input type="hidden" name="callbackdata" id="callbackdata" value="$callbackdata" />

Receiving a Callback

When our system makes the callback to your system, it will typically happen around 2 minutes after the transaction has been processed. The time delay happens because callbacks are processed by an automated task within SecureHosting rather than processing the callback as part of the transaction process. The reason for not processing the callback as part of the transaction process is to prevent the customer from waiting longer than necessary to see a confirmation page.

When the callback request calls your script, it will pass all the fields you've requested inside the callback data field along with a series of additional fields about the transaction. If the transaction is successful, you will receive the below fields:

- transactionnumber – Integer value, 8 digits long.
- transactiontime – DateTime format (yyyy-mm-dd hh:mm:ss)
- cv2avsresult – String
- upgcardtype – String
- upgauthcode – Alphanumeric

If the transaction has failed, you will expect to receive these fields:

- transactionnumber – Value of &quot;-1&quot; for a failed transaction
- transactiontime – DateTime format (yyyy-mm-dd hh:mm:ss)
- failurereason – String

The field "transactionnumber" is present in both successful and failed transactions, however you can use this field as an indication whether the transaction was successful or not. If the transaction has failed, the value will always be "-1", if the transaction is successful, the transaction number will be an 8 digit integer number.

When your script has completed all required actions, we advise outputting the work "success" or something similar as this response is captured by our servers and becomes visible from with the client control panel inside the transaction. This method of capturing the response from your script also allows you to output error messages should something go wrong in your script.

When your script has completed, you need to ensure your web server outputs the standard HTTP 200 response code as our system uses the response code to identify the a callback has been successful or not. If we receive a HTTP 200 response, we will consider the callback successful. If we do not receive a HTTP 200 response we will consider the callback as failed and will keep trying the callback repeatedly for up to 24 hours after the transaction. If we have not received a successful HTTP 200 response after 24 hours, we will stop attempting the callback all together. If we receive a HTTP 301 or 302 response (redirect), our system will not follow the redirect, we will also not retry the callback.

Additional Fields

There are a certain number of additional fields that can be requested with the callback. The following fields are requested by adding the extra fields to the callback data field:

- IP Country – "IPCountry #IPCountry"
- Bin Bank – "BinBank #BinBank"

The below fields can be requested by activating the relevant configuration settings within the Advanced Settings page of the client control panel:

  • BIN number (first 6 digits of the card number) – The BIN number can be returned in the callback by specifying a field name within the client control panel. If a field name has not been specified we will not return the BIN number.
  • Encrypted PAN – A one way encrypted version of the card number can be returned in the callback by entering a field name within the client control panel. If a field name has not been specified, we will not return the encrypted card number. The encrypted card number can also be optionally salted by entering a salt value.
  • 3-D Secure Response – If you're account is using 3-D Secure, you may wish to know the 3-D Secure response returned by the card scheme and card issuing bank. By ticking the box in the client control panel, our system will add the enrolment value returned by the card scheme to the callback inside the field "enrolmentresponse". If the enrolment response was a "Y", you will also receive an additional field called "authenticationresponse" with the authentication response returned by the card issuing bank.

Verifying the Callback

If you wish to add additional security to ensure the callback being received is from the SecureHosting platform, there are two checks that can be implemented. The first check is that the referrer of the call is

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

A more advanced method of verifying the callback is to use the shared secret system. The shared secret system works by adding a hashed value to the callback which can only be created by knowing how the field was created along with having the required values stored at your end. To activate the shared secret validation, you just enter a shared secret value into the Advanced Settings page of the client control panel. Our system will use the value provided to salt the start and end of the transaction reference number, we will then SHA-1 encrypt the resulting string and add the encrypted value to the callback inside a field called "verify".

Step 7: Continuous Authority

Continuous Authority (CA), also referred to as recurring transactions, allows the merchant to automatically bill customers' cards on a regular basis for a fixed amount and for a predefined period. Typical applications would be for magazine subscriptions, web hosting payments or membership websites.

What are the limitations?

  • You will need to set up a special continuous authority merchant account with your bank in order to be able to take recurring payments. We can assist with this if you have any problems.
  • It is not possible to use Maestro cards for recurring payments. Check with your bank which cards are compatible with continuous authority.
  • The value of the recurring payment is normally a fixed amount.
  • The maximum period between two payments cannot be longer than 12 months.
  • You can only process a single subscription at a time.
  • Your SecureHosting account must be configured for online card processing using our Monek payment gateway.
  • Please contact us to enable the continuous authority feature for your SecureHosting account.

Overview of Continuous Authority

With the SecureHosting CA feature you can offer subscribers a trial period, special introductory rates, and a regular standard rate. Subscribers are billed automatically according to the terms you specify.

Adding a new subscriber

There are four methods of adding a new subscriber:-

  1. By posting a transaction from your website, referring to a predefined subscription option.
  2. By posting a transaction from your website, creating an "On-the-fly" subscription option, created at the point of a transaction.
  3. Convert an existing customer into a subscriber.
  4. Manually enter a new subscriber.

Details of fields/form actions required when posting a new subscription sign-up

The following fields are used whether the subscriber is to be set up using a predefined subscription option or "on-the-fly".

Form action:

<form action="https://www.secure-server-hosting.com/secutran/transactionsb1.php" method="POST">

Required Fields:

- shreference
- checkcode
- transactionamount
- transactioncurrency
- cardnumber
- cardexpirymonth
- cardexpiryyear

Optional Fields:

- transactiontax
- shipingcharge
- cardstartmonth
- cardstartyear
- cardholdersname
- cardholdersemail
- cardholderaddr1
- cardholderaddr2
- cardholdercity
- cardholderstate
- cardholderpostcode
- cardholdercountry
- cardholdertelephonenumber

Testing phase

When placing test transactions, use the form action below instead:-

<form action="https://test.secure-server-hosting.com/secutran/transactionsb1.php" method="POST">

Enter a new subscriber using one of the methods below.

In order to test a full subscription right through to its natural expiry, click the "Schedule Now" button when viewing the subscriber payment detail in your account. This option will only appear if you have entered subscribers via the test URL.

Method 1: Adding a subscriber using a predefined subscription

A subscription template will fist need to be configured in your account before you can set up subscribers using predefined subscriptions.

You will see a menu option in your account named "Manage predefined subscriptions" within the "Settings" tab. Click on this to view a list of any existing subscription templates.

Setting Description Example Value
Subscription reference This is the unique reference for the subscription template monthlysub
Subscription name This is the name of the subscription which will be displayed in the customer and merchant emails, transaction confirmation page etc. Monthly Subscription
Subscription description The description to be displayed in the customer and merchant emails, transaction confirmation page etc. 12 months' access to our exclusive journal.
Subscription period The time period between recurring payments. Must be consistent within a single subscription package, ie. It is not possible to mix months with days in one subscription option. Year, months, weeks, days.
Introductory rate 1 Initial trial period cost. Leave blank if not required, or enter "0" for free trial.
Introductory rate 2 As above, but allows a secondary trial rate to follow on from the first. If used, introductory rate 1 must also contain values. Leave all fields blank if not required.
Setting Description Example Value
Standard rate Enter the amount for this subscription at full, normal rate. In the "To be billed every" box enter the period length, i.e. The period between recurring transactions e.g. 1 month.In the "for: payments" box enter the subscription cycle value e.g. 12 (the subscription is for 12 months) 20.00
Number of cycles at standard rate The life of the subscription. This subscription will automatically end after 12 months. To make a subscription run indefinitely enter "0" in this field or leave blank. 1
Should failed payments be retried? Option to define whether payments are retried following failure.
Contact Note The merchant's contact details and address etc. which will be displayed in the customer login area where they can view and manage their subscription. Monek Limited, City House, Davidson Road, Lichfield, WS14 9DZ. Tel: 0345 269 6645
Subscription Currency The currency for all payments for this subscription option. Please note that you must have multi-currency merchant numbers in order to use currencies other than GBP. GBP
Should customers be able to cancel their own subscription? Allows the customer control to cancel their subscription prior to normal expiry.
What is the minimum subscription period This is only relevant if above option is enabled. It provides an override for the above option, in that you can set a minimum period (in days) during which cancellation by the customer is not possible. 180
Setting Description Example Value
From address The email address that the confirmation email is to appear to be from. sales@mycompany.com
Reply-to address The email address to which emails will be sent if the customer replies. support@mycompany.com
Customer emails Customer sign-up Customer details updated Customer scheduled payment notification Customer successful payment notification Customer payment failed notification Customer payment cancelled notification A series of email templates covering various scenarios. If not required leave email content blank. Email sent to the customer following sign-up. Email sent if customer changes their credit card details. Email to warn the customer of an impending payment. Email sent following successful payment Email sent if payment fails. Confirmation of the customer's cancellation.
Merchant emails Corresponding emails sent to you following each scenario.

Placing a transaction with a predefined subscription option

When placing the transaction, you will need to add a field to the form called "subscription", the value of which needs to be the value of the unique subscription reference configured against the subscription template. Please note, you cannot set up a subscription using the "default" subscription template as the subscription template settings are reserved for "on-the-fly" subscriptions.

Method 2: Adding a subscriber using "on-the-fly" subscriptions

To post an on-the-fly subscription sign-up there are several additional fields for which values will need to be presented with the transaction:-

Field Name Description Example Data
subscription This is the subscription code and description that will be displayed to the customer for the subscription. monthlysub
shrecur_trial1 This would create a 3 month free trial for the subscription, occurring only once. 3
(period length period type period cycle
shrecur_trial2 This would allow the fourth month of the subscription to be given at a reduced rate of £10. 1
shrecur_rate This is the full subscription after the trial period. In this case a monthly subscription recurring for the remainder of the 12 months subscription period. This subscription will terminate after 12 months. 1
sh_recur Life of subscription. This subscription will automatically end after 12 months. To make a subscription run indefinitely enter "0" in this field. 1
sh_retry This is the length of time to wait before retrying a failed subscription payment. (In number of days). If no retry is required, enter "0" in this field. 5

Notes:

  1. Available period types are year (Y), month (M), week (W), day (D)
  2. All above fields are compulsory except for "trial1" and "trial2".

Method 3: Converting an existing customer into a subscriber

Within your account, go to view an existing customer's payment details. Click the "Create subscription from this transaction" button. A page will be displayed showing any predefined subscription options, or you can create a new subscription option for this subscriber.

Method 4: Manually enter a new subscriber

Within your account, go to "Place Manual Transaction" within the "Transactions" menu option. Select a predefined subscription and then a date for the first payment to be taken.

Callbacks

Callbacks are supported through the recurring payments system when subscribers are set up from a posted transaction. For information on requesting callbacks, please see Step 6: Requesting Callbacks.

When a callback is triggered from our system, you will receive all the standard callback fields, you will also receive 2 additional fields:

  • subscription – The subscription reference
  • sh_reason – The reason for the callback

The different possible reasons for subscription callbacks are:

  • success
  • payment_failed

Step 8: PayPal Support

Setting Up PayPal

We have prepared detailed instructions to help you integrate your PayPal Merchant Account with your SecureHosting eCom package.

These instructions are clear and straightforward, however, there are a number of important steps which you must follow so that the service runs smoothly so please take care and ensure you follow all steps, as outlined:

  1. Create a PayPal account
  2. Confirm your email address with PayPal
  3. Verify your PayPal account
  4. Request API credentials and create an API signature
  5. Request PayPal functionality is turned on in your account
  6. Logon to http:// securehosting.com/
  7. In the user log in area enter your client login and password
  8. From the home page select "Online Processing > PayPal Settings"
  9. Fill in the details supplied to you by PayPal:
  10. PayPal Username
  11. PayPal Password
  12. PayPal API Key
  13. Make PayPal Active on your account by selecting "Yes" (you can use this option in the future should you wish to disable the service at any time).
  14. Press "Submit above details"

Configure Your Website

To configure your website to be able to process PayPal transactions, having completed steps 1 and 2 of the Hosted Form integration, all you need to do is change the redirect form action from:

<form action="https://www.secure-server-hosting.com/secutran/secuitems.php" method="post">

To:

<form action="https://www.secure-server-hosting.com/secutran/paypal.php" method="post">

You will also need to ensure your redirect form contains the following fields on to of any other fields you wish to send:

  • shreference
  • checkcode
  • transactionamount
  • transactioncurrency

The value of the transaction currency must be the ISO 4217 Alpha-3 currency code for the desired currency. Please see Appendix L for a list of currencies supported by PayPal.

Additional considerations

Some additional consideration must be made when integrating PayPal, if you wish to submit product data to PayPal, you must ensure that product totals calculated from the product string, and the shipping charge (if supplied) add up to the transaction total. If these values do not add up, PayPal will not allow you to create your checkout. If you do not send product data with your order, the order will still be processed.

For more information on the product string, please see Step 4: Building Product Data.

Customising the New PayPal Templates

With the PayPal supported Hosted Form solution, when the customer checks out through PayPal the customer journey is a little different. After being redirected from your website, the customer is presented with the option of paying with PayPal or a normal card transaction, this option page is the first customisable page on the SecureHosting website. The customer selects PayPal and goes to the PayPal website, when they come back to the SecureHosting website and are then asked to click a button to confirm the payment. The confirm page is the second customisable page on the SecureHosting website.

Screenshot

The two pages can be customised by uploading correctly named HTML templates to your SecureHosting account via the File Manager interface.

The two HTML template file names are:

  1. paypal_option.html
  2. paypal_confirm.html

You can download copies of our default templates by clicking on the file names above.

In each of the two templates, you must include the text "$paypalbutton" in order for the SecureHosting System to insert a form which will handle the process.

In the PayPal option page, you can use the below code to build a form to give the customer the option to choose your normal checkout method:

<form action="https://www.secure-server-hosting.com/secutran/secuitems.php" method="post">
    $postedfields
    <input type="submit" value="Credit Card Payment" />
</form>

Alternatively you can actually build your payment form straight into the PayPal option page.

Once the PayPal transaction has been completed by the customer, the SecureHosting system will either use the same confirmation page as your normal card transaction method, or if you have uploaded the following PayPal specific templates, the system will use these templates instead:

  1. paypal_good.html
  2. paypal_bad.html

The functionality of these templates is the same as the normal confirmation and error pages, the existence of these templates simply allows you have PayPal specific confirmation or error templates.

Additional Data

In order to supply additional checkout information with a PayPal transaction, you must include the additional fields in the redirect form. You can supply the customer name and address details inside the various cardholder fields associated with a card transaction, the SecureHosting system will capture the address supplied by your site as the customer's address but it will also capture all information, including the customer information supplied by PayPal. You will be able to see all information about the transaction within the client control panel.

You can also use callbacks with PayPal for more information please see Step 6.