USTC Payment Portal

This package makes SOAP requests to the pay.gov hosted collection pages service.

The application is intended to handle API requests from USTC applications and then make requests to Pay.gov on its behalf.

Using as a dev dependency

npm install --save-dev @ustaxcourt/payment-portal
npx payment-portal start

See docs/using-as-dev-dependency.md for the complete guide: port configuration, type imports, and troubleshooting.

Workflow

Initiate a Transaction

1. An application makes a request to initiate a transaction to the Payment Portal. This request includes some key information:

   • Fee (fee parameter): The stable key identifying the type of fee the Application wishes to charge (e.g., PETITION_FILING_FEE). Internally referred to as a FeeKey — a client-facing identifier that remains consistent across fee versions. The Portal maintains the list of valid keys.
   • TransactionReferenceId: A unique identifier generated by the Application to use in future API calls that refer back to the specific thing the User is paying for (e.g., a DAWSON Petitions Fee for Docket Number 123-12). This must be a UUID.
   • Metadata: This is an object with N number of Key/Value pairs. Different fees will require values for specific keys. For example, { "DocketNumber": "123-12" } may be used for a Petitions Fee payment request.

2. The Portal authenticates the application via AWS Signature Version 4

3. The Portal checks its own permission system to authorize the Application to initiate a Transaction to the Specified Fee

4. Once authorized, the Portal also makes sure there is not already a Successful transaction for the specified TransactionReferenceId.

5. If there isn't, then the Portal generates a unique agencyTrackingId and starts keeping track of this transaction in its own database.

6. The portal then performs a startOnlineCollection request to Pay.gov with the transaction information derived from the Fee.

7. Pay.gov responds with a token, which the portal uses to generate a redirect URL to Pay.gov to enter in payment information.

8. The token and URL are returned to the original App, which stores the token and forwards the user to the redirect URL.

9. The user enters their payment information on Pay.gov and either submits or cancels, which sends them back to the corresonding success or cancel URL specified in the original request.

init-payment-flow.drawio

Process Payment on a Transaction

1. Once back on the originating app, the app makes another request to the Payment Portal to process the transaction with the token
2. Once authenticated, the Portal makes sure the App has the authority to process transactions for the Fee of the transaction that is associated with the token.
3. Once authorized, the payment portal calls Pay.gov to perform a completeOnlineCollectionWithDetails with the token.
4. Pay.gov responds with a Pay.gov Tracking ID for future, Transaction Status
5. The Portal updates the transaction information in the database
6. The Portal responds to the Application the derived Payment Status as well as any transactions that share the transaction's transactionReferenceId.

process-payment-flow.drawio

Get Details about a Payment

1. At any time the App may request information for their unique transactionReferenceId by calling the getDetails API.
2. Once authenticated, the Portal ensures the App has access to the Fee that is associated with the specified transactionReferenceId.
3. And once authorized, the Portal checks to see if there is a transaction with a Pending status. If so, the Portal will call Pay.gov with getDetails to see if the transaction status has resolved, updating its database accordingly.
4. Then the Portal will respond with the most up-to-date Payment Status as well as any transactions that share the transaction's transactionReferenceId.

get-details-flow.drawio

Environment Variables

The .env file in this repo is for local development only — it provides the variables a developer needs to run the service against the local mock Pay.gov server. Deployed environments (dev, stg, prod) get their configuration from Terraform and AWS Secrets Manager — see terraform/environments/ and ADR 0007.

For local setup instructions, see running-locally.md. The full list of variables a developer needs is in .env.example, with inline comments where the purpose isn't obvious from the name.

How the environment layer is structured

A few variables have semantic meaning beyond just "set this value":

• APP_ENV identifies the deployment topology — one of local, dev, stg, prod, or test. Read it via getAppEnv() / isLocal() / isDeployed() from src/config/appEnv.ts, not directly from process.env.
• NODE_ENV is the Node runtime mode — development, production, or test. Set automatically by Jest in test runs. Reserved for Node, Express, knex, and other libraries that consume it.
• LOCAL_DEV=true bypasses SigV4 auth for local development. Do not set in deployed environments.
• LOG_LEVEL (optional) overrides the default log level. Valid values: trace, debug, info, warn, error, fatal, silent. See Logging for details.

The dev server should be configured to point to the USTC Pay.gov test server, which is managed in a separate repository.

Deployment

This gets deployed to the USTC Website AWS Account using Terraform. You will need credentials loaded in order to perform this operation. And you will need the above environment variables specified.

See the terraform/ directory for deployment configuration and instructions.

Testing

npm run test            # unit tests
npm run test:integration # integration tests against a running local stack

Publishing to npmjs.org

This package is published to npmjs.org as @ustaxcourt/payment-portal and can be installed via:

npm install --save-dev @ustaxcourt/payment-portal

Publishing Process

1. Make changes on a feature branch
2. Add a changeset to document your changes:

   npx changeset add

   • Select the package and bump type (patch/minor/major)
   • Write a concise summary for the changelog
3. Open a PR and merge to main
4. Review and merge the "Version Packages" PR that Changesets automatically creates
5. Automatic publish via GitHub Actions to npm with provenance

For detailed instructions, see PUBLISHING.md.