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:

  1. Log in to ChargeOver, and click the settings gear/cog in the top right
  2. Choose "Developer" from the left-side navigation menu
  3. Choose "ChargeOver.js"
  4. Enable ChargeOver.js
  5. 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:

React

An example React app can be found on GitHub:

Vue

An example Vue app can be found 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.

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

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/EFT/bank account

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.051 (gen) on Thu, 19 May 2022 09:17:18 -0500