Skip to main content

FAQ - Commonly Asked Hosted Payment Page Question

Updated

Table of Contents

 

Overview

This article covers a number of frequently asked questions regarding NMI's Hosted Payment Page solution on the CardEase platform (not to be confused with the QuickClick Hosted Payment Page). The usage of HPP in the article below refers to the Hosted Payment Page solution.

 

General

Where can I find integration documentation for the Hosted Payment Page solution?

The Integration Guide for the Hosted Payment Page solution can be found under the eCommerce section of our SDK and API's section of our EU website, at the following link.

 

Can I use real payment cards on the CardEase test/staging platform?

From a security point of view, it is not considered good practice to use real payment card data in a testing environment, and accordingly, we do not recommend it. That said, as the test platform simulates acquirer responses and is not connected to any real acquirers, funds will not be reserved or charged against a live, enrolled payment card.

If you require specific tests be performed, such as CVV or AVS validation, or 3D Secure authentication, please ensure you utilize the test cards noted in the test card Knowledge Garden article. Card details that are not registered on the test platform will pass AVS and CVV validation regardless of whether they are correct or not (i.e. any given address or CVV will be returned as Matched), so it is advisable to use a combination of test data provided by CreditCall as well as card data generated or sourced by yourself for the testing process.

It is worth noting that any test card data provided by NMI or found anywhere else will not work on any live platform. A card number that passes a Luhn algorithm check does not mean that it is enrolled with any bank or will work on a live payment platform. It is discouraged to ever use test card data on a live system.

 

How long does it take to switch from a test account to a live account?

Once NMI has received a signed merchant registration form we set up your account on our platform using the merchant account details provided by your acquirer, which can take up to 5 working days in some circumstances. Once this stage is complete we will provide you with the configuration information.

Keep in mind that it can take up to 2 weeks to register as a merchant with 3-D Secure and it is always advisable to allow as much time as possible for the switch over before going live.

 

Why do I receive errors when disabling JavaScript/Cookies?

The support of JavaScript is required by the 3-D Secure Access Control Servers and is not handled by NMI. The support of Cookies is also required for 3-D Secure and for us to maintain the cardholder's session during a transaction. Most modern internet browsers such as Google Chrome, Mozilla Firefox, and Edge have JavaScript/Cookies enabled by default.

 

Why do I receive errors when utilizing HPP via an iFrame with Safari?

Due to the Safari browser's cookie policy, using the HPP in an iFrame may cause issues outside of our control due to 3rd party Cookies being blocked. Other browsers are following this trend including Google Chrome, and as such, we do not recommend utilizing HPP via an iFrame. In the instance your solution requires an iFrame, please ensure you work around any limitations by fully redirecting to HPP and returning back to the page once completed on any browsers which do not support cookies with an iFrame.

 

Features & Functionality

Can I use the Hosted Payment Page solution to make repeat payments (without storing card details)?

HPP is primarily intended to safely capture, authenticate, and process payment card information.
However, every successful card authorization processed by HPP will return a CardEase card hash and card reference in the ekashu_card_hash and ekashu_card_reference fields, which together are commonly known as a token. Tokens can be safely stored (e.g. in a database) without coming under the scope for PCI DSS, and can be submitted to HPP to make subsequent payments from a card, without requiring the card details themselves.

This can make your application's user experience more convenient for your customers, as rather than having to enter their card details every time they want to pay, the token that refers to their card details can be retrieved from your database and passed to HPP to take payment. Rather than having to input the card number, expiry date, and Card Verification Value (CVV), you can set ekashu_card_hash and ekashu_card_reference as hidden elements in your form to the card hash and card reference associated with the customer. Other than the customer pressing pay in order to submit payment, this method essentially negates the need for cardholder interaction in this situation.

If ekashu_verification_value_verify is set to True when performing a transaction in this way, HPP will still prompt the cardholder for the CVV. This can be useful as an extra verification step to ensure that the user legitimately possesses the payment card in question, and reduces the risk of fraud and resultant chargebacks. As the card number isn’t supplied in this case, the 3-D Secure process cannot take place and is bypassed automatically.

