API ReferenceSupport

Tokenization with Tithely.js (V2)

👍

Changes

Credit card entry is now handled via a flexible iframe to keep everyone adhering to the simplest form of PCI compliance. Bank account tokenization works the same way with a slightly different callback return.

In order to charge a card or bank account, the information must be tokenized using Tithely.js. This allows you to make donations to organizations without having the information touch your servers.

Include tithely.js

Make sure to use the right path for testing vs. when going live.

<!-- Testing -->
<script src="https://tithelydev.com/api-js/v2/tithely.js"></script>

<!-- Go Live -->
<script src="https://tithe.ly/api-js/v2/tithely.js"></script>

📘

Note

For testing, you may use http or https for Tithely.js. The live url requires https.

Create the tithely object

Use javascript to create a tithely object using your public key.

// Create the tithely object (passing your public key)
var tithely = new Tithely('pub_xxxxxxxx');

🚧

Warning

Never show your private key in javascript or HTML. Only use your public key.

Tokenize a card (using card entry form)

Tokenization with credit / debit cards works different than version 1 of Tithely.js. Instead of creating the form elements on the page (card number, CVV, exp date, etc), the form will be generated for you in an iframe. This allows you to keep to the simplest form of PCI compliance.

First, you'll specify a div to place your card entry form.

<div id="card-entry-form">
<!-- Iframed card entry form will be generated here -->
</div>

Next, you'll call the createCardEntry() method to generate the card entry form within the specified div and pass in any styles for the form elements.

// Style fields inside the form
var form_style = {
  base: {
    color: '#32325d',
    fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
    fontSmoothing: 'antialiased',
    fontSize: '16px',
    '::placeholder': {
      color: '#aab7c4'
    }
  },
  invalid: {
    color: '#fa755a',
    iconColor: '#fa755a'
  }
};

// Create our card entry form in the specified div (using the div's ID attribute)
tithely.createCardEntry('#card-entry-form', form_style);

Once the user has entered their card information (and whatever else you collect on the form), you'll call createCardToken method. Typically you'll want to call this on a submit or click event. You'll be able to grab your token (and other information) using a specified callback function.

// Form submit example using jQuery
$('#some-form-id').submit(function() {
  // Specify your callback function to retrieve the card token, etc
  tithely.createCardToken(tithelyTokenCallback);
});

// Callback function to grab your token and any other info needed from the card
function tithelyTokenCallback(response) {
  if (response.error) {
    // Error handling here
    console.warn(response.error.message);
  }
  else {
    // Get the token
    var token = response.token.id;
    console.log(response);
    // What's next?
    // Add this token to your form as a hidden field (or use ajax to send it)
    // On the server side, attach the token to a user using the API (server side) - see documentation for /api/v1/payment-methods
    // This will allow you to charge this card going forward
    // Or just charge a user once (keep in mind tokens will expire in a few minutes) - see documentation for /api/v1/charge-once
  }
}

Interacting with card entry

You can interact with your card entry form using several methods and events. See some examples below.

// Update the styles and / or move to a new wrapper
tithely.updateCardEntry('#new-card-entry-form', form_style);

// Remove a card entry field
// Keep in mind that once destroyed, it is gone
tithely.destroyCardEntry();

// Clear card entry form fields
tithely.clearCardEntry();

// Detect a change in card entry
tithely.onCardEntryChange(tithelyCardChangeCallback);

// Callback function to detect changes to card info as it's being entered
function tithelyCardChangeCallback(event) {
  // Grab card brand with event.brand (amex, visa, discover, mastercard or null)
  // Grab form completeness with event.complete (true or false)
  console.log(event);
  // See the console for more options
}

Styling card entry

We recommend styling your wrapping div, but you can also style form elements within the iframe by passing in the style object when creating your form.

Customize appearance using CSS properties. Style is specified as an object for any of the variants below.

  • base, base style—all other variants inherit from this style
  • complete, applied when the Element has valid input
  • empty, applied when the Element has no customer input
  • invalid, applied when the Element has invalid input

For each of the above, the properties below can be customized.

  • color
  • fontFamily
  • fontSize
  • fontSmoothing
  • fontStyle
  • fontVariant
  • iconColor
  • lineHeight
  • letterSpacing
  • textDecoration
  • textShadow
  • textTransform

The following pseudo-classes and pseudo-elements can also be styled with the above properties, as a nested object inside the variant.

  • :hover
  • :focus
  • ::placeholder
  • ::selection
  • :-webkit-autofill
  • :disabled 
// Example of a style object
var style = {
  base: {
    color: '#32325d',
    fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
    fontSmoothing: 'antialiased',
    fontSize: '16px',
    '::placeholder': {
      color: '#aab7c4'
    }
  },
  invalid: {
    color: '#fa755a',
    iconColor: '#fa755a'
  }
};

Tokenize a bank account

Tokenizing a bank account works pretty much the same way as Tithely.js version 1. Just create a bank account object, pass in the values and submit it using the createBankToken method. The callback function works the same way.

📘

Note

Tokens are now returned in the callback as response.token.id (previously they returned as response.id).

// Example bank account object
var bank_account = {
  routing_number : '110000000',
  account_number : '000123456789',
  name : 'Mike Rogers', // Name of the person or business that owns the bank account
  account_holder_type : 'individual' // Either "individual" or "company"
};

// Tokenize bank account
tithely.createBankToken(bank_account, tithelyTokenCallback);

// Callback function to grab your token and any other info needed from the card
function tithelyTokenCallback(response) {
  if (response.error) {
    // Error handling here
    console.warn(response.error.message);
  }
  else {
    // Get the token
    var token = response.token.id;
    console.log(response);
    // What's next?
    // Add this token to your form as a hidden field (or use ajax to send it)
    // On the server side, attach the token to a user using the API (server side) - see documentation for /api/v1/payment-methods
    // This will allow you to charge this card going forward
    // Or just charge a user once (keep in mind tokens will expire in a few minutes) - see documentation for /api/v1/charge-once
  }
}

How to use the token

  • On the server side, add a payment method using the token (see payment methods documentation) and then charge the donor (see charges documentation). This will allow you to charge the payment method multiple times without adding it over and over again.
  • On the server side, charge a user once (see quick charge documentation) using the token.