Link

Paying with a Bank - 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 - ACH 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.

  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.

var fattjs = new FattJs("your_website_payments_token", {});

3. Define additional properties

We are getting ready to send in the payment, but we need to gather bank account and some other 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 bank payment with Fattmerchant.js.

Properties of extraDetails (When paying via Bank)

Pay special attention to properties highlighted in bold which may be required

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
person_name required, max of 50 characters, Full name of bank account holder name
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"
bank_name not required, ex. "Chase"
bank_type required, "checking" or "savings"
bank_holder_type required, "personal" or "business"
bank_account required for bank, string representing the bank account number
bank_routing required for bank, string representing the bank routing number (9 digits)
total required when using the pay() method, must be a number
url "https://omni.fattmerchant.com/#/bill/" 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.
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",
      person_name: firstName + ' ' + lastName,
      method: "bank",
      bank_type: "savings",
      bank_name: "Bank INC",
      bank_account: "9876543210",
      bank_routing: "021000021",
      bank_holder_type: "personal",
      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",
              "quantity":10,
              "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.
          }
        ]
      }
    };

4. Call the pay() method with extraDetails

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

5. 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: "https://omni.fattmerchant.com/#/bill/"
    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.