Skip to main content

Advanced Pay Button Integration

Creating a custom pay button allows you to have full control over what information is passed to the Handpoint gateway. You can leverage any of the hosted integration fields as part of the pay button integration.

Pre-Requisites

NameDescription
Merchant Account IDYour unique Merchant Account ID. You should have received these details when your account was set up.
Hosted Integration URLYour unique URL to use the Hosted Integration.
SignatureHash used to sign the transaction request. See the signature calculation section for information on how to create the hash.

Gateway Request

To create the button the details should be URL encoded Name=Value fields separated by ‘&’ characters (refer to RFC 1738 and the application/x-wwwform- urlencoded media type).

This is then base64 encoded with all padding characters (=) stripped and the following characters +, / replaced with – and _ respectively.

This string is then appended to the gateway URL via a GET parameter called fields to give the final link replacing the {base 64 encoded string} above.

Request Fields

FieldMandatoryDescription
merchantIDYesThe six-digit id provided to you during set-up, e.g. 123456 For testing, please use ‘TEST’
amountYesThe amount of the transaction in minor currency. For the UK this is in pence, e.g. £10.99 is sent as 1099. Numeric values only – no decimal points or currency symbols.
actionYesThe action of the transaction. Values are: SALE, VERIFY and PREAUTH.
typeYesThe type of transaction. Passed as a single digit. Possible values are:
1 – E-commerce (ECOM)
2 - Mail Order/Telephone Order (MOTO)
redirectURLYesThe URL to which the customer will be redirected after the transaction with the transaction result sent via POST. We recommend the integration also contain a callbackURL to ensure the transaction details are sent to the website in case the cardholder’s browser fails to redirect them.
countrycodeYesMerchant's Location. Valid ISO-3166 alpha or numeric code, e.g. 826 for U.K.
currencyCodeYesTransaction Currency. Valid ISO-3166 alpha or numeric code, e.g. 826 for U.K.
signatureYesA hashed string of the request containing the signature key unique to the merchant ID. More details on message signing can be found in our annex Signature Calculation
redirectURLFailNoThe URL to which the customer will be redirected and the transaction result will be POSTed if the transaction fails.If left blank, the redirectURL will be used.
formAmountEditableNoAccepts the following value:
Y’ – Allows the cardholder to enter the amount to pay in the hosted form and is useful for donations.
Note: Passing ‘N’, or null to this field causes the amount in the hosted form to act as default, i.e. A static value the user can’t change.

Sample Code (Request)

The following is an example test request built in PHP.

<?php

//Gateway URL
$url = 'https://commerce-api.handpoint.com/button/';

//Merchant signature key. It will be provided by the Handpoint support team
$sigKey = '3obzOxdqw6e1u';

//Request information
$req = array(
'merchantID' => '155928', //merchantID will be provided by the Handpoint support team
'amount' => 1099, //Either major currency units includes a single decimal point such as ’10.99'.
//Minor currency units contains no decimal points such as ‘1099
'action' => 'SALE', //action could be SALE, VERIFY or PREAUTH
'type' => 1, //1 –> E-commerce (ECOM), 2 –> Mail Order/Telephone Order (MOTO)
'redirectURL' => 'https://checkout.handpoint.io/', //The payment form will redirect the Customer’s browser to this URL after the transaction has been completed.
'countryCode' => 826, //ISO 3-letter country code. 826 -> United Kingdom
'currencyCode' => 826 //ISO 3-letter currency code. 826 -> GBP
);

$req['signature'] = createSignature($req, $sigKey);
$poststring = http_build_query($req, '', '&');
$base64request = base64_encode($poststring);

echo "<form action=\"{$url}?fields={$base64request}\" method=\"post\" id=\"custom\">";

//Button to start the payment
echo '<input type="submit" value="Pay Now">
</form>';

//Function that generates the signature using the request information and the merchant signature key
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);
}
?>