ChargeOver.js
ChargeOver.js offers an easy, customizable, and PCI-compliant way to send data to ChargeOver via a web browser/client-side applications.
All ChargeOver.js calls are transferred from the client web browser, directly to the ChargeOver servers over an industry-standard 256-bit HTTPS/SSL connection. Credit card details, etc. are never touched or handled by your servers, which relieves you of a significant PCI-compliance burden.
Configuration
Each page you want to use ChargeOver.js on needs a few lines of configuration code to set things up. You can find the configuration code within your ChargeOver account:
- Log in to ChargeOver, and click the settings gear/cog in the top right
- Choose "Developer" from the left-side navigation menu
- Choose "ChargeOver.js"
- Enable ChargeOver.js
- Click the save button to save the configuration
The configuration code should be embedded in the <HEAD> section of your HTML page.
Example
Make sure you use your own configuration information, from your own account.
Example
JavaScript
<!--
This is an EXAMPLE configuration only
You need to get YOUR OWN CONFIGURATION from YOUR OWN CHARGEOVER ACCOUNT
<<< See the CONFIGURATION section to get these for your own ChargeOver account
-->
<script src="https://dev.chargeover.com/assets/minify/?g=chargeover.js"></script>
<script>
ChargeOver.Core.setup({
'instance': 'dev.chargeover.com',
'token': '6EILWfekvcjbiMz2F5ulDAXNrwSdp0nK'
});
</script>
Code / Libraries
Make sure to visit the ChargeOver GitHub account to see ChargeOver.js examples! Feel free to contact us for additional sample code.
Javascript
All of the examples below use Javascript. We also have additional Javascript examples on GitHub:
Sign-Ups
Sign up customers
Signing up new customers creates a customer account, creates a recurring package for that customer, and stores a credit card.
Example
Call the ChargeOver.Signup.signup(...) method to sign up a new customer.
This example does not require any payment information from the customer.
Example
JavaScript
// The data we want to send to ChargeOver
var my_data = {
'send_welcome_notice': true, // Default is FALSE. TRUE sends a welcome e-mail to new sign-ups, while FALSE will not send them anything.
'customer': {
company: 'My Company Name, LLC',
external_key: '1234abcd1234', // Use external keys to link your app to ChargeOver data
bill_addr1: '56 Cowles Road',
bill_addr2: '',
bill_addr3: '',
bill_city: 'Mt Pleasant',
bill_state: 'MI',
bill_postcode: '48858',
bill_country: 'United States',
custom_1: '', // Custom field values
custom_2: '',
custom_3: ''
},
'package': {
paycycle: 'mon', // The paycycle will default to your default payment cycle, but can be specific here instead
external_key: 'abcd12341234',
custom_1: '',
custom_2: '',
custom_3: '',
nickname: '', //If customers have multiple subscriptions, you can use nicknames to distinguish them
holduntil_datetime: '2015-06-01 00:00:00', // You can use this to hold/delay billing until a specific date
},
'user': {
name: 'John Doe',
email: 'test@chargeover.com',
phone: '888-924-2347'
},
coupon: '', // The coupon code to be applied to a package
'_comment': 'This is a list of hashes for the services to subscribe the customer to',
'line_items': [
{
'item_id': 1
}
]
// ... or you can refer to item external_key values instead of item_id values
// item_external_keys: [ ... ]
// ... or you can refer to item token values instead of item_id values
// item_tokens: [ ... ]
};
// Our callback function (this gets called after data is sent to ChargeOver)
function my_callback_function(code, message, response)
{
if (code == ChargeOver.Core.CODE_OK)
{
alert('You have signed up! Thanks ' + response.user.first_name + '!');
}
else
{
alert('An error occurred: ' + message);
}
}
// Call the signup method
ChargeOver.Signup.signup(my_data, my_callback_function);
Example w/ credit card
Call the ChargeOver.Signup.signup(...) method to sign up a new customer and store credit card information securely.
Example w/ credit card
JavaScript
// The data we want to send to ChargeOver
var my_data = {
'send_welcome_notice': true, // Default is FALSE. TRUE sends a welcome e-mail to new sign-ups, while FALSE will not send them anything.
'send_payment_receipt': true, // Default is FALSE. TRUE sends a payment receipt e-mail to new sign-ups, while FALSE will not send them anything.
'customer': {
company: 'My Company Name, LLC',
bill_addr1: '56 Cowles Road',
bill_addr2: '',
bill_addr3: '',
bill_city: 'Mt Pleasant',
bill_state: 'MI',
bill_postcode: '48858',
bill_country: 'United States',
},
'user': {
name: 'John Doe',
email: 'test@chargeover.com',
phone: '888-924-2347'
},
'creditcard': {
number: '4111 1111 1111 1111',
expdate_month: '7',
expdate_year: '2016',
name: 'John D Doe'
// CVV/CSC card security code (used only for card validation, not stored)
// cvv: '',
// Optional address information (can be used for address verification)
// address: '',
// city: '',
// state: '',
// postcode: '',
// country: ''
},
'items': [
1 // This is the item_id value of the product you want them signed up for
]
};
// Our callback function (this gets called after data is sent to ChargeOver)
function my_callback_function(code, message, response)
{
if (code == ChargeOver.Core.CODE_OK)
{
alert('You have signed up! Thanks ' + response.user.first_name + '!');
}
else
{
alert('An error occurred: ' + message);
}
}
// Call the signup method
ChargeOver.Signup.signup(my_data, my_callback_function);
Example w/ ACH
Call the ChargeOver.Signup.signup(...) method to sign up a new customer and store ACH/bank account information securely.
Example w/ ACH
JavaScript
// The data we want to send to ChargeOver
var my_data = {
'send_welcome_notice': true, // Default is FALSE. TRUE sends a welcome e-mail to new sign-ups, while FALSE will not send them anything.
'send_payment_receipt': true, // Default is FALSE. TRUE sends a payment receipt e-mail to new sign-ups, while FALSE will not send them anything.
'customer': {
company: 'My Company Name, LLC',
bill_addr1: '56 Cowles Road',
bill_addr2: '',
bill_addr3: '',
bill_city: 'Mt Pleasant',
bill_state: 'MI',
bill_postcode: '48858',
bill_country: 'United States',
},
'user': {
name: 'John Doe',
email: 'test@chargeover.com',
phone: '888-924-2347'
},
'ach': {
number: '8566602',
routing: '072403004',
name: 'John Doe',
// address: '',
// city: '',
// state: '',
// postcode: '',
// country: ''
},
items: [
1 // This is the item_id value of the product you want them signed up for
]
};
// Our callback function (this gets called after data is sent to ChargeOver)
function my_callback_function(code, message, response)
{
if (code == ChargeOver.Core.CODE_OK)
{
alert('You have signed up! Thanks ' + response.user.first_name + '!');
}
else
{
alert('An error occurred: ' + message);
}
}
// Call the signup method
ChargeOver.Signup.signup(my_data, my_callback_function);
Creating a customer
Creating new customers stores customer and contact information within ChargeOver.
Example
Call the ChargeOver.Customer.create(...) to create a new customer.
Example
JavaScript
var my_data = {
customer: {
company: 'My Company Name, LLC',
// external_key: '1234abcd1234', // Use external keys to link your app to ChargeOver data
bill_addr1: '56 Cowles Road',
bill_addr2: '',
bill_addr3: '',
bill_city: 'Mt Pleasant',
bill_state: 'MI',
bill_postcode: '48858',
bill_country: 'United States',
custom_1: '', // Custom field values
custom_2: '',
custom_3: ''
},
user: {
name: 'John Doe',
phone: '888-924-2347',
email: 'test@ChargeOver.com'
}
// You can optionally specify a credit card too if you want
/*
creditcard: {
number: '4111 1111 1111 1111',
expdate_month: '7',
expdate_year: '2016',
name: 'John D Doe'
}
*/
};
//
function my_callback_function(code, message, response)
{
if (code == 200)
{
alert('Thanks, we created the customer ' + response.customer.company);
}
else
{
alert('Error: ' + message);
}
}
//
ChargeOver.Customer.create(my_data, my_callback_function);
Credit Cards
Tokenizing a credit card
Tokenizing a credit card securely stores a credit card within ChargeOver.
Example
Call the ChargeOver.CreditCard.tokenize(...) method to store a credit card.
The default behavior is to update all packages for this customer to use this newly tokenized credit card for future payments. If you do not want this behavior, you can specify use_as_default_paymethod=false.
Example
JavaScript
var my_data = {
customer_external_key: '110051',
// customer_token: 'e64f6121a3cdfb8424413cce74f201e2',
// use_as_default_paymethod: true,
number: '4111 1111 1111 1111',
expdate_month: 7,
expdate_year: 2015,
name: 'John D Doe'
// CVV/CSC card security code (used only for card validation, not stored)
// cvv: '',
// Optional address information (can be used for address verification)
// address: '',
// city: '',
// state: '',
// postcode: '',
// country: ''
}
function my_callback_function(code, message, response)
{
if (code == 200)
{
alert('We stored/tokenized credit card ' + response.creditcard.mask_number);
}
else
{
alert('Error: ' + message);
}
}
ChargeOver.CreditCard.tokenize(my_data, my_callback_function);Type of credit card
Use this method to determine the type of credit card (Visa, Mastercard, etc.).
Example
Call the ChargeOver.CreditCard.type(...) method to determine the type of credit card provided.
Validate a credit card
Validating a credit card lets you determine if a given credit card number and expiration date are valid.
Example
Call the ChargeOver.CreditCard.validate(...) method to validate credit card information.
Example
JavaScript
var my_data = {
number: '4111 1111 1111 1111',
expdate_month: 7,
expdate_year: 2016,
name: 'John D Doe'
// CVV/CSC card security code (used only for card validation, not stored)
// cvv: '',
// Optional address information (can be used for address verification)
// address: '',
// city: '',
// state: '',
// postcode: '',
// country: ''
};
function my_callback_function(code, message, response)
{
if (code == 200)
{
alert('Valid!');
}
else
{
alert('Not valid!');
}
};
ChargeOver.CreditCard.validate(my_data, my_callback_function);
Get a tokenized credit card
Get tokenized credit card data by token.
Example
Call the ChargeOver.CreditCard.get($token) method to get tokenized credit card information.
ACH / EFT / Bank Accounts
Tokenizing an ACH/EFT/bank account
Tokenizing an ACH/bank account securely stores bank info within ChargeOver.
Example
Call the ChargeOver.ACH.tokenize(...) method to store ACH bank info.
The default behavior is to update all packages for this customer to use this newly tokenized ACH info for future payments. If you do not want this behavior, you can specify use_as_default_paymethod=false.
Example
JavaScript
var my_data = {
customer_external_key: '110051',
// customer_token: 'e64f6121a3cdfb8424413cce74f201e2',
// use_as_default_paymethod: true,
number: '8512340',
routing: '072403004',
name: 'John Doe'
}
function my_callback_function(code, message, response)
{
if (code == 200)
{
alert('We stored/tokenized ACH account ' + response.ach.mask_number);
}
else
{
alert('Error: ' + message);
}
}
ChargeOver.ACH.tokenize(my_data, my_callback_function);Validate an ACH/EFT/bank account
Validating an ACH lets you determine if a given bank account and routing number are valid.
Note that the level of validation performed will vary depending on the bank account country/currency, and the configuration of your ChargeOver account.
In general, validation for United States and Canadian bank accounts will be limited to verifying that the bank account number could be valid and that the routing number is valid. ChargeOver generally can not tell whether or not bank account debits will succeed. For example, ChargeOver can not tell if the bank account is overdrawn or the account has been closed.
Example
Call the ChargeOver.ACH.validate(...) method to validate ACH information.
Get a tokenized ACH/EFT/bank account
Get tokenized ACH data by token.
Troubleshooting
ChargeOver is not defined
Uncaught ReferenceError: ChargeOver is not defined
Example
There are some scenarios (in particular pop-up windows loaded by jQuery) where browsers may try to execute Javascript prior to the browser fully loading and executing preceeding <script> tags.
If you encounter this error:
Uncaught ReferenceError: ChargeOver is not defined
You should first check to make sure you are loading the ChargeOver libraries using the setup code provided for your account.
If you're sure that much is correct, surround your ChargeOver code with the block of loader Javascript shown at the right. This delays the execution of ChargeOver code until all required ChargeOver libraries have been initialized.
Example
JavaScript
<!-- Use the setup code from your own account... -->
<script src="https://assets.chargeover.com/minify/?g=chargeover.js"></script>
<script>
// Use these next two lines to delay execution of the ChargeOver code until the libraries are loaded
function co_r(f){if(typeof(ChargeOver) == 'object'){f();}else{setTimeout('co_r('+f+')',250);}}
co_r(function(){
// Use the instance and token values from your account here
ChargeOver.Core.setup({
'instance': 'your-instance.chargeover.com',
'token': 'T08PvhDNLzsgW7uxl3UOm2ikCbVa1IYM'
});
// Put the rest of your calls to ChargeOver code here
// ... your code here ...
});
</script>
Security
Security is a practice of utmost importance at ChargeOver. See the notes below, and reach out to us if you have additional questions.
Store/review/commit mode
Store/review/commit mode provides a way to programatically hold all ChargeOver.js requests in a pending state until they are reviewed (either manually or automatically).
Requests are accessible via a simple REST API which you can utilize to review and either approve or reject on a per request basis.
You will have to contact us to enable store/commit mode.
REST API reference for ChargeOver.js store/commit functionality:
- REST API - get a list of pending requests
- REST API - commit a pending request
- REST API - reject a pending request
Enabling or disabling functionality
If you wish to only utilize a subset of ChargeOver.js functionality (e.g. you want to be able to tokenize credit cards, but you do not want to allow adding new customers through ChargeOver.js) individual actions can be enabled or disabled. Please contact us for assistance doing this.
Rate limiting/blocking
ChargeOver.js requests are rate limited using IP blocks and cookies, to prevent brute-force attacks against the ChargeOver.js endpoints.
Rotating ChargeOver.js tokens
The token used for ChargeOver.js communication can be changed or rotated on an as-needed basis. Please contact us for details on how to do this.
Duplicate checking
By default we do not do any duplicate checking for newly submitting subscriptions/transactions. We can optionally enable duplicate checking based on company name, and based on email address.