Guides
Hosted Integration

Hosted Integration

The hosted integration method makes it easy to add secure payment processing to your e-commerce business, using our hosted payment pages (HPP). You can use this method if you do not want to collect and store cardholder data.

The hosted integration method works by redirecting the customer to our gateway’s hosted payment page, which will collect the customer’s payment details and process the payment before redirecting the customer back to a page on your website, letting you know the payment outcome. This allows you the quickest path to integrating with the gateway.

The standard hosted payment page is designed to be shown in a lightbox over your website and styled with logos and colours to match. Alternatively, you can arrange for fully customised hosted payment pages to be produced that can match your website’s style and layout. These fully customised pages are usually provided using a browser redirect, displaying full-page in the browser, or can be displayed embedded in an iframe on your website.

For greater control over the customisation of the payment page, our gateway offers the use of hosted payment fields, where only the individual input fields collecting the sensitive cardholder data are hosted by the gateway while the remainder of the payment form is provided by your website. These hosted payment fields fit seamlessly into your payment page and can be styled to match your payment fields. When your payment form is submitted to your server, the gateway will submit a payment token representing the sensitive card data it collected and your webserver can then use the direct integration to process the payment without ever being in contact with the collected cardholder data.

Sale Transaction example

The following example PHP code shows how to send a SALE transaction:

 <?php
 // Signature key entered on MMS. The demo account is fixed to this value,
 $key = 'Circle4Take40Idea';
 
 // Gateway URL
 $url = 'https://gateway.example.com/hosted/';
 
 if (!isset($_POST['responseCode'])) {
    // Send request to gateway
    // Request
    $req = array(
    'merchantID' => '100001',
    'action' => 'SALE',
    'type' => 1,
    'countryCode' => 826,
    'currencyCode' => 826,
    'amount' => 1001,
    'orderRef' => 'Test purchase',
    'transactionUnique' => uniqid(),
    'redirectURL' => ($_SERVER['HTTPS'] == 'on' ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
 );
 
 // Create the signature using the function called below.
 $req['signature'] = createSignature($req, $key);
 
 echo '<form action="' . htmlentities($url) . '" method="post">' . PHP_EOL;
 
 foreach ($req as $field => $value) {
    echo ' <input type="hidden" name="' . $field . '" value="' . htmlentities($value) . '">' . PHP_EOL;
 }
 
 echo ' <input type="submit" value="Pay Now">' . PHP_EOL;
 echo '</form>' . PHP_EOL;
 
 // Check the return signature
 if (!$signature || $signature !== createSignature($res, $key)) {
    // You should exit gracefully
    die('Sorry, the signature check failed');
 }
 // Check the response code
 if ($res['responseCode'] === "0") {
 
    echo "<p>Thank you for your payment.</p>";
 
 }else{
 
    echo "<p>Failed to take payment: " . htmlentities($res['responseMessage']) . "</p>";
 
 }
 
 }
 
 // Function to create a message signature
 
 function createSignature(array $data, $key) {
    // Sort by field name
    ksort($data);
 
    // Create the URL encoded signature string
    $ret = http_build_query($data, '', '&');
 
    // Normalise all line endings (CRNL|NLCR|NL|CR) to just NL (%0A)
    $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret);
 
    // Hash the signature string and the key together
    return hash('SHA512', $ret . $key);
 }
 
 ?>
Last updated on 18 September 2023