Integration & Configuration Guide

Welcome to the TaxWisp Platform Independent (Standalone) Integration Guide. This guide walks you through connecting any custom ecommerce platform, custom storefront, or ERP system to TaxWisp for automated, compliant sales tax exemption management.

---

Architecture Overview

The TaxWisp integration is designed around a secure backend-to-backend architecture paired with modern frontend presentation options. Your ecommerce backend interacts directly with the TaxWisp REST API, ensuring sensitive API credentials are never exposed to client browsers.

flowchart TD
    subgraph Client["Your Frontend / Storefront"]
        User["Customer / Buyer"]
        UI["Storefront UI / Checkout"]
        Widget["TaxWisp Embedded Widget or Hosted Portal"]
    end

    subgraph StoreBackend["Your Backend Server"]
        AppServer["Ecommerce Application / Server"]
        DB[("Your Store Database")]
        OrdersAPI["GET /orders Endpoint"]
    end

    subgraph TaxWisp["TaxWisp Cloud Platform"]
        API["TaxWisp Integration API"]
        AdminDashboard["TaxWisp Merchant Dashboard"]
        AnalyticsEngine["TaxWisp Analytics Engine"]
    end

    User -->|1. Requests Exemption| UI
    UI -->|2. Request Exemption Session| AppServer
    AppServer -->|3. POST /customer-sessions| API
    API -->|4. Return token & redirectUrl| AppServer
    AppServer -->|5. Hand off session| UI
    UI -->|6. Launch Modal or Redirect| Widget
    Widget -->|7. Uploads Exemption Certificate| TaxWisp
    AdminDashboard -->|8. Merchant Reviews & Approves| TaxWisp
    AppServer -->|9. GET /tax-exemptions Sync| API
    API -->|10. Exemption Records| AppServer
    AppServer -->|11. Update Customer Status| DB
    AnalyticsEngine -->|12. Periodic GET /orders| OrdersAPI

---

Core Components

Component	Role	Security Context
Customer Session API	Initiates an exemption session for a customer and returns a secure token and URL.	Backend server only (X-TaxWisp-Api-Key)
Customer Portal / Widget	UI where customers upload certificates, sign declarations, and submit exemption requests.	Client-side frontend
Tax Exemption Data Sync API	Periodically retrieves approved exemptions so your store can exempt qualified orders.	Backend server only (X-TaxWisp-Api-Key)
Analytics Orders API	An endpoint on your server that TaxWisp queries to compute exemption analytics and reporting.	Your backend (X-Api-Key or Bearer Token)

---

Choosing Your Customer Experience

TaxWisp provides two flexible frontend integration options for collecting tax exemption documents from your buyers:

Capability	Customer Portal Redirect	Embedded Widget
User Experience	Redirects customer to hosted TaxWisp portal	Opens an in-page modal directly on your store
Implementation Effort	Minimal (backend session + frontend redirect)	Fast (CDN script + CSS + 1 JS function call)
Branding & Cohesion	Full-page standalone flow hosted by TaxWisp	Keeps customer seamlessly within your application
Session Requirements	Requires redirectUrl from Session API	Requires both token and redirectUrl
Fallback Support	Hosted directly by TaxWisp	Includes built-in fallback to hosted portal
Recommended For	Standard checkouts, mobile redirects, minimal JS apps	Rich SPA applications, customer account portals

---

Integration Roadmap

To launch TaxWisp on your ecommerce platform, follow these steps:

graph LR
    A["1. Obtain API Credentials"] --> B["2. Configure Store & Team"]
    B --> C["3. Implement Exemption Flow"]
    C --> D["4. Sync Exemption Records"]
    D --> E["5. Connect Analytics Orders API"]

1. Authentication & API Keys: Retrieve your API key from the TaxWisp dashboard and configure server-side authentication.
2. Store & Team Configuration: Set up your physical store locations (nexus) and invite team members to review exemption certificates.
3. Implement Customer Exemption Request:
   • Choose Customer Portal Redirect for full-page redirection.
   • Choose Embedded Widget for an in-app modal experience.
4. Implement Tax Exemption Data Sync: Pull approved exemptions into your database and apply zero-tax logic during checkout.
5. Set Up Orders API Configuration: Expose your /orders endpoint and register credentials in TaxWisp for automated analytics.

---

Next Steps

• Proceed to Authentication & API Keys to configure your API credentials and security headers.