Amounts

How moat handles totals, base amounts, taxes, shipping, discounts, tips, and payment adjustments like surcharges.

Transactions carry a single required money field — amount — and a handful of optional component fields that let moat or the processor break out line-level detail, calculate fees, and track tips. This page covers how they fit together.

amount vs. base_amount

You can submit a transaction in two ways:

amount: you calculate the final total yourself, including any surcharges, convenience fees, and taxes.
base_amount: you submit the pre-fee base, and moat applies the surcharge (or cash discount, or dual-pricing fee — whatever your active fee program is) at processing time.

Use base_amount when your checkout does not know the surcharge yet — for example, server-side submissions where card BIN is unknown at the time of pricing. Use amount when you have already computed the total in the client (recommended for most checkouts so the customer sees the final number before confirming).

Fields

Field	Type	Description
`amount`	integer	Final total in cents, inclusive of all fees and taxes.
`base_amount`	integer	Pre-fee base in cents. moat calculates and adds surcharge / payment adjustment at processing.
`tax_amount`	integer	Tax portion in cents. Required for Level 3.
`tax_exempt`	boolean	`true` marks the transaction as tax-exempt. Required for Level 3 when applicable.
`shipping_amount`	integer	Shipping in cents. Should already be included in `amount`.
`discount_amount`	integer	Discount in cents. Already reflected in `amount`.
`tip_amount`	integer	Tip in cents. Already reflected in `amount`.
`payment_adjustment`	object	Convenience fee, service fee, or surcharge. See below.

payment_adjustment

Field	Values	Description
`payment_adjustment.type`	`flat` or `percentage`	How the adjustment is expressed.
`payment_adjustment.value`	integer	Flat: value in cents (`199` = $1.99). Percentage: 3-decimal basis points (`1000` = 1.000%).

Examples

Amount with tax and shipping

{
  "type": "sale",
  "amount": 1599,
  "tax_amount": 100,
  "shipping_amount": 200,
  "payment_method": { "card": { ... } }
}

Flat convenience fee

{
  "type": "sale",
  "amount": 1398,
  "payment_adjustment": {
    "type": "flat",
    "value": 99
  },
  "payment_method": { "card": { ... } }
}

Percentage surcharge

{
  "type": "sale",
  "base_amount": 1299,
  "payment_adjustment": {
    "type": "percentage",
    "value": 3000
  },
  "payment_method": { "card": { ... } }
}

The request above charges $12.99 base plus a 3.000% surcharge. moat calculates the surcharge and settles the combined amount.

Amount Calculation API

For complex checkouts with line items, multiple taxes, discounts, and processor-specific fee rules, consider the Amount Calculation API. It applies your configured fee program, computes the totals the same way the processor will, and returns the exact amount to submit with the transaction. This is useful when you want to show the customer the final number before confirming.

Fee programs and amounts

If you have an active fee program (surcharge, cash discount, dual pricing), moat handles the fee math according to the program rules. See Fee Programs for the math each program uses. The key practical point: with a fee program enabled, base_amount is often the right field to submit, because you want moat to compute the fee the same way every time.