Tokenize with a Card - Fattmerchant.js
Fattmerchant.js is Fattmerchant’s browser-side JavaScript library, used to tokenize and send sensitive bank and card information directly from a user’s browser to Fattmerchant’s servers, keeping your software fully PCI compliant. When you tokenize a card, you are securely storing that card on file for future use.
See the Pen Fattmerchant.js Demo - Javascript by Fattmerchant (@FattLabs) on CodePen.
1. Add Fattmerchant.js to your website or checkout page.
Add the following script tag to the head of your HTML file.
<script src="https://fattjs.fattpay.com/js/fattmerchant.js"></script>
2. Initialize Fattmerchant.js
First, you will need to know your Web Payments Token (public key). You will need an Omni sandbox account to complete this step. If you do not have a sandbox, click one of the buttons below.
Developers Click Here Partner Developers Click Here
Once you have an Omni sandbox, complete the following steps.
- Navigate to Omni
- Click on Apps
- Click on API Keys
- Copy your website payments token
Initialize your fattjs instance with the FattJs class using your website payments token, like in the examples below.
Note: Passing the number and cvv into the instance of fattjs is what generates the secure iFrame around these two fields, keeping sensitive card information from touching your servers.
var fattjs = new FattJs( "your_website_payments_token" , {
number: {
id: 'card-number', // the html id of the div you want to contain the credit card number field
placeholder: '0000 0000 0000 0000', // the placeholder the field should contain
style: 'height: 30px; width: 100%; font-size: 15px;', // the style to apply to the field
type: 'text' // the input type (optional)
format: 'prettyFormat' // the formatting of the CC number (prettyFormat || plainFormat || maskedFormat)
},
cvv: {
id: 'card-cvv', // the html id of the div you want to contain the cvv field
placeholder: 'CVV', // the placeholder the field should contain
style: 'height: 30px; width: 100%; font-size: 15px;', // the style to apply to the field
type: 'text' // the input type (optional)
}
});
And then, in your payment form, make some fields with the id’s you specified while making your instance of FattJs. Let’s throw in a tokenize button while we’re at it!
<form onsubmit="return false;">
<div id="card-number" style="width:200px; height:30px;"></div>
<div id="card-cvv" style="width:50px; height:30px;"></div>
<button id="tokenizebutton">
Pay
</button>
</form>
3. Load the Credit Card fields
Now that we’ve initialized our instance of FattJs and made the elements that will contain the credit card fields, we can tell FattJs to load in those credit card fields.The showCardForm function returns a Promise which lets us handle the completion of the credit card fields loading in.
fattJs
.showCardForm()
.then((handler) => {
console.log("form was loaded");
// for quick testing, you can set a test number and test cvv here
// handler.setTestPan("4111111111111111");
// handler.setTestCvv("123");
})
.catch((err) => {
console.log("there was an error loading the form: ", err);
});
Handling Form Completion
Fattmerchant.js has a few handlers available to check for field input validity. Firstly, we’ll handle the card_form_uncomplete event, which means that the input within the fields isn’t valid (yet!).
merchant.on("card_form_uncomplete", (message) => {
// the customer hasn't quite finished filling in the fields
// or the input in the fields are invalid
console.log(message);
// activate pay button
var tokenizeButton = document.querySelector("#tokenizebutton");
tokenizeButton.disabled = true;
});
Next, we’ll handle the card_form_complete event, which means that the input within the fields is complete and valid.
merchant.on("card_form_complete", (message) => {
// the customer has finished filling in the fields, and they're valid!
// Nice!
console.log(message);
// activate pay button
var tokenizeButton = document.querySelector("#tokenizebutton");
tokenizeButton.disabled = false;
});
4. Define additional properties
Alright, now we have shown the user the credit card fields, and are getting ready to send in the payment, but we need to gather some additional fields to send into the request to tokenize. We will put together an object called extraDetails which will include - at a minimum - the required fields for creating a tokenized credit card with Fattmerchant.js
Properties of extraDetails (When tokenizing via Card)
| customer_id | not required, must be a string matching a valid customer_id which belongs to your merchant account. If supplied, a new customer will not be created or matched based on values. Instead, the supplied ID will be assigned this new payment method and transaction. If a customer_id is supplied, certain customer fields such as firstname, lastname, phone, all address fields, etc will be ignored |
| firstname | required, max of 50 characters |
| lastname | required, max of 50 characters |
| phone | required if customer_id is not passed into details, must be at least 10 characters |
| not required, must be a valid email. Receipts will be sent here automatically if the `send_receipt` flag is set to `true`. | |
| address_1 | required if customer_id is not passed into details, max of 255 characters. This field is required for AVS if the account is configured to perform an AVS check on street address. |
| address_2 | not required, max of 255 characters |
| address_city | required if customer_id is not passed into details, max of 255 characters |
| address_state | required if customer_id is not passed into details, max of 2 characters (e.g. FL) |
| address_country | not required, 3 character country code (e.g. USA) |
| address_zip | not required unless AVS is configured to perform an AVS check on zip code. |
| company | not required, string |
| method | required, "card" or "bank" |
| month | required for card, string representing the 2-digit month when the card expires(“05”) |
| year | required for card, string representing the 4-digit year when the card expires (“2020”) |
| validate | not required, boolean. Determines whether or not Fattmerchant.js does client-side validation. See Validation section for more details. |
Example extraDetails object
const extraDetails = {
firstname: "John",
lastname: "Doe",
method: "card",
month: "10",
year: "2020",
phone: "5555555555",
address_1: "100 S Orange Ave",
address_2: "Suite 400",
address_city: "Orlando",
address_state: "FL",
address_zip: "32811",
address_country: "USA",
validate: false,
};
5. Call the tokenize() method with extraDetails
document.querySelector("#tokenizebutton").onclick = () => {
fattjs
.tokenize(extraDetails)
.then((response) => {
console.log("payment method object:", response);
console.log("customer object:", response.customer);
})
.catch((err) => {
console.log("unsuccessful tokenization:", err);
});
};
6. View the response
A successful call to the Fattmerchant.js tokenize() method will create a tokenized payment method which is tied to a new or existing customer. If you already had a customer_id and passed it into the request, you already have an understanding of that customer, but if you are letting Fattmerchant.js create a new customer for you when calling tokenize(), you can retrieve the customer_id from the response and, if applicable, correlate it with the customer in your application.
Example Response(payment method object):
{
address_1: "100 S Orange Ave";
address_2: null;
address_city: "Orlando";
address_country: "USA";
address_state: "FL";
address_zip: "32811";
bank_holder_type: null;
bank_name: null;
bank_type: null;
card_exp: "112020";
card_exp_datetime: "2020-11-30 23:59:59";
card_last_four: "1111";
card_type: "visa";
created_at: "2020-07-06 16:22:16";
customer: {
address_1: "100 S Orange Ave";
address_2: "";
address_city: "Orlando";
address_country: "USA";
address_state: "FL";
address_zip: "32811";
allow_invoice_credit_card_payments: true;
cc_emails: null;
cc_sms: null;
company: "";
created_at: "2020-07-06 16:22:16";
deleted_at: null;
email: "";
firstname: "Jon";
gravatar: false;
id: "cd10fbd4-199c-4753-8db8-66c4e2c2b4e8";
lastname: "Doe";
notes: null;
options: null;
phone: "111111111111111";
reference: "";
updated_at: "2020-07-06 16:22:16";
}
customer_id: "cd10fbd4-199c-4753-8db8-66c4e2c2b4e8";
has_cvv: true;
id: "2e34394f-5f1d-4ec0-a56d-f669509a5b13"; // payment_method_id
is_default: 0;
is_usable_in_vt: true;
method: "card";
nickname: "VISA: Jon Doe (ending in: 1111)";
person_name: "Jon Doe";
updated_at: "2020-07-06 16:22:16";
}
Congratulations! You have now successfully created a tokenized payment method using Fattmerchant.js. If you need to implement other payment functionalities, please see the API reference documentation to understand additional payments capabilities.
Additional Payments Capabilities
Get Payment Methods by Customer →
See all payment methods that are associated with a customer.
Charge a Payment Method →
Make a payment using a payment method.
Set up Recurring Payments →
Attach a payment method to our scheduled invoices to set up automatic payments.