Get Started

Tokenize with Runner.js

What is Runner.js?

Runner.js is a browser-side JavaScript library used to tokenize and send sensitive payment information directly from a user’s browser, keeping your customers’ data secure and your software fully PCI-compliant. A single integration to Runner.js can be used to handle tokenization for all supported Payments API products in Run Developer.

If you’d like to tokenize a payment account without integrating to Runner.js, log in to your Run Merchant test account and navigate to the Developer menu where you will find a card tokenizer for your merchant account. Please reach out to your Integration Delivery lead if you require assistance.

Requirements:

Before you can tokenize an account using Runner.js, you must have:

  • public_key generated in Run Merchant or provided by your Integration Delivery Lead.

Usage

  1. Add the Runner.js script to your page by adding the tag to the ‘head’ of your HTML file.
1<script src=”https://javelin.runpayments.io/javascripts/1.2.9/runner.js”></script>
  1. Initialize Runner.js using your public_key. (See Runner.js Parameters)
1var runner = new Runner();
2    runner.init({
3      element: '#run-form',
4      publicKey: '<YOUR KEY>',
5      css: 'input%7Bwidth%3A200px%3B%7D',
6      useExpiry: true,
7      useCvv: true,
8      cardLabel: 'TEST CARD LABEL',
9      cvvLabel: 'TEST CVV LABEL',
10      expiryLabel: 'TEST EXPIRY LABEL',
11      tokenizeAutomatically: true,
12      inactivityto: 200
13    });
  1. (Optional) Subscribe to iframe loaded event:
1runner.onLoaded(function() {
2      console.log('loaded');
3  });
  1. Call the tokenize method to generate tokenized account information that has been entered into the Runner.js field. The resulting value may then be passed to the Payment API to enact payment processing activities. (Note: This action can be completed during form submission, if preferred.)
1runner.tokenize(res);

The function within the tokenize call will return the following data:

ParameterDescription
account_tokenThe payment account token returned from the iFrame
expiryExpiration date (Tokenized card only)
card_infoCard brand information (Tokenized card only)
bank_infoInstitution name (Tokenized ACH only)
risk_infoBank account Risk Score (Tokenized ACH only. Please inquire with your Integration Lead if you would like to receive this data.)

Runner.js Parameters

AttributeDescriptionRequired
elementID (with #) of the element where to load the Card Number/CVV fields (iframe) or the account/routing number in case of ACHYes
publicKeyYour Public Key linked to your accountYes
cssStyling that will get applied to the iframe (Card Number/CVV) fields in case of card entry. For ACH it is ignored since account/routing fields are not part of the iframe. You may use URL-encoded or JSON CSS for this parameterNo
useExpiryIf true, render expiry month/year fieldsNo
useCvvIf true, render the CVV fieldNo
cardLabelSet your own label for the Card Number input fieldNo
cvvLabelSet your own label for the CVV fieldNo
expiryLabelSet your own label for expiry fieldNo
tokenizeAutomaticallyIf you want Runner.js to call tokenize after user stops typing instead of using onBlur event. Defaults to falseNo
inactivitytoHow long to wait (in ms) for tokenize to be called. Works only if tokenizeAutomatically is set to true. Defaults to 300No

Examples

Cardpointe Gateway

Passing Merchant ID while using the same Public Key to render the correct version of the iFrame

1    var runner = new Runner();
2    runner.init({
3      element: '#run-form',
4      publicKey: 'N1uWuiv8KneR8Rppnnt5fw2n',
5      mid: '800000001780',

Cybersource Gateway

If on your form there is a div like this:

1 <div id="cvvId"></div>

Then in the init function, you should have cvvFieldSelector: '#cvvId',

Example:

1runner.init({
2      element: '#run-form',
3      publicKey: 'TQhD2CRs9hedqYkozkdM4GnW',
4      useCvv: true,
5      cybersourceCvvField: '#cvvId',
6      cvvLabel: 'test cvv label',
7      cardLabel: 'test card label',
8      css: {
9        formContainer: {
10             'input': {
11                'font-size': '26px',
12                'color': 'red'
13              },
14        },
15        cardNumber: {
16          'input': {
17            'font-size': '16px',
18            'color': 'green'
19          },
20        },
21      }
22    });

Full HTML example:

1<div id="pay-example">
2
3  <form id="my-sample-form" onsubmit="return false;">
4  <div id="run-form"></div>
5      <div class="group">
6        <label>
7          <span>First Name</span>
8          <input name="cardholder-first-name" class="field input-box" placeholder="Jane" />
9        </label>
10        <label>
11          <span>Last Name</span>
12          <input name="cardholder-last-name" class="field input-box" placeholder="Doe" />
13        </label>
14        <label>
15          <span>Phone</span>
16          <input name="phone" class="field input-box"  placeholder="+1000000000000" />
17        </label>
18        <label>
19          <span>Vault ID</span>
20          <input name="vault_id" class="field input-box"  placeholder="" />
21        </label>
22      </div>
23      <div class="group">
24        <label id="cardNumber-label">Card Number</label>
25        <div id="cardNumber-container"></div>
26      </div>
27      <div class="group" >
28        <label id="securityCode-label">Cvv</label>
29        <div id="cvvId"></div>
30        <%# <input name="cvv" id="cvvId" class="field input-box" /> %>
31      </div>
32
33      <div class="group" >
34        <label id="exp-label">Exp month</label>
35         <input name="expmonth" class="field input-box"  placeholder="" />
36         <label id="exp-label">Exp year</label>
37         <input name="expyear" class="field input-box"  placeholder="" />
38      </div>
39
40      <div class="group">
41        <label id="exp-label">Transaction ID to capture:</label>
42      <input name="capture_id" />
43      </div>
44
45      <div class="group">
46        <label id="exp-label">Transaction ID to void:</label>
47      <input name="void_id" />
48      </div>
49
50      <div class="group">
51        <label id="exp-label">Transaction ID to refund:</label>
52      <input name="refund_id" />
53      </div>
54
55      <button id="pay-button">Pay $100</button>
56</form>
57</div>

When there is an error where the html element cannot be specified, check to ensure html includes form ID or credit card field identifier. The below must be present if using element: ‘#run-form’

<div id="run-form"></div>

Since cvvFieldSelector was omitted, runner.js will use the default #securityCode-container selector as well as the cardNumberFieldSelector if omitted, so #cardNumber-container selector should be used.

1 <div class="group">
2    <label id="cardNumber-label">Card Number</label>
3    <div id="cardNumber-container"></div>
4  </div>
5  <div class="group" >
6    <label id="securityCode-label">Cvv</label>
7    <div id="securityCode-container"></div>
8  </div>