neonpay.js

v1.1

neonpay.js is used to provide client-side tokenization of credit card data for NeonPay. In this guide, we explain how to implement this in your web application.

Quick Start


Generate a public API key for your app in NeonPay

As a application administrator, you can generate and revoke public API keys from the Developer Tools page in the NeonPay portal. This public API key is different from the private API key you use to access the NeonPay Charge API.

When starting development, you will need a public API key from NeonPay Sandbox (https://sandbox.neononepay.com/) to develop against the development version of the tokenization library.

For your production script, you will need a public API key from NeonPay (https://app.neononepay.com/)

Sample Script

We strongly recommend that you include fields in your payment form to collect your customer’s first name, last name, and address. Once you have that information collected, you can pass it as part of the tokenData parameter in .createToken() API method to create a more complete payment token.

Quickstart Example
<form id="paymentForm" action="#" method="POST"> <h2>Payment Form</h2> <div id="cardFields"></div> <input type="hidden" id="token" value="" /> <input id="paymentSubmit" type="submit" value="Process Payment" /> <button id="swipe" type="button" name="button">Swipe</button> </form> <script src="https://cdn.sbx.neononepay.com/1.1/neonpay.js"></script> <script type="text/javascript"> // Set up the NeonPay fields on your form var neonpay = new NeonPay('public_f8564752122b08cc9c20c374562d5cc7', '19', {swipe: true}); var card = neonpay.createField('card'); card.mount('#cardFields'); var paymentForm = document.getElementById('paymentForm'); var tokenField = document.getElementById('token'); // Intercept form submission and retrieve token paymentForm.addEventListener('submit', function (event) { event.preventDefault(); var tokenData = { first_name: 'Robert', middle_name: 'Norman', last_name: 'Ross', email: 'bob@ross.net', phone: '+18888606366', address_line_1: '4545 N. Ravenswood Ave.', address_line_2: '2nd Floor', address_city: 'Chicago', address_state: 'IL', address_zip: '60640', address_country: 'US' }; var token = neonpay.createToken(card, tokenData).then(function(result) { // Pass the token to your Charge API call using // a hidden input that your form will serialize // or to an intermediary API on your server if (result.token) { tokenField.value = result.token; } }); }); </script>

Step-by-Step Guide

1. Include neonpay.js

Include the NeonPay JS library in your payment form.

Include NeonPay.js
<script src="https://cdn.app.neononepay.com/1.1/neonpay.js"></script>

If you are developing in the Sandbox environment, your script will be:

NeonPay.js for Sandbox
<script src="https://cdn.sbx.neononepay.com/1.1/neonpay.js"></script>

2. Create DOM Elements

Add a container field where you wish NeonPay to populate the payment fields on your page. Be sure to give it a unique HTML id attribute so that you can target it directly.

Create DOM Elements
<div id="cardFields"></div>

3. Generate the NeonPay class

In a <script> that runs on page load, create an instance of the NeonPay object. You must provide your Public API Key and your Merchant ID, which can be retrieved from the NeonPay merchant portal.

Argument: options

Object
The object may contain the keys defined below:
Values
swipe
boolean
Allows for transactions via the use of a supported magnetic card swiper/reader. You must have a button with the id of "swipe" inside your payment form.
Generate NeonPay Class
var neonpay = new NeonPay(apiKey, merchantId[, options]);
Example With Swiper On
var neonpay = new NeonPay(apiKey, merchantId, {swipe: true});

4. Define Payment Fields

In the same script as above, declare which payment fields should appear using this method:

Define Payment Fields
var card = neonpay.createField('card');

5. Mount Payment Fields

Call this method to place your payment fields inside the previously created DOM element. The fields will be added as iFrames to your page.

Mount NeonPay Fields
neonpay.mount('#cardFields');

6. Set up Callback Method

Use the neonpay.createToken() method to catch the payment token and complete your charges with NeonPay.

Set up Callback
neonpay.createToken(card).then(function(result) { // callback methods to handle result.error or result.token });

API Documentation

Create Field

When displaying card fields using this method, you can choose either to use the type of card to display a single consolidated field that collects card number, expiration, and cvc, or else you can display those fields individually by calling this method three times with a different type.

Method
var field = neonpay.createField(type, options);

Argument: type

Required String
Use one of the values below:
Values
card A set of fields for credit card entry, including card number, card expiration, card CVC, and postal code.
cardNumber Credit card number field
cardExpiration Credit card expiration field
cardCvc Credit card CVC number field

Argument: options

Object
The object may contain the keys defined below:
Values
style
object

Customize fields’ appearances with CSS. Style is specified as an object for the variants below:

  • base: all variants inherit from this style
  • complete: applied when the field has valid input
  • empty: applied when the field has no input
  • invalid: applied when the field has invalid input

For each of the above, the following styles can be customized.

  • color
  • fontFamily
  • fontSize
  • fontSmoothing
  • fontStyle
  • fontVariant
  • fontWeight
  • letterSpacing
  • textAlign
  • textDecoration
  • textShadow
  • textTransform

The following pseudo-classes and pseudo-elements can also be styled with the above properties, as a nested object inside the variant.

  • :hover
  • :focus
  • ::placeholder
  • :disabled
value
object
Available if type parameter is card. You may pre-fill field values (e.g., {postalCode: ‘90210’}). You may not prefill card data like number and expiration date due to data protection concerns.
hidePostalCode
boolean
Only available if type parameter is card. Hide the postal code field. Defaults to false. If you are collecting full billing information elsewhere on your payment form, you can set this to true.
hideBorders
boolean
Hides the default border styling for card fields.
disabled
boolean
Applies a disabled state to the field so that it prevents user input. Defaults to false.
placeholder
string
Available if type parameter is not card or cardExpiration. Customize the field’s placeholder text.
Example with Options
var card = neonpay.createField('card', { style: { base: { color: '#46a0ba', '::placeholder': { color: '#000' } }, invalid: { color: 'yellow' } }, value: { postalCode: '60613' }, hidePostalCode: false, disabled: false });
Example with separate card fields
var styleObject = { base: { fontFamily: 'Open Sans, sans-serif', color: '#46a0ba' } }; var cardNumberField = neonpay.createField('cardNumber', { style: styleObject, placeholder: 'Enter card number', disabled: false }); var cardExpirationField = neonpay.createField('cardExpiration', { style: styleObject }); var cardCvcField = neonpay.createField('cardCvc', { style: styleObject });

Update Field

Updates the configuration for a field. Updates are merged into any existing configuration.

Method
field.updateField(options);
Example Usage
var options = { style: { base: { fontSize: '13px' } } }; card.updateField( options );

Mount Field

You need to first create a container DOM element to mount a Field. After mounting, the method will attach the Field to the specified DOM element, causing the field to display on your page.

Method
field.mount(domElement)
Example Usage
card.mount('#paymentForm');

Unmount Field

Unmounts the Field from the DOM. You will need to call .mount() again to re-attach fields to the DOM.

Method
field.unmountField(domElement)
Example Usage
card.unmountField('#paymentForm');

Create Token

Use the createToken() method to convert the information collected by the payment fields into a payment token that you can safely pass to your server to use in a Charge API call.

Argument: field

Required object
This object is the payment field(s) previously declared and mounted by your script. The information from field will be tokenized in preparation for charging.

Argument: tokenData

object
This object contains additional payment information you may have collected in the rest of your payment form. It may contain the following information:
Values
first_name
string
Cardholder first name
middle_name
string
Cardholder middle name
last_name
string
Cardholder last name
address_line_1
string
Cardholder billing address line 1
address_line_2
string
Cardholder billing address line 2
address_city
string
Cardholder billing address city
address_state
string
Cardholder billing address state
address_zip
string
Cardholder billing address zip code
address_country
string
Cardholder billing address country. Two character ISO country code (e.g., ‘US’)
email
string
Cardholder email address
phone Cardholder phone number
Method
neonpay.createToken(field, tokenData)
Example Usage
neonpay.createToken(field).then(function(result) { // callback methods to handle result.error or result.token });
Example with Token Data
var tokenData = { first_name: 'Robert', middle_name: 'Norman', last_name: 'Ross', email: 'bob@ross.net', phone: '+18888606366', address_line_1: '4545 N. Ravenswood Ave.', address_line_2: '2nd Floor', address_city: 'Chicago', address_state: 'IL', address_zip: '60640', address_country: 'US' } neonpay.createToken(field,tokenData).then(function(result) { // callback methods to handle result.error or result.token });

Create Token (Bank Account)

Bank account information can also be tokenized with this method. Use createToken() with a ‘bank_account’ flag parameter to request a bank account token to pass to the Charge API.

Argument: field

Required string
Values
bank_account
string
required
Indicates that a bank account token should be created.

Argument: tokenData

Required object
This object contains bank account fields collected from the rest of your payment form:
Values
routing_number
string
required
The bank account routing number
account_number
string
required
The bank account number
account_holder_first_name
string
required
The first name of the account holder
account_holder_last_name
string
required
The last name of account holder
account_type
string
required
The type of account (e.g., ‘savings’, ‘checking’, ‘corporate-checking’, ‘corporate-savings’)
country
string
Two character ISO country code (e.g., ‘US’)
Method
neonpay.createToken(field, tokenData)
Example Usage
var tokenData = { routing_number: '111000000', account_number: '000111222', account_holder_first_name: 'Robert', account_holder_last_name: 'Ross', account_type: 'checking', country: 'US' } neonpay.createToken('bank_account',tokenData).then(function(result) { // callback methods to handle result.error or result.token });

On Event

You can set event listeners to catch events emitted by your fields.

Argument: event

Required object
We attempt to validate customer input upon input. To help your customers, listen for the change event to display any errors.
Values
blur Triggers when the Field loses focus.
change Triggers when any of the following values has changed in the field:
  • empty {boolean}
  • complete {boolean}
  • error {object} - contains error message, code, and type
focus Triggers when the Field gains focus.
ready Triggers when the Field is rendered and available for interaction.

Argument: handler

Required function
This is the callback function that is called upon an emitted event.
Method
field.on(event, handler)
Example Error Handling
card.on('change', function(event) { var displayError = document.getElementById('card-errors'); if (event.error) { displayError.innerHTML = event.error.message; } else { displayError.innerHTML = ''; } });