State Tax Codes
ACH
>
State Tax Codes
openapi: 3.0.3
info:
title: Automated Clearing House (ACH) API - State Tax Codes
version: v1
description: |
Automated Clearing House (JHPlatform ACH).
contact:
name: Platform Services - ACH
url: https://www.jackhenry.com/
email: DC-Operations@jackhenry.com
servers:
- url: https://{API_ENDPOINT}
variables:
API_ENDPOINT:
default: digital.garden-fi.com
security: []
tags:
- name: State Tax Codes
description: API operations for State Tax Code management
paths:
/a/api/jh-ach/v1/{InstitutionUniversalId}/state-tax-codes:
post:
operationId: UploadStateTaxCodes
tags:
- State Tax Codes
summary: Upload state tax codes file for an institution
description: |
Enterprise users can upload a CSV or XLS file containing state tax codes for their institution.
The file should include state name (full name or abbreviation), tax code, and tax code description.
Any new upload will replace all existing tax codes for the institution.
**File Requirements:**
- File types: CSV or XLS only (XLSX not supported)
- Optional header row (automatically detected and skipped)
- Three columns required: State Name, Tax Code, Tax Code Description
- State Name: Full name (e.g., "Missouri") or abbreviation (e.g., "MO")
- Tax Code: Numeric value, maximum 6 digits
- Tax Code Description: Alphanumeric text, maximum 80 characters
**Validation:**
- All rows must be valid (any validation error rejects entire file)
- State name must be a valid US state
- No duplicate state + tax code combinations within file
- Maximum file size: 10MB
parameters:
- name: InstitutionUniversalId
in: path
description: A unique identifier to establish the identity of an Institution/Environment/Brand combination
required: true
schema:
type: string
requestBody:
required: true
description: State tax codes file upload
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: |
CSV or XLS file containing state tax codes. May include optional header row.
Columns: State Name (full or abbreviated), Tax Code (max 20 chars), Tax Code Description (max 80 chars).
File name is extracted from the uploaded file header.
responses:
'204':
description: No Content - File successfully uploaded and processed
'400':
description: The server could not understand the request due to an invalid request.
content:
application/problem+json:
schema:
type: object
required:
- type
- title
- details
properties:
type:
description: A string path which uniquely classifies the domain of the error.
type: string
nullable: false
example: jackhenry/operation-failed
title:
description: A end-user readable string title of the error type.
nullable: false
type: string
details:
description: An array of end-user readable strings which provide additional details for the error message.
type: array
nullable: false
items:
type: string
data:
type: object
description: |
Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined.
nullable: true
'401':
description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
'403':
description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the clients identity is known to the server.
'404':
description: The server can not find the requested resource. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client.
'500':
description: An unexpected internal server error occurred while processing the request.
content:
application/problem+json:
schema:
type: object
required:
- type
- title
- details
properties:
type:
description: A string path which uniquely classifies the domain of the error.
type: string
nullable: false
example: jackhenry/operation-failed
title:
description: A end-user readable string title of the error type.
nullable: false
type: string
details:
description: An array of end-user readable strings which provide additional details for the error message.
type: array
nullable: false
items:
type: string
data:
type: object
description: |
Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined.
nullable: true
examples:
internalServerError:
summary: Internal server error
value:
type: general/internal-server-error
title: Internal server error
details:
- Unexpected internal server error
get:
operationId: GetStateTaxCodes
tags:
- State Tax Codes
summary: Retrieve state tax codes and amount types
description: |
Retrieve all state tax codes for an institution along with the available amount types.
**Authorization**: Clients should check the `ach_state_tax_payments` ability to determine whether
to show state tax payment features in the UI. This endpoint returns the configured tax codes
to allow authorized users to review the configuration.
parameters:
- name: InstitutionUniversalId
in: path
description: A unique identifier to establish the identity of an Institution/Environment/Brand combination
required: true
schema:
type: string
responses:
'200':
description: OK - Returns tax codes and amount types
content:
application/json:
schema:
type: object
required:
- amountTypes
- stateTaxCodes
properties:
amountTypes:
type: object
description: Map of amount type codes to their descriptions
additionalProperties:
type: string
example:
T: Tax
S: State
P: Penalty
I: Interest
C: City
L: Local
stateTaxCodes:
type: array
description: List of state tax codes for the institution
items:
type: object
required:
- state
- code
- taxCode
- description
properties:
state:
type: string
maxLength: 50
description: Full name of the state
example: Missouri
code:
type: string
minLength: 2
maxLength: 2
description: Two-letter state abbreviation
example: MO
taxCode:
type: string
pattern: ^[a-zA-Z0-9]{1,20}$
minLength: 1
maxLength: 20
description: State tax code identifier (alphanumeric, per TRD Req 4.2 & 9.2)
example: '1999'
description:
type: string
maxLength: 80
description: Description of the tax code
example: State Sales Tax
'400':
description: The server could not understand the request due to an invalid request.
content:
application/problem+json:
schema:
type: object
required:
- type
- title
- details
properties:
type:
description: A string path which uniquely classifies the domain of the error.
type: string
nullable: false
example: jackhenry/operation-failed
title:
description: A end-user readable string title of the error type.
nullable: false
type: string
details:
description: An array of end-user readable strings which provide additional details for the error message.
type: array
nullable: false
items:
type: string
data:
type: object
description: |
Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined.
nullable: true
'401':
description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
'403':
description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the clients identity is known to the server.
'404':
description: The server can not find the requested resource. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client.
'500':
description: An unexpected internal server error occurred while processing the request.
content:
application/problem+json:
schema:
type: object
required:
- type
- title
- details
properties:
type:
description: A string path which uniquely classifies the domain of the error.
type: string
nullable: false
example: jackhenry/operation-failed
title:
description: A end-user readable string title of the error type.
nullable: false
type: string
details:
description: An array of end-user readable strings which provide additional details for the error message.
type: array
nullable: false
items:
type: string
data:
type: object
description: |
Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined.
nullable: true
examples:
internalServerError:
summary: Internal server error
value:
type: general/internal-server-error
title: Internal server error
details:
- Unexpected internal server error
Did this page help you?
Why was this page helpful?
Why wasn't this page helpful?
Thank you for your feedback!
Last updated Thu Mar 12 2026