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);
}
?>Hosted Payment Page library #2
The following example code shows how to create a payment form to open the Hosted Payment Page in a lightbox style overlay on your website using the Hosted Payment Page library:
<!DOCTYPE html>
<html>
<head>
<!-- Load the Hosted Payment Page library -->
<script src="https://gateway.example.com/sdk/web/v1/js/hostedforms.min.js"></script>
</head>
<body>
<!-- Pay button placeholder -->
<div id="paynow"></div>
<script>
// Create a new Hosted Form object that will render a payment button
// and load the Hosted Payment Page into a modal overlay over this page.
// The request can be provided from your server.
var req = {
merchantID: "100001",
action: "SALE",
type: "1",
currencyCode: "826",
countryCode: "826",
amount: "1001",
orderRef: "Test purchase",
redirectURL: "https://www.merchant.com/payment/",
signature:
"07599ef4cdb2e26cb2bf34a9c65190a7ce82494bc1df144c3bb0d20ee2655d8278dc663b2b0421ef12b8f081e821151bb4c644277c5d65b5523a96539b53b5aa",
};
var data = {
id: "my-payment-form",
url: "https://gateway.example.com/hosted/modal/",
modal: true,
data: req,
submit: {
type: "button",
label: "Pay <i>Now</i>",
},
};
var form = new window.hostedForms.classes.Form("paynow", data);
</script>
</body>
</html>Hosted payment Page Library (using Jquery)
The following example code shows how to create a payment form to open the Hosted Payment Page in a lightbox style overlay on your website using the Hosted Payment Page and jQuery libraries:
<!DOCTYPE html>
<html>
<head>
<!-- Load the jQuery library -->
<script
src="https://code.jquery.com/jquery-3.4.1.min.js"
integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo="
crossorigin="anonymous"
></script>
<!-- Load the Hosted Payment Page library -->
<script src="https://gateway.example.com/sdk/web/v1/js/hostedforms.min.js"></script>
</head>
<body>
<!-- Pay button placeholder -->
<div id="paynow"></div>
<script>
// Create a new Hosted Form object that will render a payment button
// and load the Hosted Payment Page into a modal overlay over this page.
// The request can be provided from your server.
var req = {
merchantID: "100001",
action: "SALE",
type: "1",
currencyCode: "826",
countryCode: "826",
amount: "1001",
orderRef: "Test purchase",
redirectURL: "https://www.merchant.com/payment/",
signature:
"07599ef4cdb2e26cb2bf34a9c65190a7ce82494bc1df144c3bb0d20ee2655d8278dc663b2b0421ef12b8f081e821151bb4c644277c5d65b5523a96539b53b5aa",
};
var data = {
id: "my-payment-form",
url: "https://gateway.example.com/hosted/modal/",
modal: true,
data: req,
submit: {
type: "button",
label: "Pay <i>Now</i>",
},
};
var form = $("#paynow").hostedForm(data);
</script>
</body>
</html>