This document outlines the end-to-end process for integrating third-party tax providers into the Infosys Equinox Commerce platform, detailing webhook usage, merchant configuration, and testing protocols for seamless ecommerce transactions.

Tax Extensions

Tax extensions are specific APIs within the Tax service that enable app developers to extend functionality by integrating with third-party tax providers and building custom tax calculation engines for their e-commerce storefronts.

Key capabilities include:

  • Providing merchants with external tax calculation methods
  • Automating tax calculations during checkout
  • Supporting both tax-inclusive and tax-exclusive item pricing

Tax App Overview

A tax app is a connector that enables tax calculation from third-party providers and seamlessly integrates it into the platform’s checkout flow. The platform invokes the tax app’s endpoints whenever any item is added to a cart, gets the tax quote and adjusts it in the cart price breakdown.

The tax provider may support additional use cases such as record keeping for calculating an organization’s tax liability, auto filing of taxes, calculating similar surcharges like export/import fees, etc.

Please make sure that you are using some sort of address verification and recommendation app for your storefront, preferably from the tax provider itself, as tax calculation relies heavily on address accuracy. If a customer misses a field or makes a wrong entry, the tax provider will not generate an accurate quote.

Generating Tax Quotes in the Infosys Equinox E-commerce Platform

  1. Merchant Account Configuration and Validation:

Upon app installation, merchants are required to provide their credentials and along with other information on the app configuration page. The Infosys Equinox platform triggers the validate webhook extension to notify the app of this event.

    • Webhook Trigger: appmarketplaceservices/validator/merchantdetails
    • App Function Responsibilities:
      • Validate merchant credentials with the third-party tax service
      • Return a success or failure response to Infosys Equinox
      • Store validated credentials for future API calls
    • Configuration Details:
      • The specific configuration elements required vary by app and are defined in the app creation JSON file by the developer.
      • Refer to the provided JSON template for sample structure and fields.
  1. ParameterStoreAPIFunction
    • Purpose: Stores the app secret key securely.
    • Webhook: appmarketplaceservices/generateapikeyandsecret/create
    • Steps:
      1. Receive API secret key.
      2. Write to parameter store.
      3. Return confirmation response.
  1. Calculate Tax
    • Webhook: taxservice/tax/calculatetax
    • Responsibilities:
      • Receive order details and price breakdown of cart details, address details along with app configurations such as ‘store has tax inclusive prices’, ‘calculate tax on shipping charge’, etc.
      • Call Avalara’s CreateTransaction API to get a quote for the configured line items.
      • Some providers may require additional information such as whether items or customers are tax exempt, etc. Ensure that this app function passes these onto the tax provider.
      • Return calculated tax amounts per line item.
  1. Authorize Tax
    • Webhook: taxservice/tax/authorizetax
    • Responsibilities:
      • This will confirm the tax calculation before order placement and create an entry with the tax provider. You may decide to commit / finalize the transaction here or later when the order is shipped. This will impact on your approach for cancelling and voiding entries on order cancellations or refunds later on.
  1. Cancel Tax
    • Webhook: taxservice/tax/canceltax
    • Responsibilities:
      • Cancel tax transaction if order is canceled.
  1. Commit Tax
    • Webhook: taxservice/tax/committax
    • Responsibilities:
      • Finalize tax transaction after order fulfillment.
  1. Refund Tax
    • Webhook: taxservice/tax/refundtax
    • Responsibilities:
      • Process tax refunds for returned items by voiding the original tax entry

Testing

Ensure that your tax app meets the following functional requirements:

  1. Verify that users can install the tax app from the App Marketplace.
  2. Test app activation with both valid and invalid configurations, ensuring appropriate error messages are displayed.
  3. Ensure that the tax quote is updated in the cart only when the user has specified an address. Confirm that this quote matches the one generated directly in the third-party tax provider’s dashboard. You can do this by recreating the transaction in the dashboard.
  4. Verify that additional use cases, such as tax exemptions for customers or items, function correctly when configured.
  5. Confirm that tax transactions are committed upon order fulfillment.
  6. Confirm that tax transactions are canceled in the event of order cancellations or refunds.

Revision History
2025-07-11 | JP – Added the content.