Intro
The Hosted Payment Page (HPP) integration method provides web developers with a quick integration to the online Payment Gateway and full payment page functionality for processing online card payments.
How it Works
To process an online payment using the HPP, your website needs to send a simple 'Purchase Request' to our payment gateway to initiate the transaction, and Mint completes the rest of the process. The shopper will be returned to the merchant's website with the results of the online payment request. This service is hosted on the Mint’s Payment Servers, which are fully PCI DSS certified and secure, so the merchant is not required to have their own SSL certificate.
Integration with Merchant Website
Company Token
Company Token is a very important concept and must be provided while initiating the payment. This token uniquely identifies the merchant within the Mint’s payment system.
The Mechanics
Interacting with the HPP can be done in two ways:
-
HTTP POST Request (preferred):
- The input parameters (see table below) will be passed as hidden parameters of the HTTP request.
- The URL of POST request will look like
https://hpp-uatsb.mintpayments.net/<companyToken>
-
HTTP GET Request:
- In this case, the URL would need to contain all the necessary parameters in a form of
https://hpp-uatsb.mintpayments.net/<CompanyToken>[email protected]&amount=10000&reference1=REF-1234&reference2=INV-1234&redirectUrlMerchant=https://integratedposdev.mintpayments.net/hpp/confirm/beginTransaction
- In this case, the URL would need to contain all the necessary parameters in a form of
There are also two ways of providing payment parameters for the payment transaction:
- Passing payment parameters (internal reference, invoice number, amount, etc.) while making the call. In that case, the values will be auto-populated on the HPP on behalf of the user.
- Simply call the HPP with no values. In that case, the user would need to enter the payment details directly into the HPP.
Input Parameters
All input parameters are strings.
Choosing how to pass parameters to the HPP fully depends on the level of integration that needs to be achieved. If your system generates the internal references and/or invoice numbers and you don't want the customer to be able to override them, then the values should be passed to the HPP.
| Visual fields on HPP | Key (in the HTTP request) | Notes | Example |
|---|---|---|---|
| Payment Amount | amount | Amount in cents. E.g. 10000 means $100.00 | 10000 |
| Email Receipt to | Email address to where a payment receipt will be sent. Mostly customer’s email address | [email protected] | |
| Customer Reference | reference1 | Merchant internal customer reference | REF-1234 |
| Invoice No. | reference2 | Merchant internal invoice number | INV-1234 |
| N/A | requestHash | Optional for ensuring data integrity. | 2GajOzeYI3PVB4S84Ni4d+tYX4ya06dxYhsSdgyOvNA= |
| N/A | redirectUrlMerchant | This value is not shown on the HPP. This URL will be redirected to upon completion of the payment. If left out, no redirection will happen | https://customer.net/hpp/confirm/transaction |
| N/A | redirectTarget | Controls the way the confirmation page will be displayed. Only relevant if ‘redirectUrlMerchant’ passed | _blank, _self, _parent, _top, framename |
| N/A | storeCardPermission | If true, the system will tokenize the card and return the token in the response | true/false |
| N/A | virtualTerminalMode | Flag passed in with the request which will process the transaction as MOTO preventing improper handling of 3DS | true/false |
Output Parameters
| Name | Notes | Example |
|---|---|---|
| transactionStatus | Describes the outcome of the payment transaction | approved/failed/declined |
| receiptNumber | Transaction’s reference number | 967017495762308097 |
| totalTransactionAmount | The total amount of the transaction processed. This might include surcharges on top of the transaction amount if the merchant chooses to apply the surcharge | 101.1 |
| errorMessage | Detailed explanation of the root cause if the transaction didn’t succeed | ‘Your payment could not be completed at this time’, ‘The daily sales limit for this company has been reached’ |
| responseHash | Optional for ensuring data integrity. | 2GajOzeYI3PVB4S84Ni4d+tYX4ya06dxYhsSdgyOvNA= |
| cardCurrency | 3-letter code of the currency of the card | NZD, AUD |
| cardNumber | Obfuscated credit card number | 411111**1111 |
| cardExpiry | Expiry date of the card | 03/22 |
| cardBrand | The flavor of the credit card | visa/master/amex |
| reference1 | The same as the input parameter reference1 | |
| reference2 | The same as the input parameter reference2 | |
| cardToken | Will contain the token of the credit card used for the last payment transaction | ab123456-abc4-123a-ab12-a12bb34c5def |
Credit Card Tokenization
The HPP allows tokenizing credit card details upon payment. If the input parameter ‘storeCardPermission’ is set to true, the system will return the card token. This might come in handy for customers who wish to use a hybrid solution of Mint’s HPP/API integration:
- Use the HPP in a fully Mint-managed PCI compliant environment to do a one-off payment and create a card token. You can safely store the card’s token on your system without any PCI-related concerns.
- Subsequent calls to Mint’s payment system can go via Mint’s mPay API using the previously tokenized card.
Verification Value for HPP
Request/Response verification is optional. If the merchant wishes to use it, Mint will share a secret key used to calculate the verification code.
Mint’s HPP mechanism allows the customer to verify that the payment response came from Mint’s system. Vice versa, Mint is able to verify the origin of the payment request really comes from the merchant.
The concept for verification is the same for request/response. The merchant (for request) or Mint (for response) will generate the code and the other party will calculate the code on the other end. Matching values of the code guarantee the request/response came from the trusted origin.
The verification code is simply a hash value out of the secret key and text:
- secret key = gD5YvCaCF5ojCXaHI2hV2xFpZ
- text = 12345678:1200
- hash = Base64(hmacSHA256(secret key, text))
- e.g., 2GajOzeYI3PVB4S84Ni4d+tYX4ya06dxYhsSdgyOvNA=
Java Snippet to Generate Hash Value
private String createHash(String hmacSecretKey, String data) throws InvalidKeyException, NoSuchAlgorithmException {
javax.crypto.Mac macService = javax.crypto.Mac.getInstance("HmacSHA256");
javax.crypto.spec.SecretKeySpec secretKeySpec = new javax.crypto.spec.SecretKeySpec(hmacSecretKey.getBytes(), "HmacSHA256");
macService.init(secretKeySpec);
return org.apache.commons.codec.binary.Base64.encodeBase64String(macService.doFinal(data.getBytes()));
}