Numeral Payments Integration

Numeral automates sales tax calculation, collection, and reporting for Adobe Commerce merchants. The extension connects your store to the Numeral tax engine, which determines accurate tax rates in real time at checkout based on product taxability, customer location, and jurisdiction-specific rules.

Getting sales tax right is complex. Tax rates vary across thousands of jurisdictions, change frequently, and depend on product type, customer exemptions, and location. Numeral handles this complexity so you can focus on growing your business.

Account & Pricing

To use this extension, you need a Numeral account. Visit numeralhq.com to sign up. The extension can be installed and configured independently, but an API key is required to activate real-time tax calculations.

How It Works

When a customer enters their shipping address at checkout, Numeral calculates the applicable tax in real time. The tax amount and jurisdiction breakdown (state, county, city, district) are displayed in the cart and order summary. When the order is invoiced, the tax transaction is automatically committed to Numeral for reporting. When a credit memo is issued, the transaction is automatically voided or partially refunded.

Features

• Real-Time Tax Calculation
  • Numeral determines the correct tax rate at checkout based on the customer's shipping address and the applicable jurisdiction rules. Tax rates are always up to date without any manual configuration in the store.
• Jurisdiction-Level Breakdown
  • Customers see a detailed tax breakdown by jurisdiction (e.g., California state tax, Los Angeles county tax) in the cart and checkout, providing full transparency.
• Automatic Transaction Lifecycle
  • Tax transactions are committed when an invoice is created and voided when a credit memo is issued. Partial invoicing and partial refunds are fully supported, with each invoice generating its own tax transaction.
• Two-Tier Caching for Performance
  • The extension uses an in-memory cache (per request) and a persistent Redis cache (cross-request) to reduce API calls. Magento typically calls the tax engine 4-8 times per page load with identical data; Numeral deduplicates these down to a single API call per unique cart state.
• Smart Address Validation
  • During progressive checkout, customers type their address incrementally. The extension validates that the address has a state code and a properly formatted postal code before making an API call, avoiding unnecessary requests on incomplete input. Invalid addresses silently fall back to native Magento tax.
• Native Magento Tax Fallback
  • If the Numeral API is temporarily unavailable, the extension automatically falls back to Magento's built-in tax engine. The checkout experience is never interrupted.
• Multi-Website Support
  • API keys and test mode settings are configured at the website scope, allowing different Numeral accounts or configurations per website in a multi-website setup.
• Encrypted API Key Storage
  • The API key is stored using Magento's encrypted configuration backend, ensuring credentials are never stored in plain text.
• Test Mode
  • Enable test mode to validate tax calculations in a sandbox environment without recording real transactions. Useful during initial setup and testing.
• Debug Logging
  • When enabled, all API requests and responses are logged to var/log/numeral_tax.log for troubleshooting.
• Configuration
  • After installation, configure the extension at Stores > Configuration > Numeral > Tax Settings:
  • Enable/Disable the extension
  • Enter your Numeral API key
  • Toggle test mode on or off
  • Enable debug logging for troubleshooting
  • Access to this configuration is controlled by the Numeral_Tax::config ACL resource.

Compatibility

• Adobe Commerce (cloud): 2.4
• Adobe Commerce (on-prem): 2.4
• Magento Open Source: 2.4
• PHP: 8.1, 8.2, 8.3

Security

The Numeral extension uses an API-based integration to calculate tax, sync product data, record order tax transactions, and process order void/refund events. The extension communicates with Numeral over HTTPS using authenticated REST API requests. It does not use a payment redirect flow and does not act as a payment gateway.

This extension does not collect, process, transmit, or store cardholder data. Customers do not enter credit card numbers, CVV codes, expiration dates, or other payment card data into the Numeral extension, and no payment card data is sent to Numeral. Payment collection remains the responsibility of the merchant’s existing Magento payment provider or payment extension.

Because the Numeral extension is not involved in payment acceptance and does not handle cardholder data, it does not add PCI DSS cardholder-data scope to the Magento environment. The integration is compatible with an SAQ A payment environment when the merchant’s separate payment provider fully hosts or redirects payment collection in accordance with SAQ A eligibility requirements. The merchant’s final SAQ level depends on their selected payment provider and payment implementation, but the Numeral extension itself does not require SAQ A-EP, SAQ C, or SAQ D due to any Numeral payment-data handling.

The API requests sent by the extension include only the information required for tax calculation and transaction recording, such as product identifiers, product descriptions, quantities, prices, discounts, shipping amount, currency, order identifiers, and shipping address information. This information is used to calculate applicable tax and maintain tax transaction records.

Customer payment data is not entered into the Magento server through this extension. Customer payment data is not stored on the Magento server by this extension. The extension also does not create custom Magento storage for cardholder data or other payment credentials.

Customer non-payment data, such as shipping address and order details, may be entered into and stored by Magento as part of the merchant’s normal checkout and order management process. The Numeral extension does not add additional customer data collection beyond the standard checkout/order data needed for tax calculation, and it does not store customer payment data in Magento.

Support

For technical support, contact support@numeralhq.com or visit numeral.com/docs.