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
cardPlaceholderPlaceholder text for card number fieldCardNo
cvvPlaceholderPlaceholder text for cvv fieldCardNo
accountNumberPlaceholderPlaceholder text for account number fieldACHNo
routingNumberPlaceholderPlaceholder text for routing number fieldACHNo
repeatedAccountNumberPlaceholderPlaceholder text for repeated account number 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). Valid account type values are 1, 2, and 3 (Checking, Saving, and Ledger).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',

Example:

JavaScript
1var runner = new Runner();
2    runner.init({
3      element: '#run-form',
4      publicKey: '<public key>',
5      mid: '<option mid to route to>',
6      useExpiry: true,
7      useCvv: true,
8      cardLabel: 'label',
9      cvvLabel: 'cvv label',
10      expiryLabel: 'Expiration Date<b> (MM/YYYY) </b>',
11      inactivityto: 300,
12      cardPlaceholder: 'Card Number #',
13      cvvPlaceholder: 'CVV #'
14});
15
16runner.onTokenize (function (runnerResult) {
17    console.log(`tokenized: ${JSON.stringify(runnerResult)}`);
18});
19
20document.querySelector('#paybutton').onclick = () => {
21      var successElement = document.querySelector('.success');
22      var errorElement = document.querySelector('.error');
23      var loaderElement = document.querySelector('.loader');
24
25      successElement.classList.remove('visible');
26      errorElement.classList.remove('visible');
27      loaderElement.classList.add('visible');
28
29      var form = document.querySelector('form');
30
31      var extraDetails = {
32        amount: 10000,
33        name: form.querySelector('input[name=cardholder-first-name]').value + ' ' + form.querySelector('input[name=cardholder-last-name]').value,
34        company_name: 'acme',
35        email: '',
36        phone: form.querySelector('input[name=phone]').value,
37        address1: "4547 East Thompson Street'",
38        address2: '1234',
39        address_city: 'Orlando',
40        address_state: 'FL',
41        account_zip: '32811',
42        address_country: 'USA',
43        order_id: '100',
44        capture: 'Y',
45      
46      };
47
48runner.tokenize((res) => {
49        var xhr = new XMLHttpRequest();
50        xhr.open("POST", 'http://<your backend url>' + '/charge', true);
51        xhr.setRequestHeader('Content-Type', 'application/json');
52
53var params = JSON.stringify({
54          ...extraDetails,
55          account_token: res.account_token,
56          expiration: res.expiry,
57        
58        });
59
60xhr.onreadystatechange = function() {
61            if (xhr.readyState == XMLHttpRequest.DONE) {
62                var resp = JSON.parse(xhr.responseText);
63                console.log(resp);
64
65                if (resp['trans_id']) {
66                  successElement.querySelector('.token').textContent = resp['trans_id'];
67                  successElement.classList.add('visible');
68                  loaderElement.classList.remove('visible');
69                } else {
70                  errorElement.textContent = typeof resp === 'object' ? (resp && resp.error) || Object.keys(resp).map((k) => resp[k].join(' ')).join(' ') : JSON.stringify(resp);
71                  errorElement.classList.add('visible');
72                  loaderElement.classList.remove('visible');
73                }
74            }
75        }
76
77        xhr.send(params);
78
79      })
80    };

Full HTML example:

Example:

