Vertex Tax

Article Topics: NATS Admin, Billers, Payments

NATS integrates with Vertex O Series to automatically look up a current tax rate for a customer's country and ZIP code. NATS caches the rate it receives, writes it to the existing Tax Rates table, and uses it for price display and transaction tax recording. If Vertex is unavailable, NATS falls back to the tax rate already stored for that country and region.

A global Vertex included-tax mode lets any biller use Vertex without dynamic pricing, keeping the configured option amount unchanged and calculating the tax portion inside that amount. Biller-level exclusive-tax settings remain available for billers that can accept a tax-added price.

Configuration

Enable Vertex only after your OAuth credentials and seller information have been entered in Configuration Admin. The following settings control the integration:

• VERTEX_ENABLED: Enables live Vertex requests once the required credentials and seller fields are configured. Default: Off

• VERTEX_INCLUDED_TAX_ALL_BILLERS: Uses Vertex for prices that already include tax when a biller has no saved exclusive-tax mapping. The amount submitted to the biller does not change. Default: Off

• VERTEX_ALLOWED_COUNTRIES: Limits live Vertex requests to the configured ISO country codes. Leave blank to permit every country. Default: US

• VERTEX_CLIENT_ID and VERTEX_CLIENT_SECRET: OAuth credentials used to request a Vertex access token. Default: Blank

• VERTEX_SELLER_COMPANY and seller origin: Identifies the seller and the seller's physical origin in the Vertex request. Default: Blank and IL, US

• VERTEX_PRODUCT_CODE and VERTEX_PRODUCT_CLASS: Identifies the subscription product in the Vertex quotation. Default: NATS-SUBSCRIPTION and Streaming Subscription

• VERTEX_DEFAULT_TAX_DEDUCT: The default tax deduction rule applied only to a newly created Tax Rate. Existing tax rates keep their own deduction setting. Default: 0

• VERTEX_TAX_CACHE_SECONDS: The minimum age before a country and ZIP lookup is refreshed. NATS enforces a minimum of 60 seconds. Default: 3600

• VERTEX_TRANSACTION_TIMEOUT: The timeout for a live signup lookup, limited to five seconds or less. Default: 5 seconds

• VERTEX_CRON_TIMEOUT and VERTEX_DAILY_CRON: Controls the daily refresh of already-initialized Vertex locales. Default: 30 seconds and On

Biller Tax Mode Priority

A saved biller account tax mapping always takes priority over the global included-tax setting. This preserves existing exclusive-tax billers while letting unmapped billers use Vertex included tax.

Saved Biller Mapping	Global Included Mode	Effective Behavior
No exclusive-tax value saved	Off	Normal NATS included-tax calculation using the Tax Rates table.
No exclusive-tax value saved	On	Vertex included-tax calculation. The configured price is sent to the biller unchanged.
Included Taxes	On or Off	Normal NATS included-tax calculation. The saved biller setting overrides the global setting.
Exclusive Taxes	On or Off	NATS adds tax to the price before sending the amount to the biller. The biller must support dynamic pricing.
Exclusive Taxes Vertex	On or Off	Vertex supplies the rate and NATS adds tax to the outgoing price. The biller must support dynamic pricing.

Location and Rate Lookup

NATS needs a country and ZIP code to perform a Vertex calculation. The ZIP is resolved from the stored member subscription's tax ZIP value when available. Otherwise, NATS can derive a ZIP from the member's IP address or use the server-detected ZIP supplied while displaying signup options. NATS does not send customer city or state to Vertex, since those values can conflict with the ZIP code.

The Vertex request sends the buyer's country and ZIP, your seller configuration, product details, and the quoted amount, using a quotation sale type. Your configured seller state remains part of the seller origin information.

Signup and Price Display

1. Select option: Gateway signup, signup, and plus pages obtain the selected option and the available customer tax location.

2. Check cache: NATS checks the cached lookup table for a valid Vertex result for the network's country and ZIP.

3. Refresh rate: If the cache is stale, NATS requests a short-timeout Vertex quotation. A successful response updates the Tax Rates table and the cache.

4. Display price: Included-tax mode leaves the configured initial and rebill price unchanged. Exclusive-tax mode displays the configured price plus tax.

5. Submit charge: Included-tax mode sends the configured amount to any biller. Exclusive-tax mode sends the tax-added amount only to billers that support dynamic pricing.

Templates can use pre_tax_initial, tax_initial, tax_amount_initial, pre_tax_rebill, tax_rebill, and tax_amount_rebill. In included-tax mode, the pre-tax and tax values are the same as the configured price. In exclusive-tax mode, pre-tax is the configured price and tax is the price including tax.

Transaction Recording

When a sale is recorded, NATS determines the effective biller tax mode. In global Vertex included-tax mode, NATS keeps the received transaction amount unchanged and uses the Vertex rate to calculate the tax portion within that amount. In exclusive-tax mode, the transaction amount already includes the tax-added charge, so NATS extracts the tax portion from the total.

The existing transaction tax fields and tax deduction logic continue to be used. The total transaction amount remains the amount actually charged to the customer, including tax when tax applies.

Cache Storage and Daily Refresh

NATS stores the Vertex source, country, ZIP, associated tax row, calculated tax percentage, validity flag, and the last checked and updated timestamps in a lookup cache. This avoids repeated live requests during the configured cache window.

A successful lookup updates an existing Tax Rate for the country and region, or creates one when none exists. Existing tax deduction values are never overwritten; a new row receives the value set in VERTEX_DEFAULT_TAX_DEDUCT.

The daily Vertex cron refreshes initialized cache locales using the longer cron timeout. It's controlled by VERTEX_DAILY_CRON and should remain enabled after Vertex has been configured.

Failure Handling and Logging

If Vertex doesn't return a usable result, times out, receives an HTTP error, or returns invalid data, NATS records the failed lookup time and falls back to the stored Tax Rate. The failed result never overwrites a valid cached tax rate.

When Vertex is configured and a live call fails, NATS sends a notification. Enable VERTEX_LOGGING to record request outcomes, HTTP status, response details, the source file that made the call, and the lookup location. OAuth credentials and access tokens are never written to the Vertex log events.

Related Articles

TaxesAdding a New Tax