# Tokenizer
Securely tokenize user payments
# Overview
The purpose of the Tokenizer API is to provide a javascript implementation that injects hosted payment fields onto a client’s website. By injecting the hosted payment page into an iframe via this library, a client remains outside the scope of PCI while still having full control over the processing of the transaction. Once the sensitive data has been collected and tokenized, you may submit any regular API call exchanging the sensitive information with the token you have received.
# Simplicity
With a few lines of code you can take customer payments on your website
# Security
Tokenizer creates a secure iframe that seperates your website from the processing of users payment information into a vault system with a returned token hash
# Customizability
Even though we host and provide the form you can pass your own css styles to tokenizer. See styles
# Step 1 - Add Script Code
TIP
You will need a public api key, the public api key will start with pub_ and is safe to use on the frontend of your website.
TIP
The code that instantiates a new tokenizer instance (not the script src import) can be in the head or the body as long as the container element your referring to has loaded and is accessible. You can use any string to access your element as long as it can be referenced in a document.querySelector('#container') call as that is what tokenizer will attempt to do to look for the element you provided.
WARNING
If you're developing locally be sure to set the url to your api endpoint. Otherwise it will attempt to make a request to the url you are on.
WARNING
Based upon how you build your front end application you may want to place the tokenizer.js file at the bottom of the html body.
DANGER
The secret api key, should never be shared and should only be used within the backend of your application.
<html>
<head>
<!-- Add tokenizer.js file to head or end of body based upon your application setup -->
<script language="javascript" src="https://sandbox.gosparrowone.com/tokenizer/tokenizer.js"></script>
</head>
<body>
<!-- Add div with id, that we will reference below, for where iframe form will go -->
<div id="container"></div>
<!-- Add button to call submit -->
<button onclick="example.submit()">Submit</button>
<!-- Add script tag -->
<script>
var example = new Tokenizer({
url: '', // Optional - Only needed if domain is different than the one your on, example: localhost
apikey: 'pub_XXXXXXXXXXXXXX',
container: '#container', // Make sure that this "container" is the same as the id of the div container you referenced above.
// Callback after submission request has been made
// See Advanced -> Methods for breakdown of specific fields
submission: (resp) => { console.log(resp) }
})
</script>
</body>
</html>
# Default Output
# Step 2 - Process with token
Once you have received the token from the submission callback, you can use the token to replace a payment object in any of our direct API calls.
See Transaction Processing for more details
See below for a few examples:
# Process a sale with token
curl -v -X POST \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
"type": "sale",
"amount": 1112,
"payment_method": {
"token": "<tokenizer token goes here>"
}
}' \
"https://sandbox.gosparrowone.com/api/transaction"
# Process a verification with token and store for later use
curl -v -X POST \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
"type": "verification",
"payment_method": {
"token": "<tokenizer token goes here>"
},
"create_vault_record": true
}' \
"https://sandbox.gosparrowone.com/api/transaction"
# Process a sale with token and store for later use
curl -v -X POST \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
"type": "sale",
"amount": 1112,
"payment_method": {
"token": "<tokenizer token goes here>"
},
"create_vault_record": true
}' \
"https://sandbox.gosparrowone.com/api/transaction"
# Advanced
# Multiple Payment Types
Tokenizer currently supports two payment types credit/debit cards and ach. By default only card is enabled, to enable ach add it to the payment types
var example = new Tokenizer({
apikey: 'pub_XXXXXXXXXXXXXX',
container: '#container',
submission: (resp) => { console.log(resp) },
settings: {
payment: {
types: ['card', 'ach'], // Default ['card']
ach: {
sec_code: 'web', // Default web - web, ccd, ppd, tel
showSecCode: false // Default false - true to show sec code dropdown
},
card: {
strict_mode: false, // Set to true to allow for 19 digit cards
requireCVV: false // Default false - true to require cvv
}
}
}
})
# Paay Integration
Tokenizer will make paay requests when the service is turned on. If the paay service is turned on any use of tokenizer will attempt paay service. Below are a list of options you may use to fine tune paay service with tokenizer.
var example = new Tokenizer({
apikey: "pub_XXXXXXXXXXXXXX",
container: '#container',
submission: (resp) => {
console.log(resp);
},
settings: {
paay: {
sandbox: false, // Set to true to send to sandbox endpoint
forceDisabled: false, // Force not running paay
rejectChallenges: [], // Statuses to reject from submission
// https://docs.3dsintegrator.com/docs/3ds-response-table-of-content
},
},
});
# Fee Calculation
Tokenizer will calculate certain fees for you based upon the amount, payment type selected and the processor id that is passed in. Processor id is optional and if not passed in it will default to the default processor.
var tokenizer = new Tokenizer({
apikey: apikey,
amount: 100,
container: this.$refs.example as HTMLDivElement,
settings: {
payment: {
calculateFees: true,
// optional - default will use default processor
processorId: '12345'
}
},
submission: (resp: any) => {
console.log(resp)
},
validCard: (resp: any) => {
console.log(resp)
}
})
// Submit
var submit = function() {
// submit off to the tokenizer with the dollar amount
tokenizer.submit()
}
# Settings
Tokenizer allows the you to easy take in user, billing and shpping information within the same form. This info will be pased back to the submission callback in raw values.
TIP
Tokenizer DOES NOT tokenize user, shipping or billing information! It only tokenizes payment info
var example = new Tokenizer({
apikey: 'pub_XXXXXXXXXXXXXX',
container: '#container',
submission: (resp) => { console.log(resp) },
settings: {
payment: {
calculateFees: true,
showTitle: true,
placeholderCreditCard: '0000 0000 0000 0000',
showExpDate: true,
showCVV: true,
ach: {
sec_code: 'web', // Default web - web, ccd, ppd, tel
secCodeList: ['web', 'ccd', 'ppd'], // Default web, ccd, ppd
showSecCode: false // Default false - true to show sec code dropdown
},
card: {
strict_mode: false, // Set to true to allow for 19 digit cards
requireCVV: false // Default false - true to require cvv
}
},
user: {
showInline: true,
showName: true,
showEmail: true,
showPhone: true,
showTitle: true
},
shipping: {
show: true,
showTitle: true
},
billing: {
show: true,
showTitle: true
}
}
})
# Methods
var example = new Tokenizer({
apikey: 'pub_XXXXXXXXXXXXXX',
container: '#container',
// Callback after submission request has been made
submission: (resp) => {
// Figure out what response you got back
switch(resp.status) {
case 'success':
// Successful submission
console.log(resp.token)
// If you had user info
if (resp.user) { console.log(resp.user) }
// If you had billing info
if (resp.billing) { console.log(resp.billing) }
// If you had shipping info
if (resp.shipping) { console.log(resp.shipping) }
break;
case 'error':
// Encountered an error while performing submission
console.log(resp.msg)
break;
case 'validation':
// Encountered form validation specific errors
console.log(resp.invalid)
break;
}
},
// Callback after iframe is initiated an onload
onLoad: () => { console.log('iframe has loaded') },
// Callback after payment type changes
onPaymentChange: (type) => { console.log(type) },
// Callback to identify when a valid cc has been inputed
// If valid will return ccbin data as well
validCard: (card) => {
console.log(card)
// card.isValid // Boolean
// card.bin // Object of bin data
// If lookupFees is enabled in the options, then you will also receive the following:
// card.ServiceFee uint - ServiceFee is applicable, to be added to the requested amount.
// card.PaymentAdjustment.value
// card.PaymentAdjustment.type
// card.RequestedAmount uint - this is the base amount of the transaction, any service fee/surcharge should be added to this
// card.Surcharge uint - this is the amount to be surcharged.
// card.Disclosure string - this is the surcharge text to be presented to the card holder
// If you need to check if surchargable
// Pass state and card bin data
var isSurchargeable = example.isSurchargeable(state, card.bin)
console.log(isSurchargeable)
},
// Callback for when the user has changed sec code or account type
achOnChange: (data: any) => { console.log(data) },
// Callback for when someone swipped a card
magStripeSwipe: (data: any) => { console.log(data) }
})
// Set expiration date on card payment
example.setExpDate('09/12')
// Submit payment
example.submit()
# Single Page Apps
Tokenizer is currently setup to output to UMD(univeral module loader). If you hare having difficulty configuring webpack to get the file imported. You can always import into your main file and just refer to it as if it was a window variable.
// index.js - add to your main file
import './tokenizer.js' // tokenizer will add to window.Tokenizer allowing you to globally use it
new Tokenizer({
apikey: 'pub_XXXXXXXXXXXXXX',
container: '#container'
})
# Card Swipe Reader
By default tokenizer will allow the ability to take in a card swipe reader and automaticallly fill out the credit card and expiration fields.
In order for this to work you have to at least be focused on the credit card field.
# Style Examples
Tokenizer allows the passing of css information to style form within the iframe
// Example Code
var example = new Tokenizer({
apikey: 'pub_XXXXXXXXXXXXXX',
container: '#container',
submission: (resp) => { console.log(resp) },
settings: {
// Styles object will get converted into a css style sheet.
// Inspect elements to see structured html elements
// and style them the same way you would in css.
styles: {
'body': {
'color': '#ffffff'
},
'input': {
'color': '#ffffff',
'border-radius': '8px',
'background-color': '#ffffff40',
'border': 'none'
},
// Example - style cvv to have full border box
'.payment .cvv input': {
'border': 'solid 1px #ffffff',
'padding-left': '6px'
}
}
}
})
# Default
# Dark Mode
# Purple
# Konnektive Integration
If you are looking to use our Tokenizer integration along side Konnektive as a CRM, you will need to submit the resulting token in the formCardNonce field to their Order Import API.