HTML
1<form onsubmit="return false;">
2      <div class="group">
3        <label>
4          <span>First Name</span>
5          <input
6  name="cardholder-first-name" class="field input-box" placeholder="Jane" />
7        </label>
8        <label>
9          <span>Last Name</span>
10          <input name="cardholder-last-name" class="field input-box" placeholder="Doe" />
11        </label>
12        <label>
13          <span>Phone</span>
14          <input name="phone" class="field input-box"  placeholder="+1000000000000" />
15        </label>
16      </div>
17      <div class="group" style="height: 200px;">
18        <label>
19          <span>Card</span>
20          <div id="card-element" class="field">
21            <div id="run-form"></div>
22          </div>
23        </label>
24      </div>
25      <button id="paybutton">Pay</button>
26      <div class="outcome">
27        <div class="error"></div>
28        <div class="success">
29          Successful! The Result is
30          <span class="token"></span>
31        </div>
32        <div class="loader" style="margin: auto">
33        </div>
34    </form>
35
36
37
38
39
40### Cybersource Gateway
41
42If on your form there is a div like this:
43
44```jsx
45 <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>

CYBS Gateway

The CBYS gateway uses custom field selectors for the card number and CVV iframes, and native <select> elements for expiration month/year. Pass the selectors via cardNumberFieldSelector and cvvFieldSelector in the runner.init call.

Example:

1<form onsubmit="return false;">
2  <div id="card-number-cybs"></div>
3  <select id="exp-month-cybs">
4    <option value="01">01</option>
5    <option value="02">02</option>
6    <option value="03">03</option>
7    <option value="04">04</option>
8    <option value="05">05</option>
9    <option value="06">06</option>
10    <option value="07">07</option>
11    <option value="08">08</option>
12    <option value="09">09</option>
13    <option value="10">10</option>
14    <option value="11">11</option>
15    <option value="12">12</option>
16  </select>
17  <select id="exp-year-cybs">
18    <option value="2026">2026</option>
19    <option value="2027">2027</option>
20    <option value="2028">2028</option>
21    <option value="2029">2029</option>
22    <option value="2030">2030</option>
23  </select>
24  <div id="cvv-cybs"></div>
25
26  <input type="hidden" id="mytoken" />
27
28  <button id="paybutton">Pay</button>
29
30  <div class="outcome">
31    <div class="error"></div>
32    <div class="success">
33      Successful! The Result is
34      <span class="token"></span>
35    </div>
36    <div class="loader" style="margin: auto"></div>
37  </div>
38</form>

Payroc Gateway

The Payroc Gateway implementation requires specific field selectors and configuration options to properly handle form validation and tokenization.

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      <div class="card-holder-name"></div>
7      <div class="card-holder-name-error error-message"></div>
8      <label>
9        <span>Phone</span>
10        <input name="phone" class="field input-box"  placeholder="+1000000000000" />
11      </label>
12      <label>
13        <span>Vault ID</span>
14        <input name="vault_id" class="field input-box"  placeholder="" />
15      </label>
16    </div>
17    <div class="group" >
18      <label id="cardNumber-label">Card Number</label>
19      <div id="cardNumber-container"></div>
20      <div id="cardNumber-error"></div>
21    </div>
22    <div class="group cvv-wrapper" >
23      <label id="securityCode-label">Cvv</label>
24      <div id="securityCode-container"></div>
25      <div id="securityCode-error"></div>
26    </div>
27
28    <div class="group">
29      <label>
30        <span>Expiration</span>
31        <div id="expiration-container"></div>
32        <div id="expiration-error"></div>
33      </label>
34    </div>
35
36    <div id="pay-button"></div>
37    <div class="outcome">
38      <div class="error"></div>
39      <div class="success">
40        Successful! The Result is
41        <span class="token"></span>
42
43      </div>
44      <div class="loader" style="margin: auto">
45      </div>
46    </div>
47  </form>
48</div>

ACH (iStream and Fiserv ACH)

Both iStream and Fiserv ACH gateways provide bank account tokenization with customizable field labels and validation. The implementation supports automatic or manual tokenization depending on your requirements.

1<div id="pay-example">
2  <form id="my-sample-form" onsubmit="return false;">
3    <div id="run-form"></div>
4    <div class="group">
5      <label>
6        <span>Customer Name</span>
7        <input name="customer_name" class="field input-box" placeholder="John Doe" />
8      </label>
9    </div>
10    <button id="pay-button">Process ACH Payment</button>
11    <div class="outcome">
12      <div class="error"></div>
13      <div class="success">
14        Successful! The Result is
15        <span class="token"></span>
16      </div>
17      <div class="loader" style="margin: auto"></div>
18    </div>
19  </form>
20</div>

iStream — Full Page Example

The following is a complete iStream ACH implementation using native HTML elements for account type and customer name. The accountTypeField and customerNameField parameters wire Runner.js directly to those elements — no separate label rendering is needed. The last4 of the account number is captured from the tokenization message event and can be used for display or reconciliation.

iStream does not apply CSS sanitization to the hosted iframe fields. Styles passed via the css parameter are applied directly.

1<!doctype html>
2<html lang="en">
3  <body>
4    <div id="run-form"></div>
5
6    <div>
7      <label>Account Type</label>
8      <select id="account-type">
9        <option value="">Select Account Type</option>
10        <option value="1">Checking</option>
11        <option value="2">Savings</option>
12        <option value="3">Ledger</option>
13      </select>
14    </div>
15
16    <div>
17      <label>Customer Name</label>
18      <input type="text" id="customer-name" placeholder="Account Holder Name">
19    </div>
20
21    <script src="https://javelin.runpayments.io/javascripts/1.5.5/runner.js"></script>
22    <script>
23      var runner = new Runner();
24
25      let last4;
26      window.addEventListener('message', (event) => {
27        const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
28        if (data.extras?.last4) {
29          last4 = data.extras.last4;
30        }
31      });
32
33      runner.onTokenize((res) => {
34        var xhr = new XMLHttpRequest();
35        xhr.open('POST', 'https://example.com/charge', true);
36        xhr.setRequestHeader('Content-Type', 'application/json');
37
38        xhr.onerror = function (err) {
39          // handle error here
40        };
41
42        var params = JSON.stringify({
43          account_token: res.token,
44          mid: '<YOUR_MID>',
45          amount: 10000,
46          name: document.getElementById('customer-name').value,
47          account_number: `XXXXXXXXXX${last4}`,
48          payment_description: 'payment',
49          entry_class: 'TEL', // SEC Code: CCD, PPD, TEL, or WEB
50          // ach_discretionary_data: 'S' // required for WEB; 'S' = single, 'R' = recurring
51        });
52
53        xhr.onreadystatechange = function () {
54          if (xhr.readyState == XMLHttpRequest.DONE) {
55            var resp = JSON.parse(xhr.responseText);
56            if (resp['trans_id']) {
57              console.log(resp['trans_id']);
58            } else {
59              // handle error here
60            }
61          }
62        };
63
64        xhr.send(params);
65      });
66
67      runner.init({
68        element: '#run-form',
69        publicKey: '<YOUR_PUBLIC_KEY>',
70        accountTypeField: 'account-type',
71        customerNameField: 'customer-name',
72      });
73    </script>
74  </body>
75</html>