Taxes

PayNext integrates with tax providers to automatically calculate, collect, and report taxes on your transactions. Configure tax once, and PayNext handles the rest—from calculating the correct rate based on customer location to reporting transactions for filing. See Integrations for supported tax providers.

How it works

Customer initiates payment

PayNext sends transaction details to your tax provider.

Tax calculated

Provider returns tax amount based on customer location and your tax behavior setting (exclusive or inclusive).

Payment authorized

Payment authorized for the total amount (subtotal + tax for exclusive, or full amount for inclusive).

Payment settles

Tax transaction submitted to provider for reporting.

Refund processed (if applicable)

Tax transaction reversed with provider.

How tax location is determined

PayNext determines the customer’s tax jurisdiction based on the payment method and available data:

Payment method	Tax location source
Apple Pay, Google Pay	Billing address from the wallet
All other methods	`zip_code` and `state` passed in the customer object
Fallback	Cloudflare geolocation from device fingerprint

For US customers, pass zip_code and state in the customer object when creating the checkout session. These two fields are the minimum required for tax calculation—in most cases, the state can be detected automatically from the zip code. For the most accurate calculation, pass the full address object. If address data is not provided, PayNext uses geolocation data from the customer’s device. Learn more about what data PayNext collects to determine tax location.

Address data and audit risk

The accuracy of your tax location data affects audit risk. When a payment method provides a full billing address (like Apple Pay or Google Pay), PayNext automatically uses it for tax calculation.

Scenario	Approach	Audit risk
Full billing address	Street-level geocoding	Low
Partial address (zip + state)	State-level tax calculation	Low
No address provided	Cloudflare geolocation (zip, state, city, coordinates)	Medium

When no customer address is provided, PayNext collects fingerprint data that includes zip code, state, city, coordinates, and IP address from the customer’s device. This approach carries medium audit risk because:

Documented methodology — Consistent, defensible process with detailed location data
Regulatory precedent — Texas PLR guidance confirms IP-based geolocation is acceptable when addresses aren’t collected
Audit trail — All geolocation data is logged and available for compliance review

Location mismatch handling

When creating a client session with customer country set to US but no address data available (no zip_code/state provided and payment method is not Apple Pay or Google Pay), PayNext falls back to device fingerprint for tax location. If the fingerprint indicates the customer is outside the US (e.g., Canada), PayNext does not calculate US sales tax for that transaction. The payment processes without tax, and the API returns the “tax doesn’t apply” response structure. This occurs because the customer’s actual location—based on fingerprint data—is outside the tax provider’s supported jurisdiction.

Disclaimer: PayNext is not a tax provider. The information on this page is for informational purposes only and should not be considered tax advice. Audit risk assessments reflect our opinion, not guidance from a tax professional. Consult a qualified tax advisor for advice specific to your situation.

Configuration

Tax configuration follows a hierarchy—set defaults globally and override tax collection at the plan level when needed.

Global settings

Configure default tax behavior in Dashboard → Integrations → Tax:

Setting	Description
Tax provider	Your connected tax provider (e.g., Numeral)
Tax behavior	`exclusive` (tax added on top) or `inclusive` (tax included in price)
Product category	Product category for tax rate determination—select from the drop-down menu. Each tax provider has its own product categories (e.g., `GENERAL_MERCHANDISE`, `SAAS_GENERAL`). Defaults to `GENERAL_MERCHANDISE` if not set.
Tax registrations	Jurisdictions where you’d like to collect tax
Collect tax automatically	When enabled, tax is calculated for all payments by default. When disabled, tax is only collected for plans explicitly configured to collect.

Plan-level settings

Override global tax collection for specific plans in Dashboard → Plans → [Plan Name]. Each plan has a collect_tax setting that controls whether tax is collected for payments under that plan:

`collect_tax`	Description
`DEFAULT`	Uses the global “Collect tax automatically” setting from your tax provider configuration
`COLLECT`	Always collect tax for this plan, regardless of the global setting
`DONT_COLLECT`	Never collect tax for this plan, regardless of the global setting

