Tokens are key to processing payments (credit card, bank account ACH, eCheck) with the QuickBooks Payments API.
Tokens are opaque containers that mask cardholder, credit card, and bank account info. Your app can create and then use tokens to make API calls while keeping private data hidden. Tokens also gives you a programmatic way to comply with the Payment Application Data Security Standard (PA DSS) and Payment Card Industry (PCI) compliance standards.
Use the token entity to create tokens. Then use the charges entity to process the payment. You can also use existing credit cards (via the card entity) or eChecks (via the eCheck entity) objects.
This requires you to think broadly when designing your app. Consider when and how payments are received, if payment method info already exists, and what data your app needs to mask with tokens.
Apps that use the QuickBooks Payments API to access cardholder and credit card data are required to follow the Payment Application Data Security Standard (PA DSS) and Payment Card Industry (PCI) compliance rules.
If your app uses tokens, your app complies with these standards without needing to handle sensitive card info. You also don’t need to store sensitive data on your app’s servers - we’ll store this data on our servers.
Learn more about basic payment processing and data standards. For more details, refer to the Payment Card Industry (PCI) Security Standards Council website.
If you haven’t already, get a QuickBooks Online sandbox company to test with and create an app on the dev portal.
When you create your app, make sure you review your app’s scopes. Scopes limit what API entities and data your app can access.
Get the Client ID and Client Secret for your app.
You’ll use these to connect your app to services like OAuth 2.0.
If you haven’t already, set up OAuth 2.0 for your app.
To satisfy PA DSS and PCI compliance requirements, make sure your app exchanges bank or credit card info with tokens before the data reaches your server.
Identify incoming charges or existing data (via the card or bankAccount entities) you need to mask. You can create a charge from the existing card or bank account, or create a new one via the charges entity.
Then, create the token. Exchange the charge object for the token to mask the info.
Tokens have a few limitations:
For this example, let’s create a token for a credit card. This is a typical transaction your app needs to “tokenize”.
Use the following entities:
In this example, we’ll use HTML and JavaScript. Since we have to exchange credit card info before it reaches your server, your app can create a token from the JavaScript running in the browser. It can then pass the token to your server to call charge objects.
HTML
JS
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | <form role="form">
<div class="tab-content">
<div class="tab-pane fade in active" role="tabpanel" id="stepper-step-1">
<div class="container">
<h3 class="emulateSandbox">Click <a target="_blank" href="https://developer.intuit.com/docs/00_quickbooks_payments/2_build/60_tutorials/test_your_app">here </a>to emulate credit card numbers in sandbox</h3>
<div class="col-xs-12 col-md-4" style="left:100px;">
<h2>1. Create Token : </h2>
<!-- CREDIT CARD FORM STARTS HERE -->
<div class="panel panel-default credit-card-box">
<div class="panel-heading display-table" >
<div class="row display-tr" >
<h3 class="panel-title display-td" >Payment Details</h3>
<div class="display-td" >
<img class="img-responsive pull-right" src="http://i76.imgup.net/accepted_c22e0.png">
</div>
</div>
</div>
<div class="panel-body">
<form role="form" id="payment-form">
<div class="row">
<div class="col-xs-12">
<div class="form-group">
<label for="cardNumber">CARD NUMBER</label>
<div class="input-group">
<input
type="tel"
class="form-control"
name="cardNumber"
placeholder="Valid Card Number"
autocomplete="cc-number"
required autofocus
id = "cardNumber"
/>
<span class="input-group-addon"><i class="fa fa-credit-card"></i></span>
</div>
</div>
</div>
</div>
<div class="row">
<div class="col-xs-7 col-md-7">
<div class="form-group">
<label for="cardExpiry"><span class="hidden-xs">EXPIRATION</span><span class="visible-xs-inline">EXP</span> DATE</label>
<input
type="tel"
class="form-control"
name="cardExpiry"
placeholder="MM / YYYY"
autocomplete="cc-exp"
required autofocus
id="expYear"
/>
</div>
</div>
<div class="col-xs-5 col-md-5 pull-right">
<div class="form-group">
<label for="cardCVC">CVC</label>
<input
type="tel"
class="form-control"
name="cardCVC"
placeholder="CVC"
autocomplete="cc-csc"
required
id="cvc"
/>
</div>
</div>
</div>
<div class="row">
<div class="col-xs-12">
<div class="form-group">
<label for="couponCode">NAME ON CARD</label>
<input type="text" class="form-control" name="couponCode" id="name"/>
</div>
</div>
</div>
<div class="row">
<div class="col-xs-12">
<div class="form-group">
<label for="couponCode">STREET ADDRESS</label>
<input type="text" class="form-control" name="couponCode" id="streetAddress" />
</div>
</div>
</div>
<div class="row">
<div class="col-xs-7 col-md-7">
<div>
<label for="couponCode">COUNTRY</label>
<input type="text" class="form-control" name="COUNTY" value="US" readonly/>
</div>
</div>
<div class="col-xs-5 col-md-5 pull-right">
<div class="form-group">
<label for="couponCode">CITY</label>
<input type="text" class="form-control" name="CITY" id="city"/>
</div>
</div>
</div>
<div class="row">
<div class="col-xs-7 col-md-7">
<div>
<label for="couponCode">REGION</label>
<div class="form-group">
<div class="col-xs-7">
<select class="form-control" id="state" name="state">
<option value="">N/A</option>
<option value="AK">Alaska</option>
<option value="AL">Alabama</option>
<option value="AR">Arkansas</option>
<option value="AZ">Arizona</option>
<option value="CA">California</option>
<option value="CO">Colorado</option>
<option value="CT">Connecticut</option>
<option value="DC">District of Columbia</option>
<option value="DE">Delaware</option>
<option value="FL">Florida</option>
<option value="GA">Georgia</option>
<option value="HI">Hawaii</option>
<option value="IA">Iowa</option>
<option value="ID">Idaho</option>
<option value="IL">Illinois</option>
<option value="IN">Indiana</option>
<option value="KS">Kansas</option>
<option value="KY">Kentucky</option>
<option value="LA">Louisiana</option>
<option value="MA">Massachusetts</option>
<option value="MD">Maryland</option>
<option value="ME">Maine</option>
<option value="MI">Michigan</option>
<option value="MN">Minnesota</option>
<option value="MO">Missouri</option>
<option value="MS">Mississippi</option>
<option value="MT">Montana</option>
<option value="NC">North Carolina</option>
<option value="ND">North Dakota</option>
<option value="NE">Nebraska</option>
<option value="NH">New Hampshire</option>
<option value="NJ">New Jersey</option>
<option value="NM">New Mexico</option>
<option value="NV">Nevada</option>
<option value="NY">New York</option>
<option value="OH">Ohio</option>
<option value="OK">Oklahoma</option>
<option value="OR">Oregon</option>
<option value="PA">Pennsylvania</option>
<option value="PR">Puerto Rico</option>
<option value="RI">Rhode Island</option>
<option value="SC">South Carolina</option>
<option value="SD">South Dakota</option>
<option value="TN">Tennessee</option>
<option value="TX">Texas</option>
<option value="UT">Utah</option>
<option value="VA">Virginia</option>
<option value="VT">Vermont</option>
<option value="WA">Washington</option>
<option value="WI">Wisconsin</option>
<option value="WV">West Virginia</option>
<option value="WY">Wyoming</option>
</select>
</div>
</div>
</div>
</div>
<div class="col-xs-5 col-md-5 pull-right">
<div class="form-group">
<label for="couponCode">POSTAL CODE</label>
<input type="text" class="form-control" name="couponCode" id="postalCode"/>
</div>
</div>
</div>
<br>
<div class="row">
<div class="col-xs-12">
<button class="btn btn-success btn-lg btn-block" id="createtoken" type="submit">Create Token</button>
</div>
</div>
</form>
</div>
</div>
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | $("#createtoken").click(function(e) {
var card = {};
var exp = $('#expYear').val().split('/');
card.expYear = exp[1];
card.expMonth = exp[0];
card.address = {};
card.address.region = $('#state').val();
card.address.postalCode = $('#postalCode').val();
card.address.streetAddress = $('#streetAddress').val();
card.address.country = 'US';
card.address.city = $('#city').val();
card.name = $('#name').val();
card.cvc = $('#cvc').val();
card.number = $('#cardNumber').val();
var cardObj = {"card":card};
$("#token-payload").text(JSON.stringify(cardObj, null, 2));
e.preventDefault();
var baseUrlSandbox = "https://sandbox.api.intuit.com/quickbooks/v4/payments/tokens";
var baseUrlProduction = "https://api.intuit.com/quickbooks/v4/payments/tokens";
$.ajax({
url: baseUrlSandbox || baseUrlProduction,
data: JSON.stringify(cardObj),
type: 'POST',
dataType: "text",
headers: {"Content-Type": "application/json"},
success: function (resp) {
alert(resp);s
$("#token-result").text(resp);
},
error: function(e) {
$("#token-result").text(e);
}
});
});
|
Here’s what the “tokenized” credit card looks like:
1 2 3 4 5 6 7 8 9 10 11 12 | <form id="tokenize_form" action="" method="POST"> <label>Number</label><input id="tokenize_cc-number" type="text" value="4444444444444448" /><br /> <label>Expiry Month</label><input id="tokenize_cc-expmonth" type="text" value="10" /><br /> <label>Expiry Year</label><input id="tokenize_cc-expyear" type="text" value="2016" /><br /> <label>CVC</label><input id="tokenize_cc-cvc" type="text" value="123" /><br /> <label>Street Address</label><input id="tokenize_cc-address-street" type="text" value="1 main st" /><br /> <label>City</label><input id="tokenize_cc-address-city" type="text" value="Mountain" /><br /> <label>Region</label><input id="tokenize_cc-address-region" type="text" value="CA" /><br /> <label>Country</label><input id="tokenize_cc-address-country" type="text" value="US" /><br /> <label>Postal Code</label><input id="tokenize_cc-address-postalcode" type="text" value="95005" /><br /> <button type="submit">Tokenize</button> </form> |
You can see all the information about the credit card is masked by the token input id.
Check out more QuickBooks Payments API samples on our Github.