Hosted Payment Page

You’re just a few steps away from integrating our Hosted Payment Page (HPP), offering your customers an intuitive, seamless checkout experience.

Why will you love this solution?

Secure

Now, being secure is that much easier. With our HPP, there’s just PCI DSS SAQ A (that’s Payment Card Industry Data Security Standard Self-Assessment Questionnaire A, in case you wondered) to complete. You get the customers; we have your security.

Dynamic

There’s no need to reinvent the design wheel. Our dynamic templates adapt to your display requirements for device and screen size.



Personal

Make your payment page as handsome as the rest of your site. Upload HTML, CSS, JavaScript, image, and font files to our secure environment and watch magic happen.


Let's get started.

Configuration

Your unique HPP gets created in the Merchant section of our portal. To build or upload an HPP for a specific merchant ID (MID), go to Merchant > Company & MID > Create Service. Not sure if you’re in the right place? Take a look at the screenshot below:

Acquired Merchants List

Simple as that. Now it’s time to customise your payment page. We’ve also added a default template to the dashboard to get you started. Download it and if you need some help, take a look here.

Endpoints

Time to play - access your HPP using these endpoints:

Security

For your sake and ours, we make sure that each transaction you send to us is a genuine request.

Here is how:

Verified Referring URL

Your customers are redirected to the HPP using a referring URL. We only accept requests from referring URLs whitelisted within the Hub, so make sure you go to Merchants > Company & MID > HPP > Edit and so we know you’re for real.

Don't forget Don’t forget to confirm at least one referring URL for the production environment within the Hub. And because security is so important, referring URLs must begin with https://.

Request Hash

