# 

`tax_amount` records how much of a transaction is tax. The gateway keeps it with the transaction and returns it on every read, so your reports can show the tax on each sale without a lookup in your own system.

## The one rule that matters

**`amount` is the whole charge. `tax_amount` says how much of it is tax.**

The two are not added together. A 100.00 sale with 5.00 of tax is:

```json
{
  "amount": 10500,
  "tax_amount": 500
}
```

The cardholder is charged 105.00. Sending `"amount": 10000, "tax_amount": 500` charges them 100.00 and reports 5.00 of it as tax.

Both fields are integers in cents. `tax_amount` is optional and runs from 0 to 99,999,999. A negative value returns `400` with `INVALID_REQUEST_DATA`.

**`tax_amount` is for reporting only.** The gateway does not check it against `amount`, so a value larger than the charge is accepted as sent. Make sure your own figures add up before you send them.

## Before you start

* You can already create a transaction. See [Accept a card payment](/docs/payments/accept-a-card-payment).
* `tax_amount` works on every transaction you create: a card sale, a card authorization, an ACH sale and a payout.


## On a sale

Send `tax_amount` with the rest of the transaction.

A sale can carry a tip and tax together. Both are parts of `amount`, and each is reported on its own. See [Add a tip](/docs/payments/add-a-tip).

## On an authorization

Send `tax_amount` when you authorize. The capture request has no `tax_amount` of its own, and the capture reports the value from the authorization it captures.

So if the tax depends on the final total, work it out before you authorize. [Authorize and capture](/docs/payments/authorize-and-capture) covers the rest of that flow.

## What comes back

The response echoes `tax_amount` alongside `amount`, and so does every later read of the transaction, including `GET /v1/transactions`.

```json 200 application/json
{
  "id": "TRANSACTION-01KEW3J8QD2N5V7X4ZRB6TMC1P",
  "reference_transaction_id": null,
  "type": "SALE",
  "result": "APPROVED",
  "client_id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB",
  "client_dba": "Acme Jewelry",
  "integrations": [
    "TSYS"
  ],
  "response_code": "00",
  "response_description": "Approved",
  "batch_id": null,
  "is_settled": false,
  "time_created": "2026-07-15T18:33:46Z",
  "amount": 10500,
  "tip": 0,
  "tax_amount": 500,
  "currency": "USD",
  "payment_method": {
    "type": "CARD",
    "truncated_pan": "****-****-****-5439",
    "payment_token": "CARD_TOKEN-01KFDKXMQ637EKEAY410MSQSXB",
    "expiry": {
      "month": "01",
      "year": "2028"
    },
    "first_name": "John",
    "last_name": "Doe",
    "entry_method": "ECOMMERCE",
    "auth_code": "123456",
    "retrieval_reference_number": "000000603081",
    "card_type": "UNKNOWN",
    "card_brand": "Visa",
    "cvv_result_code": "M",
    "avs_result_code": "Y",
    "avs_response": "Exact Match - Street address and postal code match"
  },
  "recurring": false,
  "initiator": "CUSTOMER",
  "network_transaction_id": "000000004271008",
  "metadata": {
    "order_id": "ORD-10457",
    "sales_channel": "web",
    "customer_reference": "cust-8891"
  }
}
```

```json 400 application/json
{
  "error_code": "INVALID_REQUEST_DATA",
  "error_message": "The API request contains invalid data.",
  "details": {
    "amount": "Invalid amount",
    "payment_method.pan": "Malformed PAN"
  },
  "source": {
    "system": "TSYS",
    "code": "13",
    "message": "Invalid amount"
  }
}
```

```json 401 application/json
{
  "error_code": "NOT_AUTHENTICATED",
  "error_message": "Access credentials missing or invalid.",
  "details": null,
  "source": {
    "system": null,
    "code": null,
    "message": null
  }
}
```

```json 403 application/json
{
  "error_code": "UNAUTHORIZED_ACTION",
  "error_message": "Requested action is unavailable or forbidden.",
  "details": null,
  "source": {
    "system": null,
    "code": null,
    "message": null
  }
}
```

```json 409 application/json
{
  "error_code": "DUPLICATE_ACTION",
  "error_message": "Duplicate action requested.",
  "details": null,
  "source": {
    "system": "TSYS",
    "code": "12",
    "message": "Invalid transaction"
  }
}
```

```json 500 application/json
{
  "error_code": "SYSTEM_ERROR",
  "error_message": "Internal system error.",
  "details": null,
  "source": {
    "system": "TSYS",
    "code": "96",
    "message": "System malfunction"
  }
}
```

```json 502 application/json
{
  "error_code": "DOWNSTREAM_ERROR",
  "error_message": "Downstream service returned invalid or unexpected response.",
  "details": null,
  "source": {
    "system": "VERICHECK",
    "code": "502",
    "message": "Bad Gateway"
  }
}
```

```json 503 application/json
{
  "error_code": "string",
  "error_message": "string",
  "details": {
    "property1": "string",
    "property2": "string"
  },
  "source": {
    "system": "TSYS",
    "code": "51",
    "message": "Insufficient funds"
  }
}
```

**`tax_amount` is `null` when none was sent, never `0`.** That covers:

* a transaction created without a `tax_amount`
* every transaction created before `tax_amount` existed
* every refund and void


Read `null` as "not recorded", not as "no tax". A sale you sent with `"tax_amount": 0` comes back as `0`.

## Next steps

* [Add a tip](/docs/payments/add-a-tip)
* [Authorize and capture](/docs/payments/authorize-and-capture)
* [Find and report on transactions](/docs/after-the-payment/find-and-report-on-transactions)