hps / heartland-tokenization

SecureSubmit Tokenization Library

SecureSubmit Tokenization Library

PCI Friendly Card Tokenization

This plugin allows you to use your SecureSubmit Public API Key to convert a credit card into a secure Token which can be charged in a PCI friendly way.

Refer to the Heartland Payment Systems SecureSubmit website for examples.

Usage

<script src='https://api2.heartlandportico.com/SecureSubmit.v1/token/2.4.1/securesubmit.js'></script>

Building from source

$ npm install
$ npm run build

npm run build will perform the following tasks:

1. Clean the ./dist/ directory.
2. Builds the Typescript files into ./dist/securesubmit.js using tsconfig.json.
3. Lints the Typescript files according to tslint.json.
4. Minifies ./dist/securesubmit.js into ./dist/securesubmit.min.js.
5. Copies the needed field.html and index.html files into ./dist/.

Development

The tokenization library is built in Typescript. The Typescript compiler is available as an add-on for Visual Studio, but it can also be installed independently. This library's package.json file also pulls down a copy of the Typescript compiler on npm install, which allows it to be used by calling ./node_modules/bin/tsc.

Watch files during development

This will compile changes to ./dist/securesubmit.js but will not update the minified ./dist/securesubmit.min.js.

$ npm run watch

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

heartland-tokenization's Issues

allow changing the date format used in Heartland.Card.formatExpiration?

Distrusted SSL certificate on Chrome

When I include the script

<script src="https://api2.heartlandportico.com/SecureSubmit.v1/token/2.1/securesubmit.js"></script>

I get the following warning on Chrome 63

According to these docs, on April 2018, the cert will be distrusted in Chrome. Any thoughts?

timeout issue

I call hps.tokenize method and pass two callbacks for "success" and "error". When the tokenization request fails with timeout nor "success" neither "error" functions gets triggered.

Suport external event handler for iframe events

Two cases should be supported if possible:

• Allows integrator code to know a field's validity (.valid/.invalid) and any information related to the field's value (e.g. .card-type-{brand})
• Allow integrator code to register handler functions on input events (focus, blur, etc.). This may be tricky due to postMessage/browser security limitations.

JSON2 not compatible with Content Security Policy

When trying to lock down a project I'm working on to avoid script injection, I ran into a problem securing a credit card entry page. The Secure Submit library bundles JSON2, which -- after screening them for illicit payloads -- turns JSON documents into real JavaScript with eval(). Secure Submit then uses JSON2 directly, without checking if the browser builtin JSON is present.

Adding a Content Security Policy makes eval() raise an error. This is intended behavior: code that's being evaled can come from anywhere, even (especially) malicious actors -- the very people we want to secure credit card entry forms from. This can be overcome by adding unsafe-eval to the policy, but that basically nullifies all the security the policy provides. We want to be able to specify a reasonable, safe policy.

All browsers released since 2010 (IE 8+, Firefox 3.5+, Safari 4+, and all versions of Chrome and Edge) have a safe JSON object available to use, and earlier browsers can't use Secure Submit anyway as they don't support the version of TLS that Heartland requires. Please consider removing the JSON2 library and reimplementing that functionality in terms of the browser builtin.

Getting single-use token for random numbers as card number

We have integrated the heartland using tokenization method, the basic validations are working fine(like card numbers, cvv, expiration), but when random numbers such as 0000000000 are entered in card number field, keeping cvv and exp date fields as empty, then also getting single use token.

Is this expected behaviour ? How to test negative scenarios?

Untrusted SSL Certificate - Mozilla/Google products

See #51, @slogsdon @russelleverett is there any way you can reach out to the ops team or whoever is in charge of this and have them get a certificate issued by someone other than Symantec? It is now untrusted by both Mozilla and Google in the latest versions of FF/Chrome.
See: https://www.ssllabs.com/ssltest/analyze.html?d=api2-c.heartlandportico.com

