
Get up and running and start taking card payments online, by exploring our integration guides and documentation for developers; including libraries, keys and other integration tools.
Get Started
The Hosted Payment Page (HPP) is our PCI DSS v3.2 compliant redirect solution, allowing you capture card data without having to worry about the PCI overhead associated with a traditional API integration.
Using the HPP along with our SDKs and libraries means that you can have a secure payment form setup in your application/website in minutes. The library handles the opening, display and response of the HPP on desktop, tablet, mobile or in-app with minimal configuration required. If you are accepting card details via the HPP only, you can attest to your PCI compliance by completing the short PCI DSS Self-Assessment Questionnaire (SAQ) A.
We'll start by setting up the server-side code, if you are using one of our SDKs we'll create our request object and convert it to JSON. Your application code can then pass the JSON string to the client-side library. If you're integrating directly, your application can build the HTTP POST itself.
Note: Your shared secret should always remain on the server-side and must not be exposed to the public.
// configure client, request and HPP settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setAccountId("internet");
config.setSharedSecret("secret");
config.setServiceUrl("https://pay.sandbox.realexpayments.com/pay");
HostedPaymentConfig hostedPaymentConfig = new HostedPaymentConfig();
hostedPaymentConfig.setVersion(HppVersion.Version2);
config.setHostedPaymentConfig(hostedPaymentConfig);
// Add 3D Secure 2 Mandatory and Recommended Fields
HostedPaymentData hostedPaymentData = new HostedPaymentData();
hostedPaymentData.setCustomerEmail("james.mason@example.com");
hostedPaymentData.setCustomerPhoneMobile("44|07123456789");
hostedPaymentData.setAddressesMatch(false);
Address billingAddress = new Address();
billingAddress.setStreetAddress1("Flat 123");
billingAddress.setStreetAddress2("House 456");
billingAddress.setStreetAddress3("Unit 4");
billingAddress.setCity("Halifax");
billingAddress.setPostalCode("W5 9HR");
billingAddress.setCountry("826");
Address shippingAddress = new Address();
shippingAddress.setStreetAddress1("Apartment 825");
shippingAddress.setStreetAddress2("Complex 741");
shippingAddress.setStreetAddress3("House 963");
shippingAddress.setCity("Chicago");
shippingAddress.setState("IL");
shippingAddress.setPostalCode("50001");
shippingAddress.setCountry("840");
HostedService service = new HostedService(config);
try {
String hppJson = service.charge(new BigDecimal("19.99"))
.withCurrency("EUR")
.withHostedPaymentData(hostedPaymentData)
.withAddress(billingAddress, AddressType.Billing)
.withAddress(shippingAddress, AddressType.Shipping)
.serialize();
// TODO: pass the HPP request JSON to the JavaScript, iOS or Android Library
} catch (ApiException exce) {
// TODO: Add your error handling here
}
<?php
require_once('vendor/autoload.php');
use GlobalPayments\Api\Entities\Address;
use GlobalPayments\Api\Entities\Enums\AddressType;
use GlobalPayments\Api\ServiceConfigs\Gateways\GpEcomConfig;
use GlobalPayments\Api\HostedPaymentConfig;
use GlobalPayments\Api\Entities\HostedPaymentData;
use GlobalPayments\Api\Entities\Enums\HppVersion;
use GlobalPayments\Api\Entities\Exceptions\ApiException;
use GlobalPayments\Api\Services\HostedService;
// configure client, request and HPP settings
$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "internet";
$config->sharedSecret = "secret";
$config->serviceUrl = "https://pay.sandbox.realexpayments.com/pay";
$config->hostedPaymentConfig = new HostedPaymentConfig();
$config->hostedPaymentConfig->version = HppVersion::VERSION_2;
$service = new HostedService($config);
// Add 3D Secure 2 Mandatory and Recommended Fields
$hostedPaymentData = new HostedPaymentData();
$hostedPaymentData->customerEmail = "james.mason@example.com";
$hostedPaymentData->customerPhoneMobile = "44|07123456789";
$hostedPaymentData->addressesMatch = false;
$billingAddress = new Address();
$billingAddress->streetAddress1 = "Flat 123";
$billingAddress->streetAddress2 = "House 456";
$billingAddress->streetAddress3 = "Unit 4";
$billingAddress->city = "Halifax";
$billingAddress->postalCode = "W5 9HR";
$billingAddress->country = "826";
$shippingAddress = new Address();
$shippingAddress->streetAddress1 = "Apartment 825";
$shippingAddress->streetAddress2 = "Complex 741";
$shippingAddress->streetAddress3 = "House 963";
$shippingAddress->city = "Chicago";
$shippingAddress->state = "IL";
$shippingAddress->postalCode = "50001";
$shippingAddress->country = "840";
try {
$hppJson = $service->charge(19.99)
->withCurrency("EUR")
->withHostedPaymentData($hostedPaymentData)
->withAddress($billingAddress, AddressType::BILLING)
->withAddress($shippingAddress, AddressType::SHIPPING)
->serialize();
// TODO: pass the HPP JSON to the client-side
} catch (ApiException $e) {
// TODO: Add your error handling here
}
// configure client, request and HPP settings
var service = new HostedService(new GpEcomConfig
{
MerchantId = "MerchantId",
AccountId = "internet",
SharedSecret = "secret",
ServiceUrl = "https://pay.sandbox.realexpayments.com/pay",
HostedPaymentConfig = new HostedPaymentConfig
{
Version = "2"
}
});
// Add 3D Secure 2 Mandatory and Recommended Fields
var hostedPaymentData = new HostedPaymentData
{
CustomerEmail = "james.mason@example.com",
CustomerPhoneMobile = "44|07123456789",
AddressesMatch = false
};
var billingAddress = new Address
{
StreetAddress1 = "Flat 123",
StreetAddress2 = "House 456",
StreetAddress3 = "Unit 4",
City = "Halifax",
PostalCode = "W5 9HR",
Country = "826"
};
var shippingAddress = new Address
{
StreetAddress1 = "Apartment 825",
StreetAddress2 = "Complex 741",
StreetAddress3 = "House 963",
City = "Chicago",
State = "IL",
PostalCode = "50001",
Country = "840",
};
try
{
var hppJson = service.Charge(19.99m)
.WithCurrency("EUR")
.WithHostedPaymentData(hostedPaymentData)
.WithAddress(billingAddress, AddressType.Billing)
.WithAddress(shippingAddress, AddressType.Shipping)
.Serialize();
// TODO: pass the HPP request JSON to the JavaScript, iOS or Android Library
}
catch (ApiException exce)
{
// TODO: Add your error handling here
}
<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
<input type="hidden" name="TIMESTAMP" value="20180613110737">
<input type="hidden" name="MERCHANT_ID" value="MerchantId">
<input type="hidden" name="ACCOUNT" value="internet">
<input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
<input type="hidden" name="AMOUNT" value="1999">
<input type="hidden" name="CURRENCY" value="EUR">
<input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
<input type="hidden" name="COMMENT1" value="Mobile Channel">
<input type="hidden" name="HPP_VERSION" value="2">
<input type="hidden" name="HPP_CHANNEL" value="ECOM">
<input type="hidden" name="HPP_LANG" value="en">
<!-- Begin 3D Secure 2 Mandatory and Recommended Fields -->
<input type="hidden" name="HPP_CUSTOMER_EMAIL" value="test@example.com">
<input type="hidden" name="HPP_CUSTOMER_PHONENUMBER_MOBILE" value="44|789456123">
<input type="hidden" name="HPP_BILLING_STREET1" value="Flat 123">
<input type="hidden" name="HPP_BILLING_STREET2" value="House 456">
<input type="hidden" name="HPP_BILLING_STREET3" value="Unit 4">
<input type="hidden" name="HPP_BILLING_CITY" value="Halifax">
<input type="hidden" name="HPP_BILLING_POSTALCODE" value="W5 9HR">
<input type="hidden" name="HPP_BILLING_COUNTRY" value="826">
<input type="hidden" name="HPP_SHIPPING_STREET1" value="Apartment 852">
<input type="hidden" name="HPP_SHIPPING_STREET2" value="Complex 741">
<input type="hidden" name="HPP_SHIPPING_STREET3" value="House 963">
<input type="hidden" name="HPP_SHIPPING_CITY" value="Chicago">
<input type="hidden" name="HPP_SHIPPING_STATE" value="IL">
<input type="hidden" name="HPP_SHIPPING_POSTALCODE" value="50001">
<input type="hidden" name="HPP_SHIPPING_COUNTRY" value="840">
<input type="hidden" name="HPP_ADDRESS_MATCH_INDICATOR" value="FALSE">
<input type="hidden" name="HPP_CHALLENGE_REQUEST_INDICATOR" value="NO_PREFERENCE">
<!-- End 3D Secure 2 Mandatory and Recommended Fields -->
<!-- Begin Fraud Management and Reconciliation Fields -->
<input type="hidden" name="BILLING_CODE" value="59|123">
<input type="hidden" name="BILLING_CO" value="GB">
<input type="hidden" name="SHIPPING_CODE" value="50001|Apartment 852">
<input type="hidden" name="SHIPPING_CO" value="US">
<input type="hidden" name="CUST_NUM" value="6e027928-c477-4689-a45f-4e138a1f208a">
<input type="hidden" name="VAR_REF" value="Acme Corporation">
<input type="hidden" name="PROD_ID" value="SKU1000054">
<!-- End Fraud Management and Reconciliation Fields -->
<input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/responseUrl">
<input type="hidden" name="CARD_PAYMENT_BUTTON" value="Pay Invoice">
<input type="hidden" name="CUSTOM_FIELD_NAME" value="Custom Field Data">
<input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
<input type="submit" value="Click To Pay">
</form>
To integrate with our server-side SDK, you can use our JavaScript library available to download on GitHub. This interfaces with the server-side SDK of your choice and generates the payment form on your website or in your application. You can choose to render the payment form using your own embedded iFrame, as a Lightbox or perform a full-page redirect.
In Lightbox mode, for example, the JS library does all the work of creating the overlay, opening the iFrame, displaying the HPP and finally grabbing the response to be sent to the server-side SDK. In mobile browsers the HPP is opened in a new tab.
Note: The sample code below is given as an example, you may need to modify it in order to suit your particular needs.
<script src="https://code.jquery.com/jquery-3.5.0.js"></script>
<script src="rxp-hpp.js"></script>
<script>
$(document).ready(function() {
$.getJSON("sdkRequestEndpoint", function(jsonFromRequestEndpoint) {
RealexHpp.setHppUrl("https://pay.sandbox.realexpayments.com/pay");
RealexHpp.embedded.init("payButtonId", "iframeId", "responseEndpoint", jsonFromRequestEndpoint);
if (window.addEventListener) {
window.addEventListener('message', receiveMessage, false);
} else {
window.attachEvent('message', receiveMessage);
}
});
});
</script>
payButtonId | This will be the ID of the button used to launch the HPP. |
iframeId | The ID of the iFrame to load the HPP into. |
responseEndpoint | The URL to which the JSON response from the HPP will be posted. |
jsonFromRequestEndpoint | The JSON output from the HPP server-side SDK. This must be a JavaScript object, not a string. |
RealexHpp.init() | Must only be called when the page DOM is fully loaded. |
<script src="https://code.jquery.com/jquery-3.5.0.js"></script>
<script src="rxp-hpp.js"></script>
<script>
$(document).ready(function() {
$.getJSON("sdkRequestEndpoint", function(jsonFromRequestEndpoint) {
RealexHpp.setHppUrl("https://pay.sandbox.realexpayments.com/pay");
RealexHpp.lightbox.init("payButtonId", "responseEndpoint", jsonFromRequestEndpoint);
});
});
</script>
payButtonId | This will be the ID of the button used to launch the HPP in a Lightbox. |
responseEndpoint | The URL to which the JSON response from the HPP will be posted. |
jsonFromRequestEndpoint | The JSON output from the HPP server-side SDK. This must be a JavaScript object, not a string. |
RealexHpp.init() | Must only be called when the page DOM is fully loaded. |
<script src="https://code.jquery.com/jquery-3.5.0.js"></script>
<script src="rxp-hpp.js"></script>
<script>
$(document).ready(function() {
$.getJSON("sdkRequestEndpoint", function(jsonFromRequestEndpoint) {
RealexHpp.setHppUrl("https://pay.sandbox.realexpayments.com/pay");
// When using full page redirect your Response URL must be an absolute link
RealexHpp.redirect.init("payButtonId", "https://www.example.com/responseUrl", jsonFromRequestEndpoint);
});
});
</script>
payButtonId | This will be the ID of the button used to launch the HPP. |
responseEndpoint | The URL to which the response from the HPP will be posted. |
jsonFromRequestEndpoint | The JSON output from the HPP server-side SDK. This must be a JavaScript object, not a string. |
RealexHpp.init() | Must only be called when the page DOM is fully loaded. |
In order to utilize the HPP in-app you can use our Android library. It can be installed using Maven or Gradle and it's also available to download on GitHub For more information on installation, please refer to the Libraries & SDKs section.
The library interfaces with the server-side SDK of your choice; processing the request, presenting the payment form and handling the transaction outcome.
The library is compatible with Android SDK 19+ and Android version 4.4+.
The sample code below is given as an example, you may need to modify it in order to suit your particular needs.
To instantiate the HPPManager do the following:
HPPManager hppManager = new HPPManager();
The HPPManager requires three server URLs.
The three URLs can be set in the following way:
hppManager.setHppRequestProducerURL("https://myserver.com/hppRequestProducer");
hppManager.setHppURL("https://pay.sandbox.realexpayments.com/pay");
hppManager.setHppResponseConsumerURL("https://myserver.com/hppResponseConsumer");
There are three possible outcomes from the HPP interaction:
Note that these are independent of the outcome of the transaction (whether it was authorized successfully or not), what we're referring to here is the Android library's actual communication with the HPP. You can implement the following methods specified in HPPManagerListener to receive back the result from the HPPManager:
@Override public void hppManagerCompletedWithResult(ConsumerResponse consumerResponse) { /* success */ }
@Override public void hppManagerFailedWithError(HPPError error) { /* something went wrong */}
@Override public void hppManagerCancelled() { /* operation was canceled */ }
Insert the HPPManager fragment into your activity as follows. When executing this code HPPManager will process the given parameters, get the request from the server, send the encoded request to HPP and present the form received back.
Fragment hppManagerFragment = hppManager.newInstance();
getFragmentManager()
.beginTransaction()
.add(R.id.container,hppManagerFragment)
.commit();
You can style the HPP using templates to maintain the look and feel of your app. For more information on how to do this and to download some sample templates, please see our Customization guide.
In order to utilize the HPP in-app you can use our iOS HPP library. It can be installed using Cocoapods and it's also available to download on GitHub For more information on installation, please refer to the Libraries & SDKs page.
The library interfaces with the server-side SDK of your choice; processing the request, presenting the payment form and handling the transaction outcome.
The library is compatible with Xcode 7.1.1+ | iOS 8.0+.
The sample code below is given as an example, you may need to modify it in order to suit your particular needs.
To instantiate the HPPManager do the following:
let hppManager = HPPManager();
The HPPManager requires three server URLs.
The three URLs can be set in the following way:
hppManager.HPPRequestProducerURL = NSURL(string: "https://myserver.com/hppRequestProducer");
hppManager.HPPURL = NSURL(string: "https://pay.realexpayments.com/pay");
hppManager.HPPResponseConsumerURL = NSURL(string: "https://myserver.com/hppResponseConsumer");
Next you set the object which will act as the delegate for the HPPManager. The delegate should implement the HPPManagerDelegate protocol and so will receive the response from the HPPManager.
hppManager.delegate = self;
There are three possible outcomes from the HPP interaction
Note that these are independent of the outcome of the transaction (whether it was authorized successfully or not), what we're referring to here is the iOS library's actual communication with the HPP. The HPPManager's delegate should implement the following three functions to receive back the result from the HPPManager.
func HPPManagerCompletedWithResult(result: Dictionary <String, String>);
func HPPManagerFailedWithError(error: NSError?);
func HPPManagerCancelled();
Using the presentViewInViewController() method the HPPManager will process the given parameters, get the request from the server, send the encoded request to HPP and present the form received back.
hppManager.presentViewInViewController(self);
You can style the HPP using templates to maintain the look and feel of your app. For more information on how to do this and to download some sample templates, please see our Customization guide.
On the server-side, setup your response endpoint to take in the response JSON and create the HPP response object. This will contain all the transaction response values you need to update your application. If you're using full-page redirect the response will be a standard HTTP POST.
The response from HPP will contain a hashed string (SHA1HASH field) made up of key transaction variables, including the Order ID, Result Code and Timestamp. The SDK will construct and check the hash to ensure the response hasn't been tampered with. It will throw an exception if what it constructs doesn't match the SHA1HASH returned in the response.
The Timestamp returned in the response will be identical to the one sent in the request JSON. This, combined with the Order ID and other transaction variables, can be used to definitively link the response received with the transaction request and order created in your application. You should also check the other transaction variables, for example the Amount, against what was stored in your application at the time the request JSON was sent.
A 111 result code indicates that the Issuer requires Strong Customer Authentication (SCA) for a transaction. In order to avoid this outcome, please ensure you enable 3D Secure 2 on the HPP.
// configure client settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setSharedSecret("secret");
config.setServiceUrl("https://pay.sandbox.realexpayments.com/pay");
HostedService service = new HostedService(config);
/* TODO: grab the response JSON from the client-side.
sample response JSON (values will be Base64 encoded):
String responseJson = "{ \"MERCHANT_ID\": \"MerchantId\", \"ACCOUNT\": \"internet\", \"ORDER_ID\": \"GTI5Yxb0SumL_TkDMCAxQA\", \"AMOUNT\": \"1999\", "
+ "\"TIMESTAMP\": \"20170725154824\", \"SHA1HASH\": \"843680654f377bfa845387fdbace35acc9d95778\", \"RESULT\": \"00\", \"AUTHCODE\": \"12345\", "
+ "\"CARD_PAYMENT_BUTTON\": \"Place Order\", \"AVSADDRESSRESULT\": \"M\", \"AVSPOSTCODERESULT\": \"M\", \"BATCHID\": \"445196\", \"MESSAGE\": \"[ test system ] Authorised\", "
+ "\"PASREF\": \"15011597872195765\", \"CVNRESULT\": \"M\", \"HPP_FRAUDFILTER_RESULT\": \"PASS\"}";
*/
try {
// create the response object from the response JSON
Transaction response = service.parseResponse(responseJson, true);
String orderId = response.getOrderId(); // GTI5Yxb0SumL_TkDMCAxQA
String responseCode = response.getResponseCode(); // 00
String responseMessage = response.getResponseMessage(); // [ test system ] Authorised
HashMap<String, String> responseValues = response.getResponseValues(); // get values accessible by key
String fraudFilterResult = responseValues.get("HPP_FRAUDFILTER_RESULT"); // PASS
// TODO: update your application and display transaction outcome to the customer
} catch (ApiException exce) {
// For example if the SHA1HASH doesn't match what is expected
// TODO: add your error handling here
}
<?php
require_once('vendor/autoload.php');
use GlobalPayments\Api\ServiceConfigs\Gateways\GpEcomConfig;
use GlobalPayments\Api\Services\HostedService;
use GlobalPayments\Api\Entities\Exceptions\ApiException;
// configure client settings
$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "internet";
$config->sharedSecret = "secret";
$config->serviceUrl = "https://pay.sandbox.realexpayments.com/pay";
$service = new HostedService($config);
/*
* TODO: grab the response JSON from the client-side.
* sample response JSON (values will be Base64 encoded):
* $responseJson ='{"MERCHANT_ID":"MerchantId","ACCOUNT":"internet","ORDER_ID":"GTI5Yxb0SumL_TkDMCAxQA","AMOUNT":"1999",' .
* '"TIMESTAMP":"20170725154824","SHA1HASH":"843680654f377bfa845387fdbace35acc9d95778","RESULT":"00","AUTHCODE":"12345",' .
* '"CARD_PAYMENT_BUTTON":"Place Order","AVSADDRESSRESULT":"M","AVSPOSTCODERESULT":"M","BATCHID":"445196",' .
* '"MESSAGE":"[ test system ] Authorised","PASREF":"15011597872195765","CVNRESULT":"M","HPP_FRAUDFILTER_RESULT":"PASS"}";
*/
try {
// create the response object from the response JSON
$parsedResponse = $service->parseResponse($responseJson, true);
$orderId = $parsedResponse->orderId; // GTI5Yxb0SumL_TkDMCAxQA
$responseCode = $parsedResponse->responseCode; // 00
$responseMessage = $parsedResponse->responseMessage; // [ test system ] Authorised
$responseValues = $parsedResponse->responseValues; // get values accessible by key
} catch (ApiException $e) {
// For example if the SHA1HASH doesn't match what is expected
// TODO: add your error handling here
}
// configure client settings
var service = new HostedService(new GpEcomConfig
{
MerchantId = "MerchantId",
AccountId = "internet",
SharedSecret = "secret",
ServiceUrl = "https://pay.sandbox.realexpayments.com/pay"
});
/* TODO: grab the response JSON from the client-side for example:
var responseJson = Request.Form["hppResponse"];
sample response JSON (values will be Base64 encoded):
var responseJson = "{ \"MERCHANT_ID\": \"MerchantId\", \"ACCOUNT\": \"internet\", \"ORDER_ID\": \"GTI5Yxb0SumL_TkDMCAxQA\", \"AMOUNT\": \"1999\","
+ "\"TIMESTAMP\": \"20170725154824\", \"SHA1HASH\": \"843680654f377bfa845387fdbace35acc9d95778\", \"RESULT\": \"00\", \"AUTHCODE\": \"12345\","
+ "\"CARD_PAYMENT_BUTTON\": \"Place Order\", \"AVSADDRESSRESULT\": \"M\", \"AVSPOSTCODERESULT\": \"M\", \"BATCHID\": \"445196\","
+ "\"MESSAGE\": \"[ test system ] Authorised\", \"PASREF\": \"15011597872195765\", \"CVNRESULT\": \"M\", \"HPP_FRAUDFILTER_RESULT\": \"PASS\"}";
*/
try
{
// create the response object from the response JSON
Transaction response = service.ParseResponse(responseJson, true);
var orderId = response.OrderId; // GTI5Yxb0SumL_TkDMCAxQA
var responseCode = response.ResponseCode; // 00
var responseMessage = response.ResponseMessage; // [ test system ] Authorised
var responseValues = response.ResponseValues; // get values accessible by key
var fraudFilterResult = responseValues["HPP_FRAUDFILTER_RESULT"]; // PASS
// TODO: update your application and display transaction outcome to the customer
}
catch (ApiException exce)
{
// TODO: add your error handling here
}
[RESULT=00,
AUTHCODE=12345,
MESSAGE=[ test system ] Authorised,
PASREF=14631546336115597,
AVSPOSTCODERESULT=M,
AVSADDRESSRESULT=M,
CVNRESULT=M,
ACCOUNT=internet,
MERCHANT_ID=MerchantId,
ORDER_ID=N6qsk4kYRZihmPrTXWYS6g,
TIMESTAMP=20180613113227,
AMOUNT=1001,
BATCHID=691175,
CARD_PAYMENT_BUTTON=Pay Invoice,
MERCHANT_RESPONSE_URL=https://www.example.com/responseUrl,
HPP_LANG=GB,
BILLING_CODE=59|123,
BILLING_CO=GB,
SHIPPING_CODE=50001|Apartment 852,
SHIPPING_CO=US,
COMMENT1=Mobile Channel,
ECI=5
AUTHENTICATION_VALUE=ODQzNjgwNjU0ZjM3N2JmYTg0NTM=,
DS_TRANS_ID=c272b04f-6e7b-43a2-bb78-90f4fb94aa25,
MESSAGE_VERSION=2.1.0,
SRD=MMC0F00YE4000000715,
SHA1HASH=8ab81d4437e24a88a08cffb51c15151846bd7b61]
Use our test cards to try out different scenarios for your application to handle. The full list of cards is available in the Technical Resources section.