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.

Examples/Sample Code

Make sure to visit the ChargeOver GitHub account to see ChargeOver.js examples! Feel free to contact us for additional sample code.

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, by going to:

  • Configuration > API & Web Hooks

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

<script src="https://dev.chargeover.com/assets/minify/?g=chargeover.js"></script>
<script>
	ChargeOver.Core.setup({
		'instance': 'dev.chargeover.com',
		'token': '6EILWfekvcjbiMz2F5ulDAXNrwSdp0nK'
	});
</script>

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
        // paycycle: 'yrl',
        // paycycle: 'qtr', 

        // 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

		// coupon: '',			// The coupon code to be applied to a package
    },
    
    'user': {
        name: 'John Doe',
        email: 'test@chargeover.com',
        phone: '888-924-2347'
    },
    
    '_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 plan 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 plan 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.

Example

JavaScript

var my_data = {
	number: '4111 1111 1111 1111'
};

function my_callback_function(code, message, response) 
{
	alert('Credit card type: ' + response);
}

ChargeOver.CreditCard.type(my_data, my_callback_function);

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.

Example

JavaScript

var token = 'n8dx061hwjvb';

function my_callback_function(code, message, response) 
{
	alert('Credit card number: ' + response.creditcard.mask_number);
}

ChargeOver.CreditCard.get(token, my_callback_function);

ACH

Tokenizing ACH 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 account

Validating an ACH lets you determine if a given bank account and routing number are valid.

Example

Call the ChargeOver.ACH.validate(...) method to validate ACH information.

Example

JavaScript


var my_data = {
    number: '856666',
    routing: 'A072403004'
};

function my_callback_function(code, message, response)
{
    if (code == 200)
    {
        alert('Valid!');
    }
    else
    {
        alert('Not valid!');
    }
};

ChargeOver.ACH.validate(my_data, my_callback_function);

Get a tokenized ACH

Get tokenized ACH data by token.

Example

Call the ChargeOver.ACH.get($token) method to get tokenized ACH information.

Example

JavaScript

var token = 'n8dx061hwjvb';

function my_callback_function(code, message, response) 
{
	alert('ACH account number: ' + response.ach.mask_number);
}

ChargeOver.ACH.get(token, my_callback_function);

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:

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.

0.047 (gen) on Tue, 22 Oct 2019 23:44:48 -0500