When you retrieve plan details via API, the tax object reflects this configuration:

Example plan response

{
  "id": "plan_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Pro Plan",
  "tax": {
    "collect_tax": "COLLECT"
  }
}

Use DONT_COLLECT for plans where tax should never apply (e.g., internal test plans or donation-based plans). Leave most plans on DEFAULT so they follow your global tax configuration.

Tax behavior (exclusive or inclusive) and product category are configured globally on the tax provider, not per plan. All plans that collect tax use the same behavior and product category.

Tax in API responses

All payments include a tax object. The structure varies based on whether tax was calculated for the transaction.

When tax applies

When tax is enabled for the customer’s location, the tax object includes provider details and calculation status:

Example: Tax calculated ($100 + 7% tax)

{
  "id": "pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789",
  "amount": 10700,
  "amount_usd": 10700,
  "currency_code": "USD",
  "payment_status": "SETTLED",
  
  "tax": {
    "provider": {
      "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
      "type": "NUMERAL"
    },
    "calculation_id": "calc_xxx",
    "transaction_id": "txn_xxx",
    "amount_subtotal": 10000,
    "amount_subtotal_usd": 10000,
    "amount_tax": 700,
    "amount_tax_usd": 700,
    "behavior": "exclusive",
    "status": "submitted"
  }
}

When customers pay in other currencies, use amount_subtotal_usd and amount_tax_usd to see the USD equivalent for reporting.

When tax doesn’t apply

When tax is not enabled for the customer’s location (no tax provider configured, location not in your tax registrations, or plan set to DONT_COLLECT), the provider field is null and amount_tax is 0:

Example: Tax not applicable ($100, no tax)

{
  "id": "pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789",
  "amount": 10000,
  "amount_usd": 10000,
  "currency_code": "USD",
  "payment_status": "SETTLED",
  
  "tax": {
    "provider": null,
    "amount_subtotal": 10000,
    "amount_subtotal_usd": 10000,
    "amount_tax": 0,
    "amount_tax_usd": 0
  }
}

Use the provider field to determine if tax was calculated:

provider is present → tax was calculated, check status for the outcome
provider is null → tax not applicable for this transaction

Tax fields

Field	Description
`provider.id`	PayNext internal ID for your tax provider integration
`provider.type`	Tax provider type (e.g., `NUMERAL`)
`calculation_id`	Tax provider’s calculation reference
`transaction_id`	Tax provider’s transaction reference (populated after settlement)
`amount_subtotal`	Revenue amount pre-tax
`amount_subtotal_usd`	Revenue amount in USD
`amount_tax`	Tax amount collected
`amount_tax_usd`	Tax amount in USD
`behavior`	`exclusive` or `inclusive`
`status`	Tax lifecycle status (see below)
`error`	Error details when `status` is `failed` (see When calculation fails)

Tax status lifecycle

Status	Description
`calculated`	Tax calculated during authorization, not yet reported to provider
`submitted`	Payment settled, tax transaction reported to provider
`reversed`	Payment refunded, tax transaction reversed with provider
`failed`	Calculation or transaction submission failed (see `error` for details)

Amount relationships

payment.amount = tax.amount_subtotal + tax.amount_tax

Field	Description
`amount`	Total charged to customer
`tax.amount_subtotal`	Revenue portion (pre-tax)
`tax.amount_tax`	Tax collected

When calculation fails

If the tax provider doesn’t respond within 1.5 seconds or returns an error, PayNext processes the payment without tax to ensure you don’t lose revenue. The status is failed and an error object contains the failure reason. Failed transactions appear in Dashboard → Tax → Failed where you can review and submit them manually to your tax provider.

Error code	Description
`timeout`	Tax provider did not respond within 1.5 seconds
`calculation_failed`	Tax provider request failed (see `message` for details)
Provider-specific codes	Tax provider error types are mapped directly (e.g., `INVALID_CURRENCY_CODE`, `CALCULATION_NOT_FOUND`)