If more flexibility over transactions is required, it is worth investigating ChipDNA Direct, the SDK on which HPP is based. In addition to accepting regular payment card information, tokenized card information returned by HPP can be processed via ChipDNA Direct, and vice versa.

Additionally, ChipDNA Direct supports the setup and management of recurring payments. While ChipDNA Direct and HPP complement each other to create a more powerful payment processing application, the use of ChipDNA Direct will increase the lead time required for integration and testing before going live.

 

Is there any way to submit data to HPP using HTTP GET instead of POST?

No. There are certain core parts of the payment page that require HTTPS POST, and GET exposes too much data that is at risk of being manipulated or edited, affecting the transaction. You can, however, pass your own reference to HPP as part of the HTML form if necessary. See the HPP integration guide for more information.

You can also specify GET data in your success/failure/callback URLs if you wish, but we strongly discourage including any sensitive data or data that could influence your site's response to the data returned by HPP.

 

How can I provide my customers with a transaction reference?

You can pass your own reference to HPP using the form field ekashu_reference. This will be returned exactly as it was posted when you are redirected back to your site after payment via HPP. Alternatively, if you prefer, you may use ekashu_transaction_id as a unique payment reference.

 

Does HPP automatically email confirmation of payment to customers?

HPP does not provide this functionality. If you wish to email customers' confirmation of a transaction, you will need to implement this yourself on your website. Naturally, you can use data returned by HPP (such as masked card number, transaction reference, etc.) to supplement the confirmation message.

 

Customization

Can I turn off/change the address fields/card logos/other elements on the payment page?

Address fields can be disabled by setting: ekashu_card_address_verify, ekashu_card_zip_code_verify, ekashu_card_address_required to False. More information on this can be found in the integration guide.

We discourage using CSS to hide elements on the page, as card scheme rules state that 3-D Secure logos and card scheme logos (including the space around them) should be present and intact on the payment page. Other than that, feel free to stylize the page how you wish.

On the test platform, HPP will display all card scheme logos. When you go live, only the card schemes in which you are enrolled to take payment will be displayed.

Note: Please bear in mind that if you hide an input field that may be required by certain cards (such as start date) NMI cannot be held responsible if errors occur when attempting to take payment.

 

Is it possible to change which fields are mandatory on the HPP page (such as CVV)?

NMI cannot change which fields are mandatory, as this depends entirely on the card scheme of the customer. If the customer doesn't enter a CVV when one is required, HPP will then prompt them to enter the valid CVV once they’ve attempted to submit the form. 

 

Hash Key/Hash Code

How do I obtain a Hash Key for use with HPP?

Email support@creditcall.com with the subject "hash key request", providing your Terminal/Seller ID and Transaction Key. We will endeavour to respond with your Hash Key within 24 working hours. Keep in mind that there will be one Hash Key provided for testing, and a separate one must be requested for live use, so please provide the relevant Terminal/Seller ID and Transaction Key. Test Terminal/Seller IDs commonly begin with a 9, and live IDs with a 2.

 

How do I generate an ekashu_hash_code?

Please reference either the HPP Integration Guide or our Knowledge Garden article, which contains full details on how to generate and check HPP's Hash Code.

 

What is the difference between ekashu_hash_code and ekashu_hash_code_result?

ekashu_hash_code_result is similar to ekashu_hash_code except that it validates the response from HPP after a transaction has been processed.

A Hash Code can be generated by your own application that can be used to validate against the ekashu_hash_code_result returned by HPP. When produced correctly, the user-generated Hash Code will be an exact match. This will prevent a user tampering with the POST data, for example fooling your website into registering a transaction as successful when it had actually failed or been declined (also known as a man-in-the-middle attack).

 

Callbacks

What is the difference between a success/failure URL and a success/failure callback URL?

The ekashu_success_url and ekashu_failure_url fields redirect the customer's browser back to the specified page upon a successful or failed transaction. The callback URLs (ekashu_callback_success_url and ekashu_failure_url) send data to a specified page behind the scenes, usually to execute a script (specified by the URL) that makes use of the data returned by HPP when a transaction takes place.