Handle message event data from other sources

Throws error if not JSON

Ajax.jsonp error handling

Please add a way to detect if there is an issue with loading the requested payload into the script tag that this method creates and appends to the body, especially if the call to the requested payload link returns a server error.

            script.src =
                request.url +
                (request.url.indexOf("?") >= 0 ? "&" : "?") +
                "callback=" +
                callbackName +
                "&" +
                request.payload;
            document.body.appendChild(script);

In encountered an issue earlier today when attempting to test the tokenization using https://cert.api2.heartlandportico.com and each response was a server error.

Currently if such an error occurs, there is no error returned in the callback and it cannot be captured on the client side.

hps.setText allows script injection

Using hps.setText it is possible to replace the form inside the <iframe>:

hps.setText('heartland-cvv-label', '<script>alert("hello");</script>')

Emit events when validating fields

Could you emit events about field validation at the same time that the .valid and .invalid classes are set? For example:

    var hps = new Heartland.HPS({
      publicKey: 'pkapi_cert_jKc1FtuyAydZhZfbB3',
      type:      'iframe',
      // Configure the iframe fields to tell the library where
      // the iframe should be inserted into the DOM and some
      // basic options
      fields: {
        cardNumber: {
          target:      'iframesCardNumber',
          placeholder: '•••• •••• •••• ••••',
          onValidation: function(isValid, cardType) {
            // Update UI knowing if card is valid and which card type is used
          }
        },
        ...
      },
     ...
    });

This would help immensely in making our UI as functional with iFrames as it was before.

Thanks!

React to window.postMessage deprecation in Chrome

I saw this recently when using a script with window.postMessage calls:

window.postMessage(message, transferables, targetOrigin) is deprecated and will be removed in M54, around October 2016. Please use window.postMessage(message, targetOrigin, transferables) instead. See https://www.chromestatus.com/features/5719033043222528 for more details.

The preferred function signature will need to be tested across our supported browsers.

Allow for expiration date to be select fields for month/year

Add 'possibly-valid' class

Currently there are "valid" and "invalid" classes but this does not allow for a way to style the element while input is still being added any differently than "invalid" input which is not a great user-experience. Adding a third class like "possibly-valid" would allow more styling flexibility and to fix this issue.

For example I currently have something like this:

        '#heartland-field.invalid': {
            'color': '#a94442',
            'border-color': '#a94442'
        },

The color of the field is red immediately as the customer starts entering the number. If the "possibly-valid" class was added then we could do this:

        '#heartland-field.invalid': {
            'color': '#a94442',
            'border-color': '#a94442'
        },
        '#heartland-field.possibly-valid.invalid': {
            'color': '#959595 !important',
            'border-color': '#959595 !important'
        },

This should not break any existing integrations unless perhaps they did not use a safe method of checking the class names array passed through events.

The logic for determining "possibly valid" would be to match a regex that indicates fewer than required number of digits or just checking the string length.

• Card numbers: For Amex prefixes less than 15 digits, for all others less than 16 digits are possibly valid. One digit can be always considered possibly valid and greater than two digits is possibly valid only if the type can be determined.
• Exp month: A 0 or 1 is possibly valid
• Exp year: Less than four digits is possibly valid
• Cvv: For Amex less than 4 digits, for all others less than 3 digits are possibly valid

Since the fields are hosted on your own servers this is not something I can add to a locally modified version. Is this something you could add for me and if so, hopefully pretty soon? We had to go ahead and go live for PCI compliance but our UX is not what we want it to be yet.

Thanks,
Colin

Can't access documentation outside of US

We're a UK development team working on an integration for a US client and it's impossible to access the developer documentation at https://developer.heartlandpaymentsystems.com/SecureSubmit/Documentation from an IP address outside the US.

What's the point of this? We have to use a VPN just to view the docs. It's incredibly frustrating and short-sighted.