Link

Best Practices

Throttling - Rate Limiting

All api routes are throttled to 150 requests per minute per IP.

You are only allowed 10 failed transactions per minute.

Fattmerchant.js routes are different. When you call the .pay() or the .tokenize() method, Fattmerchant.js hits the Fattmerchant API with the defined Webpayments token. This resource is throttled to 10 requests per minute per IP.

Note if you need to process a higher number of requests, please reach out to us to have your IP whitelisted


Verification Checks

Address Verification (AVS)

AVS checks are used to verify that the address information provided matches the billing address on file with the card issuer. There are different levels and combinations of AVS:

  • Based on zip code
  • Based on the street address

Whether you use Fattmerchant.js or a direct POST to create a payment method and based on your preferred AVS configuration, you need to pass in the appropriate address fields: address_zip and/or address_1

If you wish to add AVS support to your live account or for more information, please reach out to your account manager.

NOTE: AVS checks can only be tested on a live account.


Fattmerchant.js Validation

If the validate flag is passed into the tokenize or pay methods, FattJs will attempt to validate the details with the following rules:

  • method - required, must be ‘bank’ or ‘card’
  • firstname - required if customer_id is not passed into details, max of 50 characters
  • lastname - required if customer_id is not passed into details, 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
  • address_1: required if customer_id is not passed into details, max of 255 characters
  • 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)
  • card_exp: required if method === ‘card’,
  • bank_account: required if method === ‘bank’
  • bank_routing: required if method === ‘bank’
  • bank_type: required if method === ‘bank’, must be ‘checking’ or ‘savings’
  • bank_holder_type: required if method === ‘bank’, must be ‘personal’ or ‘business’
  • total: not required, must be a number
  • 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 transaciton if using .pay())

Fattmerchant.js Important Notes

Trigger a Success/Failure

Do you want to trigger a success or failure in your Sandbox account? If so, please see the table of test cards and bank accounts in the payment methods section.

Throttling

Fattmerchant.js routes are different. When you call the .pay() or the .tokenize() method, Fattmerchant.js hits the Fattmerchant API with the defined Webpayments token. This resource is throttled to 10 requests per minute per IP.

Status Column

The .pay() returns an Invoice object with a status of either PAID or ATTEMPTED depending on whether the charge was successful. Please learn more about statuses in the Invoice section below.

Automated Receipt

This method will automatically send a receipt to the email provided (which is the customer’s email). This receipt will also show whether the charge was a success or a fail.

Customer Matching

When you use .tokenize() OR .pay() the API will attempt to find matching customer information according to these groups of demographics:

  • customer_id
  • email
  • company, address_1, address_city
  • firstname, phone
  • firstname, lastname, address_1, address_zip
  • lastname, phone

A match is found when each field exists is passed and an exact match is found. For example: Bob Smith at 123 North Way 32801 would not match to Bobby Smith at 123 Noth. Way 32801 If a match is found based on the provided demographics, the existing customer will be linked to the new payment method and transaction and any additional demographics will not be stored.

For example: if a Match is found for Bob.Smith@test.com but you also passed data like Address Line 1 and the existing Bob Smith didn’t have an address, then the new address will not be saved.

If the matched customer has an email, that email address will receive the receipt.

to disable matching pass match_customer: false (as boolean false) with the rest of the fields when calling .pay() _or_ .tokenize()`

Using an existing customer_id

You are welcome to create a customer first using POST customer and then use the resuling customer_id in your Fattmerchant.js integration.

Both .pay() and .tokenize() accept a customer_id. When this value is passed, the customer will not be created, but instead the existing customer with the specified id will be used for the new payment method (and invoice, payment if using .pay())

This also provides you with the ability to implement your own customer matching and then specify the exact id.

Use a Billing Address

The address fields available in Fattmerchant.js are stored on the customer and not sent to the payment gateway. There is no way to add a billing address with Fattmerchant.js alone. However, once you have the payment_method_id you can do a PUT payment-method call to add a billing address using your api key.

Please see the PUT payment-method for detailed information.

Billing addresses are sent along with the payment if supplied.