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.
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/)
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>
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>
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>
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.
options
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 Classvar neonpay = new NeonPay(apiKey, merchantId[, options]);
Example With Swiper Onvar neonpay = new NeonPay(apiKey, merchantId, {swipe: true});
In the same script as above, declare which payment fields should appear using this method:
Define Payment Fieldsvar card = neonpay.createField('card');
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 Fieldsneonpay.mount('#cardFields');
Use the neonpay.createToken()
method to catch the payment token and complete your charges with NeonPay.
Set up Callbackneonpay.createToken(card).then(function(result) { // callback methods to handle result.error or result.token });
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.
Methodvar field = neonpay.createField(type, options);
type
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 |
options
Values | |
---|---|
style object |
Customize fields’ appearances with CSS. Style is specified as an object for the variants below:
For each of the above, the following styles can be customized.
The following pseudo-classes and pseudo-elements can also be styled with the above properties, as a nested object inside the variant.
|
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 Optionsvar 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 fieldsvar 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 });
Updates the configuration for a field. Updates are merged into any existing configuration.
Methodfield.updateField(options);
Example Usagevar options = { style: { base: { fontSize: '13px' } } }; card.updateField( options );
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.
Methodfield.mount(domElement)
Example Usagecard.mount('#paymentForm');
Unmounts the Field from the DOM. You will need to call .mount() again to re-attach fields to the DOM.
Methodfield.unmountField(domElement)
Example Usagecard.unmountField('#paymentForm');
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.
field
tokenData
Values | |
---|---|
first_name string recommended |
Cardholder first name |
middle_name string |
Cardholder middle name |
last_name string recommended |
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 recommended |
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 |
Methodneonpay.createToken(field, tokenData)
Example Usageneonpay.createToken(field).then(function(result) { // callback methods to handle result.error or result.token });
Example with Token Datavar 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 });
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.
field
Values | |
---|---|
bank_account string required |
Indicates that a bank account token should be created. |
tokenData
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’) |
Methodneonpay.createToken(field, tokenData)
Example Usagevar 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 });
You can set event listeners to catch events emitted by your fields.
event
Values | |
---|---|
blur | Triggers when the Field loses focus. |
change | Triggers when any of the following values has changed in the field:
|
focus | Triggers when the Field gains focus. |
ready | Triggers when the Field is rendered and available for interaction. |
cardbrand | Triggers when the card number field is blurred and has determined a card brand in the form an event object: {brand: 'brand name'} . The brands returned come the following list:
|
handler
Methodfield.on(event, handler)
Example Error Handlingcard.on('change', function(event) { var displayError = document.getElementById('card-errors'); if (event.error) { displayError.innerHTML = event.error.message; } else { displayError.innerHTML = ''; } });