Overview

Reference

How it Works

Chargify provides transparent iframes that allow you to customize a customer’s payment form. This approach ensures the you meet the latest PCI compliance requirements.

When a customer submits your payment form, Chargify.js sends the customer payment information to be securely stored in your payment gateway. In return, a one-time-token is generated for you to use to complete the subscription process using our API. The one-time-payment token references the payment information that is securely stored in your gateway.

With this token you can create a subscription or payment profile assigned to the customer. Your PCI is significantly reduced, because of you don’t pass any sensitive payment information. An example API call to the subscriptions endpoint would take the following form:

{
  "subscription": {
    "product_handle": "pro-plan",
    "customer_attributes": {
      "first_name": "Joe",
      "last_name": "Smith",
      "email": "j.smith@example.com"
    },
    "credit_card_attributes": {
      "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn"
    }
  }
}

Getting Started

To begin using Chargify.js, include the chargify.js script on your page. This exposes a single global object, chargify.

__

<script src="https://js.chargify.com/latest/chargify.js"></script>

It is strongly recommended to use the latest Chargify-hosted version of Chargify.js. This version is regularly updated to be compatible with the rest of the system. Using a locally hosted version of Chargify.js may introduce a risk become incompatible with our servers. We strongly recommend against this practice.

Single Page Applications

Because of the fact that Chargify.js gathers customer payment data within iframe elements, it may not work within reactive frameworks like React and Angular.

In order for Chargify.js to work within these frameworks, we suggest implementing a separate signup page, outside of the single-page application. After the signup is completed, you’ll need to gracefully redirect the subscriber back into your application.

Alternately, you may want to explore your payment gateway’s JavaScript widget offerings for tokenization, however keep in mind that if you ever switch gateways, you would need to re-implement this part of your signup flow.

Hosting and Technical Considerations

The static files on https://js.chargify.com are hosted via AWS Cloudfront. They use a different set of HTTP & TLS specifications than https://app.chargify.com. As such, their compatibility with various browsers and clients may be different. It also may be affected by different failures than our primary app.

Specific technical considerations to be aware of:

  • TLS is terminated by Cloudfront using the TLSv1.2_2018 config. TLS 1.0 and TLS 1.1 are not supported. The full cipher suite list is available from AWS
  • Utilizes SNI for TLS, which can result in lower compatibility with browsers than the Chargify application. Akamai has published a study describing the evolution of browser support for SNI and it is very high, but not perfect.
  • Supports HTTP/2, HTTP/1.1, HTTP/1.0
  • Through the use of AWS Cloudfront, https://js.chargify.com is designed for maximum reliability and speed, but is not covered by our SLA, uptime, or performance guarantees.
When you use Chargify.js, your workflow is classified as SAQ-A. For more information, please see our documentation on PCI compliance.

Configuration

Call chargify.load anywhere on your page. It’s that simple!

chargify.load({
    // selector, where the iframe will be included on your page
    // optional, if you have a `selector` for every field ('fields' option)
    selector: '#chargify-form',

    // (i.e. '1a2cdsdn3lkn54lnlkn')
    publicKey: 'your-public-api-key',

    // form type (possible values: 'card' or 'bank')
    type: 'card',

    // points to your Chargify site
    serverHost: 'https://acme.chargify.com'
});

You can find your public API key in the Config –> Integrations section on your site’s page in Chargify.

chargify.load accepts also optional parameters. Here is the complete example:

chargify.load({
    // selector, where the iframe will be included on your page
    // optional, if you have a `selector` for every field ('fields' option)
    selector: '#chargify-form',

    // (i.e. '1a2cdsdn3lkn54lnlkn')
    publicKey: 'your-public-api-key',

    // form type (possible values: 'card' or 'bank')
    type: 'card',

    // points to your Chargify site
    serverHost: 'https://acme.chargify.com',

    // flag to show/hide the credit card image
    // true: hides the credit card image
    // visible otherwise
    hideCardImage: false,

    // optional label/translation (i.e. '(optional field)') for optional fields
    // Especially useful if you use 'fields' option
    optionalLabel: '(optional field)',

    // required label/translation (i.e. '*') for required fields
    // Especially useful if you use 'fields' option
    requiredLabel: '*',

    // optional global styles that include iframe styles,
    // styles for fields, inputs, labels and messages
    style: {
        // to style an iframe, use the iframe's container selector
        '#chargify-form': { border: '1px dashed #ffc0cb57' },

        // `field` is the container for each field
        field: {
            backgroundColor: 'orange',
            paddingTop: '10px',
            paddingBottom: '10px',
            borderRadius: '5px'
        },

        // `input` is the input HTML element
        input: {
            backgroundColor: '#e6e6e6',
            paddingTop: '2px',
            paddingBottom: '1px',
            placeholder: { color: '#eee' }
        },

        // `label` is the label container
        label: {
            backgroundColor: 'lightblue',
            paddingTop: '2px',
            paddingBottom: '1px'
        },

        // `message` is the invalid message container
        message: {
            backgroundColor: 'red',
            color: 'white',
            paddingTop: '2px',
            paddingBottom: '1px'
        }
    },

    // use this option if you want to include each field
    // in the separate iframe
    fields: {}
});

Available Fields

Credit Card