If a callback fails, our servers will retry a callback after 1 minute, then 2 minutes, then 4 minutes, and so on, until it is successful (HTTP code 200), or up to a maximum of 3 days. This process is intended to be used as a failsafe should the customer's browser fail to redirect back to the success or failure page. A brief example of this feature would be a script that automatically closes a customer's order and emails them confirmation of the transaction once the callback has been performed.

 

If I specify a callback URL as well as a redirect URL, is the same information posted to both?

Yes, when the ekashu_include_post field is set to True. See the HPP integration guide for more information.

 

Why is my callback URL not doing anything even when a transaction is successfully processed by HPP?

This issue often arises when the callbacks are directed to the URL of a server behind a firewall, for instance, an in-house development server. If you think that this is the case, please contact support@creditcall.com and we will provide you with the IP addresses that need to be added as exceptions to your firewall’s rules. Our firewalls do not support callbacks on any ports other than 443 and 80.

Also, keep in mind that local server IP addresses or localhost will not work as the HPP servers will not know where to direct the callback. Our servers are configured to reattempt failed callbacks after a set period of time, up to a maximum limit, in order to minimize a loss of information should there be a connection issue between our servers and your site.

Finally, your callback script should expect POST data to be returned by HPP, although you can specify GET parameters in the callback URL if necessary.

 

Common Errors & Warnings

How can I force HPP to fail/decline a transaction during testing?

The simplest way to do this is to utilize the CardEase Platform Special Amounts, and process a transaction with an amount of 5.00 or 6.00 which will force a transaction response of declined.

 

If a payment is declined, is it possible to inform the user why?

Our payment page performs routine validation checks of your request and of the customer's card details, to ensure the card number is valid (Luhn check), that the expiry date is in the future, and so on. If an issue is detected prior to any transaction being sent online to the acquirer, HPP will display the error reason either prior to the request being made, or post request if there is an issue with the card details. For example, if a payment fails due to a failure to validate the card details (incorrect format, communication failure, etc.), HPP will return the relevant error message.

If the acquirer provides a declined payment response, the reason for the declined is often not provided. You can utilize WebMIS to check the transaction details, however, if a generic decline reason is provided, such as Do Not Honor, then you will need to reach out to your acquirer for more information as to the decline cause, as NMI will not have visibility into the reason provided by the acquirer.

 

HPP returns the error Invalid POST form field value for: ekashu_seller_id and/or Invalid POST form field value for: ekashu_seller_key.

Your ekashu_seller_key is the first eight characters of the Transaction Key provided to you upon registration to Test WebMIS (on our test platform), or by our Live Support team during the boarding process on our live platform. Your ekashu_seller_id is the Terminal ID provided in the same way (registration on Test WebMIS or via our Live Support team for live boarding).

If you haven’t signed up for a Test WebMIS account, then you can do so at https://testwebmis.creditcall.com/registration.php.

If you have registered on Test WebMIS but don't know your Terminal ID and Transaction Key, first check your email inbox/spam folder for an email from noreply@creditcall.com and see if the initial registration email is there. If not, contact support@creditcall.com.

Remember: There are two different pairs of Terminal ID and Transaction Key for each platform: test, and live. They are not interchangeable between the test and live platforms. To obtain live credentials, you will need to contact your NMI Account Manager about our boarding procedures. In most cases, live Terminal IDs start with 2, and test Terminal IDs start with 9.

 

HPP responds with the error The seller cannot accept a payment this high/low.

On the test platform, the maximum transaction amount is 130 major units (e.g. $130, £130, €130 etc.), and the minimum transaction amount is 0.25 major units (e.g. 25¢, 25p etc.). On the live platform, these limits can be configured to whatever you like when setting up your merchant account. The default limit is between 0.50 major units and 100.00 major units. If you need your minimum/maximum limits altered on the live platform, please contact support@creditcall.com.

Please note: we cannot change the transaction amount limit on the test platform, as it can cause other integrator's tests to fail unexpectedly.