We use encrypted tokens to assess the integrity of your transaction data. This encrypted token is referred to as the Request Hash and sent in the hash parameter of your request to us. If data does not pass our integrity check because the hash value is missing or mismatches the transaction data, we decline the transaction request. It’s not personal, it’s just part of the process in keeping everything as secure as possible. Each transaction request needs a unique hash value, so here are the steps to start generating yours:

  1. Sort the transaction parameters - excluding your company key - alphabetically and then concatenate (don’t you just love this word?). Here are some examples:

    amount . company_id . company_mid_id . currency_code_iso3 . merchant_order_id . transaction_type
    //14.991131045GBP20170619111AUTH_CAPTURE
          

    Over here at Request Parameters, we’ve listed all the parameters to include with each transaction request.

  2. SHA256 encrypt the resulting string:

    24febfefcd5fd890837e82b8eb29759227f7614f4bc99ce0ea9af63399cfacad
  3. Then, append your company_key to the string generated in step two and SHA256 encrypt again:

    24febfefcd5fd890837e82b8eb29759227f7614f4bc99ce0ea9af63399cfacadcompany_key
    7c93225890c7cbdf9eb904285c18fa9b72d47acd3e007049fb9adbad1fe59f27
    Pro tip: It’s time to get your company_key (if you haven't already). Send the support@acquired.com team a note, they’ll allocate one straight away.

With us so far? To get you started, here are samples of code to generate encrypted hash values:

?php 
$param = array(
    'company_id'=>133,
    'company_mid_id'=>1045,
    'merchant_order_id'=>'20170619111',
    'transaction_type'=>'AUTH_CAPTURE',
    'currency_code_iso3'=>'GBP',
    'amount'=>14.99,
);

$company_key ='company_key';
ksort($param);
$plain = implode('', $param);
// $plain ="14.991131045GBP20170619111AUTH_CAPTURE";
$temp = hash('sha256', $plain);
// $temp = "0722b76a63d0b7adde39b13119e4dfd5aa7bd0d91885d55597af334a055c4cd0";
$hash = hash('sha256', $temp.$company_key);
//$hash = "2934149504e39101f5cfad6ec3e971978890a057373ac3237e0dd150dd491d3d3"
?>              
      
Coming soon...
Coming soon...

Request

The last page of your website before customers reach our environment is the referral page. This is the place to integrate a form with hidden HTML fields containing customers’ order data. We receive the order data via POST request. The payment page loads, and customers are prompted to enter their sensitive card data. And that’s it, just like that you’ve completed a payment!

><!DOCTYPE html> 
<html> 
<head>
  <title>Sample Code</title>
</head>
<body>
  <form action="https://qahpp.acquired.com" method="POST">
    <input type=hidden name="company_id" value="113">
    <input type=hidden name="company_mid_id" value="1045">
    <input type=hidden name="currency_code_iso3" value="GBP">
    <input type=hidden name="transaction_type" value="AUTH_CAPTURE"> 
    <input type=hidden name="merchant_order_id" value="20170619111"> 
    <input type=hidden name="amount" value="14.99">
    <input type=hidden name="hash" value="2934149504e39101f5cfad6ec3e971978890a057373ac3237e0dd150dd491d3d3">
    <input type=submit value="Submit"> 
  </form>
</body>
</html>

Request Parameters

Every HPP transaction requires a certain number of mandatory fields, which you’ll see at the top of the table below. Minimal data will work, but we recommend that you give us extra information with each request. This fulfils additional security checks such as Account Verification System (AVS), where available.

Take a look at our guide for integrating 3-D Secure (both Version 1 & 2) into the HPP here.
Parameter Format Length Description
company_id
Required
int 1-4 API Company ID we issue to merchants.
company_mid_id
Required
int 1-11 API Merchant ID we issue to merchants.
hash
Required
string65 Value of your encrypted token. Take a look here for more information.
vt boolean 1 Additional parameter to flag a transaction as MOTO - include if processing payments via phone or an IVR solution.
merchant_order_id
Required
string1-50 Unique ID you’ll use to identify each transaction.
transaction_type
Required
string1-20 Transaction type. Click to list all possible transaction types.
currency_code_iso3
Required
string3 Transaction currency, an ISO 4217 3-digit code.
amount
Required
int 1-11 Transaction amount.
is_tds
3D-Secure (v1 and v2)
int 1 Flag to initiate 3-D Secure / SCA authentication. Should be set to 2 to enable both versions of 3-D Secure.
merchant_customer_id string0-50 Unique ID you’ll use to identify each customer.
merchant_custom_1 string0-50 Custom merchant data.
merchant_custom_2 string0-50 Custom merchant data.
merchant_custom_3 string0-50 Custom merchant data.
customer_fname string0-50 Customer's first name.
customer_lname
MCC 6012
string0-50 Customer's last name.
customer_dob
MCC 6012
string10 Customer’s date of birth formatted as YYYY-MM-DD.
billing_street
AVS & EMV® 3-D Secure (v2)
string0-100 Cardholder’s street address.
billing_street2
EMV® 3-D Secure (v2)
string0-100 Cardholder’s street address, line 2.
billing_city
EMV® 3-D Secure (v2)
string0-100 City as it appears in a cardholder’s address.
billing_state string0-100 State or province as it appears in a cardholder’s address.
billing_zipcode
MCC 6012 & AVS &
EMV® 3-D Secure (v2)
string0-100 Cardholder’s billing ZIP or postal code.
billing_country_code_iso2
EMV® 3-D Secure (v2)
string2 The ISO 3166 2-character country code of the cardholder’s address.
billing_phone_code
EMV® 3-D Secure (v2)
string2 Cardholder’s billing phone country code (For example, 44 for the UK).
billing_phone
EMV® 3-D Secure (v2)
string7-20 Cardholder’s billing phone number - we strongly recommend sending the customer's mobile phone number.
billing_email
EMV® 3-D Secure (v2)
string0-50 Cardholder’s billing email address.
callback_url string10-2083 You’ll find more information about direct server-to-server feedback here. Note that this parameter overwrites the default value pre-configured in our portal.
return_url string10-2083 URL to redirect customers from our environment back to your website following purchase authorisation. Note that this parameter overwrites the default value pre-configured in our portal.
return_method string0-12 Specify how to receive a response to the return URL. Possible values are POST, GET, POST_MESSAGE. Note that this parameter overwrites the default value pre-configured in our portal.
error_url string10-2083 Customers redirect to this URL when errors occur. Sent as a GET, we return the following parameters: status, message, company_id, company_mid_id, and merchant_order_id.
cancel_url string10-2083 Action for a ‘Cancel’ button if your payment page has one. Note that this parameter overwrites the default value pre-configured in our portal.
load_balance boolean 1 Enable the load balancing feature. You’ll find more information on this feature here.
template_id int 0-4 Specifies the HPP template to be displayed. Note that this parameter overwrites the default value pre-configured in our Hub.
merchant_contact_url
EMV® 3-D Secure (v2)
int1 A link to the Contact Us page on your website for example https://yourdomain/contact.
tds_source
EMV® 3-D Secure (v2)
int1 The channel being used to initiate the transaction:

1 = Browser
2 = Mobile SDK
tds_type
EMV® 3-D Secure (v2)
int1 The type of transaction you are processing:

1 = Cardholder Verification (Zero Value Auth)
2 = Ad hoc payment (Customer Present)
3 = Recurring (Setting up a monthly payment for the same amount)
4 = Add Card (Just adding a new card on file for the customers account)
tds_preference
EMV® 3-D Secure (v2)
int1 If you'd like the customer to be challenged:

0 = No Preference
1 = Don't Challenge
2 = Request Challenge

The issuer may decide to ignore your preference.
Did your acquirer give you MCC 6012 for your Merchant Category Code (MCC)? If so, please ensure that you submit customer_name, customer_dob, and billing_zipcode parameters in each request. If you don’t know your MCC classification or if you forget, which happens to the best of us, contact support@acquired.com.

Error Handling

If there is something wrong with your request, or something goes wrong on our end, we'll redirect the user to the Error URL to let you know. This will be sent as a GET here is a handy example:

https://yourdomain.com/error_url?status=500&message=hash+is+invalid.&company_id=113&company_mid_id=1045&hpp_id=27802&merchant_order_id=errortesting-92380&company_name=DemoCompany&merchant_name=DemoMerchant

Response

We have cleverly enabled two ways you can receive transaction authorisation results in our hosted environment. And even more clever, these can be used in tandem, ensuring that responses are not lost due to inconvenient circumstances such as connection issues between us and your servers.

Return URL

Right, we’ve confirmed payment authorisation. Now, we redirect customers to your website using the Return URL. When configuring the HPP, you can set a default value in our Hub or you can change the endpoint dynamically for each individual request by setting the return_url parameter to whatever endpoint you like.

In return, you’ll receive a POST or GET response. (It is up to you but we would recommend a POST).

Because we’re all about security, GET responses return limited parameters, namely:

amount, avsaddress, avszipcode, code, company_id, company_mid_id, currency_code_iso3, cvvresult, is_remember, merchant_custom_1, merchant_custom_2, merchant_custom_3, message, transaction_id and hash.

POST responses return everything above as well as everything that is either sent in the request (or gathered on the HPP)

We’ll say it again – SECURITY. The return_url parameter must begin with https:// and it should be configured to handle all possible transaction response codes, including errors. Already thought of that? You’re the biz.

Callback URL

Uh oh. Despite our best efforts, at times a transaction response is not received successfully. You’ll need a Callback URL to address these scenarios, which may include:

  • The customer closed their browser before being redirected back to your site.
  • There was a temporary connection issues with your servers.
  • A general issue with internet communication.

Silence is NOT golden. We introduced the Callback URL for direct server-to-server feedback so that you receive every response, every time. When configuring the HPP, feel free to set a default value in our Hub, or you can change the endpoint dynamically for each individual request by setting the callback_url parameter to the endpoint you like best.

If it really is the end of the world and we do not receive an HTTP 200 response back from your server, we will do our best to re-establish a connection. We’ll ping you five times in five-minute intervals to ensure your system is updated with all order details.

You guessed it, the callback_url parameter must begin with https:// and it should be configured to handle all possible transaction response codes, including errors..

Verifying the Response

You will spot the parameter hash in responses to both Return and Callback URLs, which confirms that the response really did come from us. Here are the steps to calculate the response hash value:

  1. 1. First sort response parameters - excluding hash - alphabetically and then concatenate. Here is an example:

    amount . cardnumber . code . message . merchant_order_id . transaction_id
    //14.99XXXXXXXXXXXX87101Transaction Success201706191113454353

    We listed all the parameters that may be included in a response right over here: Response Parameters.

  2. SHA256 encrypt the resulting string:

    15dc8221a54a05e9c72f360a4468ccbc26946ad931e95e48f27e5845c79a7563
  3. Append your company hash to the string generated in step two, and SHA256 encrypt again

    15dc8221a54a05e9c72f360a4468ccbc26946ad931e95e48f27e5845c79a7563company_key
    b1d09abc0be3a5beb86aa5b9b6b70e1fff26f68eb97ba7f8f0be4d506396b2dd
          
    Your company_key value is waiting for you, just ping the support@acquired.com team.

All done? Here are samples of code to calculate the response hash value:

$response = array(
'transaction_id'=>212327,
'company_id'=>113,
'merchant_order_id'=>'20160709_666',
'company_mid_id'=>'1025',
'currency_code_iso3'=>'GBP',
'code'=>1,
'amount'=>100.00,
'message'=>'Declined',
'billing_country_code_iso2'=>'GB',
'billing_city' => 'London',
'billing_state' => 'London',
'billing_street' => '123 Fake Street',
'billing_street2' => 'Hammersmith',
'billing_zipcode'=>'W120LU',
'billing_email'=>'test@sample.com',
'shipping_country_code_iso2'=>'GB',
'shipping_city'=>'London',
'shipping_state'=>'London',
'billing_zipcode'=>'W120LU',
'shipping_street'=>'',
'shipping_street2'=>'',
'shipping_zipcode'=>'',
'shipping_email'=>'test@sample.com'
);

$company_key = 'hashcode';
ksort($response);


//100LondonGBtest@sample.comLondon123 Fake StreetHammersmithW120LU11131025GBP20160709_666DeclinedLondonGBtest@sample.comLondon212327
//Hash before add company hash code: 72ad0f53cf1e0c3102ebff9edd2b178e8fd4f87cdc468f0267ddb6afe3b28876
$response['hash'] = hash('sha256', hash('sha256', implode('', $response)).$company_key);
//Hash: 7c28394b9bb5631c5d8916a16cab2c0b5a59bd7a583f71ef9baa706f0bf1f676
      
Coming soon...
Coming soon...

Response Parameters

Parameter Format Length Description
amount int 1-11 Transaction amount.
avsaddress string 1-2 AVS check on the first line of the customer’s address, when available.
avszipcode string 1-2 AVS check on the first line of the customer’s postcode or zipcode, when available.
bank_response_code int 2 Transaction result code communicated by the issuing bank.
bin int 6 First six characters of the card used for the transaction.
card_category string 0-30 Category of the card used, for example CREDIT or DEBIT
card_level string 0-30 Level of the card used, for example CLASSIC.
card_type string 2-8 Type of card used for the transaction, possible values are VISA, MC, AMEX.
cardexp int 6 Expiration date of the card used for the transaction, formatted as MMYYYY.
cardholder_name string 0-100 Cardholder’s name as entered into the HPP.
cardnumber string 12-19 Masked credit or debit card number used for the transaction.
code int 1-3 Code describing the transaction results.
company_id int 1-4 API Company ID we issue to merchants.
company_mid_id int 1-11 API MID ID we issue to merchants.
eci
3-D Secure
int 1-2 Result of 3-D Secure authentication.
cvvresult string 1-2 Result of CVV2 security check.
is_remember boolean 1 Flag to indicate if we have tokenised card details for future use.
issuing_bank string 0-50 Name of the bank issuing the card used for the transaction.
issuing_country string 0-50 Country that issued the card used for the transaction.
issuing_country_iso2 string 0-2 Country that issued the card used for the transaction, an ISO2 two-letter code.
merchant_order_id string d>0-50 Unique ID you’ll have used to identify each transaction, repeated from the request.
message string 1-65535 Text describing the transaction response.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
hash string 10-2083 Verification hash value. See here.
Extra information - In addition to the transaction-specific response parameters you’ve just seen, all the values in response to the callback_url are returned when submitted in the request or gathered on the HPP.

Styling

This is the fun part - it’s time to customise your payment page. We’ve added a default template to the Hub to get you started. Download and change it however you want (within reason), take a look here.

Your customers will have a better checkout experience, and by hosting your CSS, JavaScript, image and font files, we take on the burden of costly and complex PCI DSS compliance. You just need to complete SAQ A. How cool is that?

To make our solution as flexible as possible, we assign a placeholder to each element of the payment form. These simply display information passed through the request or gather additional information during checkout.

Uploading the Template

Templates can be uploaded in the Merchant section of our portal. To upload a template, go to Merchant > Company & MID > Configure. Not sure if you’re in the right place? Take a look at the screenshot below:

UPDATE - insert image

Acceptable File Types: .html | .css | .js | .png | .jpg | font files.

You must name the HTML file index.html. All files must be in one zipped file without any additional folders.

Note: Once uploaded to production, the files are reviewed by our Support Team and marked as available when the template is ready for use. Please allow 24 hours but it should be quick.

Default Template

You can set a default template in the Hub which displays if the template_id parameter isn’t populated in the request. Here’s a handy screen shot:

Acquired Merchants List

Dynamic Template

To change the template displayed to customers dynamically, you must include the template_id parameter in the HPP request and assign a unique identifier to each uploaded file. This value displays in the HPP section of the Hub once your template is created. Sounds complicated, but it’s really not:

Acquired Merchants List

Placeholders - Card Details

When you create the all-important payment form, use the following placeholders as values in the HTML:

Parameter Placeholder Description
cardholder_name {{cardholder_name}} Cardholder name.
cardnumber {{cardnumber}} Card number.
cardexp {{cardexp_month}} Card expiry month.
cardexp {{cardexp_year}} Card expiry year.
cardcvv {{cardcvv}} CVV2 value
subscription_type {{is_remember}} Flag to initiate a INIT subscription.

Want to know how to incorporate these placeholders into your template? There’s an example in the portal. For a test account, contact support@acquired.com.

Key info - You can display any parameter passed through the HPP request by including the relevant placeholder. For example, ‘amount’ becomes {{amount}} in your template. You can capture these parameters on the HPP in a similar way to card details.