GuidesTokenization

Runner.js

Runner.js Overview

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.

The library is continually updated to support the gateways available through Run Developer and to provide more flexibility to you, our integrated partners. If you have any feedback or questions about the service, please reach out to us at integrations@runpayments.io

Runner.js Parameters

The following table is a list of possible parameters that can be passed when calling Runner.js to tokenize a customer’s payment account:

AttributeDescriptionAccount TypesRequired
elementID (with #) of the element where to load the card number/CVV fields (iframe) or the account/routing number in case of ACHAllYes
publicKeyYour Public key linked to your accountAllYes
cssStyling that will get applied to the iframe (account number/cvv) fields in case of card entry. Please send bot url encoded version or JS objectAllNo
envPossible values: local (requests sent to localhost:8000), staging (requests sent to javelin-staging env), production (requests sent to Run/Javelin production)AllNo
useExpiryIf true, it will render expiry month/year fieldsCardNo
useCvvIf true it will render the cvv fieldCardNo
cardLabelSet your own label for the card number input fieldCardNo
cvvLabelSet your own label for cvv fieldCardNo
expiryLabelSet your own label for expiry fieldCardNo
`cardPlaceholder“Placeholder text for card number fieldCardNo
cvvPlaceholderPlaceholder text for cvv fieldCardNo
accountNumberPlaceholderPlaceholder text for account number fieldACHNo
routingNumberPlaceholderPlaceholder text for routing # textACHNo
repeatedAccountNumberPlaceholderPlaceholder text for repeated account # fieldACHNo
accountNumberLabelCustom label for account number fieldACHNo
routingNumberLabelCustom label for routing number fieldACHNo
repeatedAccountNumberLabelCustom label for repeated account number labelACHNo
accountTypeLabelCustom label for account type (IStream)ACHNo
customerNameLabelCustom label for customer name (IStream)ACHNo
entryClassCodeLabelCustom label for entry class code (Istream)ACHNo
tokenizeAutomaticallyIf you want Runner.js to call tokenize after user stops typing instead of using onBlur event. Default falseAllNo
inactivitytoHow long to wait (in ms) for tokenize to be called. Works only if tokenizeAutomatically is set to true. Default 300AllNo
errorsMapURL encoded JS object of custom errors that you can supply to override default error messages. Only applies to ACH form and card connect gateway.Example: URL encoded the following object{"1": "Account number is required","2": "Account number repeat does not match","3": "Routing number is required","4": "Routing number must be 9 digits","5": "Account type is required","6": "Customer name is required",};AllNo
errorTypeAbility to choose the way errors are displayed in ACH form (applies only to card connect gateway). Possible values: field - errors will be shown below each invalid input fieldlist - errors will be shown as unordered list at the top of the formAllNo

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>