Example: Timeout error

"tax": {
  "provider": {
    "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
    "type": "NUMERAL"
  },
  "calculation_id": null,
  "transaction_id": null,
  "error": {
    "code": "timeout",
    "message": "calculation timeout"
  },
  "amount_subtotal": 10000,
  "amount_subtotal_usd": 10000,
  "amount_tax": 0,
  "amount_tax_usd": 0,
  "behavior": "exclusive",
  "status": "failed"
}

Example: Provider error

"tax": {
  "provider": {
    "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
    "type": "NUMERAL"
  },
  "calculation_id": null,
  "transaction_id": null,
  "error": {
    "code": "INVALID_CURRENCY_CODE",
    "message": "Invalid customer currency code. Must be one of: EUR, RON, PLN, DKK, ..."
  },
  "amount_subtotal": 10000,
  "amount_subtotal_usd": 10000,
  "amount_tax": 0,
  "amount_tax_usd": 0,
  "behavior": "exclusive",
  "status": "failed"
}

Example: Post-capture transaction failure

When tax calculation succeeds during authorization but the transaction submission fails after capture, the status becomes failed while preserving the original calculation amounts:

"tax": {
  "provider": {
    "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
    "type": "NUMERAL"
  },
  "calculation_id": "calc_xxx",
  "transaction_id": null,
  "error": {
    "code": "CALCULATION_NOT_FOUND",
    "message": "Unable to find calculation with ID: calc_xxx in test environment."
  },
  "amount_subtotal": 10000,
  "amount_subtotal_usd": 10000,
  "amount_tax": 700,
  "amount_tax_usd": 700,
  "behavior": "exclusive",
  "status": "failed"
}

Tax calculation failures are rare. When they occur, absorbing the tax cost is preferable to declining payments and losing revenue.

Webhooks

PayNext sends tax data in the tax object of payment webhook payloads. The tax object is included in:

payment_v2.created — Initial payment with tax status: "calculated" (or "failed" if calculation errored)
payment_v2.settled — After settlement, tax status: "submitted"
payment_v2.failed — After capture failure, tax status: "failed"
payment_v2.refund.created / payment_v2.refund.settled — Tax status: "reversed" when a refund succeeds

Best practices

Use exclusive pricing for flexibility

Set your global default to exclusive. This lets you display pre-tax prices and add tax at checkout—the standard approach for US and B2B sales. Override to inclusive only for specific markets (like EU B2C) where tax-inclusive pricing is expected.

Start collecting before you register

You can start calculating and collecting tax before you’re officially registered in a jurisdiction. Once registered, most tax providers support backfilling historical transactions. PayNext returns $0 tax for customers in locations where you haven’t enabled tax collection in Integrations.

Use USD amounts for reporting

For reporting convenience, use the _usd fields (amount_subtotal_usd, amount_tax_usd) to avoid currency conversion complexity. Your final tax liability is available in your tax provider’s dashboard (e.g., Numeral)—use that information for your accounting and filing.

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

How it works

How tax location is determined

Address data and audit risk

Location mismatch handling

Configuration

Global settings

Plan-level settings

Tax in API responses

When tax applies

When tax doesn’t apply

Tax fields

Tax status lifecycle

Amount relationships

When calculation fails

Webhooks

Best practices

​How it works

​How tax location is determined

​Address data and audit risk

​Location mismatch handling

​Configuration

​Global settings

​Plan-level settings

​Tax in API responses

​When tax applies

​When tax doesn’t apply

​Tax fields

​Tax status lifecycle

​Amount relationships

​When calculation fails

​Webhooks

​Best practices

How it works

How tax location is determined

Address data and audit risk

Location mismatch handling

Configuration

Global settings

Plan-level settings

Tax in API responses

When tax applies

When tax doesn’t apply

Tax fields

Tax status lifecycle

Amount relationships

When calculation fails

Webhooks

Best practices