Field name Example Required Description
firstName Joe Optional Cardholder first name
lastName Doe Optional Cardholder last name
number 4242 4242 4242 4242 Required Credit card number
month 08 Required Card expiration month
year 2022 Required Card expiration year
cvv 123 Optional (may be required by your gateway settings) The 3- or 4-digit Card Verification Value. This value is merely passed through to the payment gateway
address 123 Main St. Optional (may be required by your gateway settings) The credit card or bank account billing street address. This value is merely passed through to the payment gateway
address2 i.e. Apt. 100 Optional Second line of the customer’s billing address
city Boston Optional (may be required by your gateway settings) The credit card billing address city. This value is merely passed through to the payment gateway
state MA Optional (may be required by your gateway settings) The credit card billing address state, preferably in 2-letter format. This value is merely passed through to the payment gateway
zip 12345 Optional (may be required by your gateway settings) The credit card billing address zip code. This value is merely passed through to the payment gateway
country US Optional (may be required by your gateway settings) The credit card billing address country, preferably in ISO 3166-1 alpha-2 format. This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Please check your gateway’s documentation

ACH

Field name Example Required Description
firstName Joe Optional First name on bank account
lastName Doe Optional Last name on card or bank account
bankName Test Bank Required The name of the bank where the customer’s account resides
routingNumber 110000000 Required The routing number of the bank
accountNumber 000123456789 Required The customer’s bank account number
accountType checking ——– this defaults to checking and cannot be changed
accountHolderType personal Required may be personal (default) or business
address 123 Main St. Optional may be required by your product configuration or gateway settings The bank account billing street address (i.e. 123 Main St.). This value is merely passed through to the payment gateway
address2 Apt. 100 Optional Second line of the customer’s billing address
city Boston Optional (may be required by your product configuration or gateway settings) The bank account billing address city. This value is merely passed through to the payment gateway
state MA Optional (may be required by your gateway settings) The bank account billing address state, preferably in 2-letter format. This value is merely passed through to the payment gateway
zip 12345 Optional (may be required by your gateway settings) The bank account billing address zip code. This value is merely passed through to the payment gateway
country US Optional (may be required by your gateway settings) The bank account billing address country, preferably in ISO 3166-1 alpha-2 format. This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Please check your gateway’s documentation

Working with Fields

If you want to display each field in a separate iframe, all you have to do is to skip a selector option and define a fields option instead. Minimum requirement is to specify all required fields via the fields option.

  // ...

  fields: {
      // ...

      firstName: {
          // selector where the iframe with this field will be included on your page
          selector: '#chargify4',

          // ot overrides default label
          label: 'FIRST NAME',

          // it overrides default placeholder
          placeholder: 'John',

          // if a given field is optional by default, you can make it required
          required: true,

          // it overrides default error message
          message: 'First name is not valid. Please update it.',

          // it overrides or defines max length
          maxlength: '30',

          // it overrides global styles for this field only
          style: {
              field: {
                  backgroundColor: '#f0dfdf',
                  padding: '3px',
                  borderRadius: '5px'
              },
              input: {
                  backgroundColor: '#f0fde1',
                  paddingTop: '2px',
                  paddingBottom: '1px',
                  placeholder: { color: '#eee' }
              },
              label: { paddingTop: '2px', paddingBottom: '1px', fontSize: '11px' },
              message: { paddingTop: '2px', paddingBottom: '1px' }
          }
      }
  }

Getting a Chargify Token

First, include Chargify iframe(s) inside a form:

<!DOCTYPE html>
<html>
    <head>
        <script src="https://your-page.com/chargify.js"></script>
    </head>

    <body>
        <form id='chargify-form'>
            <div id="chargify1"></div>

            <input id="chargify-token" type="hidden" />

            <button type="submit">Submit Form</button>
        </form>
    </body>

    <script>
        var chargify = new Chargify();

        chargify.load({
            // selector, where the iframe will be included on your page
            // optional, if you have a `selector` for every field ('fields' option)
            selector: '#chargify1',

            // (i.e. '1a2cdsdn3lkn54lnlkn')
            publicKey: 'your-public-api-key',

            // form type (possible values: 'card' or 'bank')
            type: 'card',

            // points to your Chargify site
            serverHost: 'https://acme.chargify.com'
        });
    </script>
</html>

Then you have to interrupt the submission of the form to send billing info to Chargify and get a one time token in exchange. Once you have the token, submit the form to your server.

document.querySelector('#chargify-form').addEventListener('submit', function() {
    var form = this;

    event.preventDefault();

    chargify.token(
        form,
        function success(token) {
            // optionally, you can assign a chargify token to a hidden field
            // or pass it to your backend in other way
            document.querySelector('#chargify-token').value = token;

            // and then submit the form
            form.submit();
        },
        function error(err) {
            // be aware that an error can occur for different reasons
            // while saving billing info in the gateway or directly
            // on the Chargify backend. It is rare but still possible.
            // Remember to make the user aware the presence of an error
            console.log('token ERROR - err: ', err);
        }
    );
});

After you get the token, you will submit it to your server and use it while creating a subscription or payment profile using our API.

Tokens expire after 20 minutes.

Handling Errors

When an error occures on the back-end side, the error callback is invoked with the object having 2 properties:

{
    status: 400, // HTTP status
    errors: "Your card was declined." // it can be an array of errors as well
}