Documentation for Developers

Get up and running by exploring our integration guides and documentation for developers; including libraries, keys and other integration tools.

Hosted Payment Page

The Hosted Payment Page (HPP) is our PCI DSS v3.2 compliant redirect solution, allowing you to 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.

Step 1 - Set up your server

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
}

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
}

Step 2 - Set up your client

Step 3 - Process HPP Response

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 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
},>

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]

Step 4 - Test

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.

Successful

4263-9700-0000-5262

Declined

4000-1200-0000-1154

Successful

5425-2300-0000-4415

Declined

5114-6100-0000-4778

Documentation for Developers

Hosted Payment Page

Step 1 - Set up your server

Step 2 - Set up your client

Step 3 - Process HPP Response

Step 4 - Test

Flexible payment solutions for small businesses

Solutions

Products

Customers