Paying 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.

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=""></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.

  1. Navigate to Omni
  2. Click on Apps
  3. Click on API Keys
  4. 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 pay 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="paybutton">

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.

  .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
  // activate pay button
  var payButton = document.querySelector("#paybutton");
  payButton.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!
  // activate pay button
  var payButton = document.querySelector("#paybutton");
  payButton.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 pay. We will put together an object called extraDetails which will include - at a minimum - the required fields for making a payment with Fattmerchant.js

Properties of extraDetails (When paying 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
email 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”)
total required when using the pay() method, must be a number
url "" not required, this represents the hosted url where this paid invoice can be viewed, when the invoice's id is appended to it. See here for an example of what a hosted paid invoice looks like.
send_receipt not required, boolean, defaults to `true`. When set to `true` an email will be sent every time the pay() method is called from your application - even if the transaction is not successful. In the case that the transaction was not successful (for whatever reason), an email will be sent which will include a call to action to pay using the Omni hosted payments solution. Alternatively, if you choose to use the out-of-the-box Omni email solution, but would like more control over when a receipt email is sent, you can utilize the Transactions resource to send receipt by email or sms.
validate not required, boolean. Determines whether or not Fattmerchant.js does client-side validation. See Validation section for more details.
meta not required, object, each field within meta is also optional.
meta.invoice_merchant_custom_fields not required, array containing custom field objects. See Example Below for more information. These custom fields will only show up if your account is subscribed to the Advanced Customization add-on. To enable this feature, please reach out to your Account Manager.

Example extraDetails object

    const extraDetails = {
      total: 10,
      firstname: "John",
      lastname: "Doe",
      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",
      send_receipt: false,
      validate: false,
      meta: {
        reference: 'invoice-reference-num',// optional - will show up in emailed receipts
        memo: 'notes about this transaction',// optional - will show up in emailed receipts
        otherField1: 'other-value-1', // optional - we don't care
        otherField2: 'other-value-2', // optional - we don't care
        subtotal: 1, // optional - will show up in emailed receipts
        tax: 0, // optional - will show up in emailed receipts
        lineItems: [ // optional - will show up in emailed receipts
              "id": "optional-fm-catalog-item-id"
              "item":"Demo Item",
              "details":"this is a regular demo item",
              "price": .1
        invoice_merchant_custom_fields: [
              "id": "dc4b-6c74-00dd-fab1-fe00" // Required, must be a unique string.
              "name": "External ID" // The name of the custom field that will be displayed to your customers and users; this will appear above the field as a label.
              "placeholder": "Ex. #123" // The placeholder for the field; this is the faint text that will appear in the entry box of your custom field to help guide your users before they enter in the value when creating an Invoice.
              "required": true // Determines if this field is required to be filled by the user (not customer) when first creating an Invoice.
              "type": "text" // Input type. Only 'text' is supported.
              "value": "123456789" // The value that will appear when viewing the Invoice or Invoice Email. For the merchant, this will also appear when viewing the Invoice via the Invoices or Edit Invoice pages.
              "visible": true // This determines if the field is visible when viewing the Invoice or Invoice Email. If false, will only appear in merchant-facing pages such as the Invoices or Edit Invoice pages.

5. Call the pay() method with extraDetails

document.querySelector("#paybutton").onclick = () => {
    .then((response) => {
      console.log("invoice object:", response);
      console.log("transaction object:", response.child_transactions[0]);
    .catch((err) => {
      console.log("unsuccessful payment:", err);

6. View the response

A successful call to the Fattmerchant.js pay() method will first create a tokenized payment method which is tied to a new or existing customer. Then, an invoice is made using the details passed into the extraDetails object. Finally, a transaction is made using the new payment method, which pays off the invoice in full. The resulting response of the pay() method, therefore, is the invoice object which will include a reference to the customer, payment method, and the transaction which was made. Often times, you may only need to have an understanding of the transaction which was made (for example, to understand if the transaction was made successfully). If this is the case, since the response is the full invoice, you will access the transaction information via response.child_transactions[0].

Example Response(invoice object):

    balance_due: 0
    child_transactions: [
        auth_id: null
        created_at: "2020-07-01 00:17:08"
        customer_id: "e8978baa-0278-47c2-9036-2849c6f522e1"
        id: "0a40f1a9-f308-4add-8613-91f717b52831" // this is the transaction's id
        invoice_id: "101c4a15-5cdb-41e5-837c-f23470c7d670"
        is_manual: false
        is_merchant_present: false
        issuer_auth_code: null
        last_four: "1111"
        message: null
        meta: {memo: "notes about this transaction", otherField1: "other-value-1", otherField2: "other-value-2",}
        method: "card"
        payment_method: {id: "68ad2229-18ab-47d5-8713-2f4cf109af55", customer: null,}
        payment_method_id: "68ad2229-18ab-47d5-8713-2f4cf109af55"
        receipt_email_at: null
        receipt_sms_at: null
        reference_id: ""
        source: null
        success: true
        total: 1
        type: "charge"
        updated_at: "2020-07-01 00:17:08"
    created_at: "2020-07-01 00:17:08"
    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-01 00:17:07"
      deleted_at: null
      email: ""
      firstname: "Jon"
      gravatar: false
      id: "e8978baa-0278-47c2-9036-2849c6f522e1"
      lastname: "Doe"
      notes: null
      options: null
      phone: "111111111111111"
      reference: ""
      updated_at: "2020-07-01 00:17:07"
    customer_id: "e8978baa-0278-47c2-9036-2849c6f522e1"
    deleted_at: null
    due_at: null
    id: "101c4a15-5cdb-41e5-837c-f23470c7d670" // this is the invoice's id
    invoice_date_at: "2020-07-01 00:17:08"
    is_merchant_present: null
    is_partial_payment_enabled: true
    is_webpayment: true
    meta: {
      lineItems: [
          details: "this is a regular, demo item"
          id: "optional-fm-catalog-item-id"
          item: "Demo Item"
          price: 0.1
          quantity: 10
      memo: "notes about this transaction"
      otherField1: "other-value-1"
      otherField2: "other-value-2"
      reference: 1988
      subtotal: 1
      tax: 0
    paid_at: "2020-07-01 00:17:10"
    payment_attempt_failed: false
    payment_attempt_message: ""
    payment_method_id: "68ad2229-18ab-47d5-8713-2f4cf109af55"
    schedule_id: null
    sent_at: null
    status: "PAID"
    total: 1
    total_paid: 1
    updated_at: "2020-07-01 00:17:10"
    url: ""
    viewed_at: null

Congratulations! You have now successfully created a simple payment 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

Set up Webhooks →
Set up webhooks to listen for different events which happen in your merchant account.

Refund/Void →
Implement refund or void capabilities in your application.

Poll for Transactions →
You’ve set up Simple Payments with Fattmerchant.js. Now, if you need your application to have an understanding of transactions which took place in your merchant account, you can list out all transactions which were made to reconcile your accountiing.

Deposit/Settlement Reporting →
Implement Reporting to understand when a transaction has settled and will be deposited in your account.