Encryption for Drop-in UI

This page explains how encryption protects sensitive data used by the Drop-in UI. It covers what is encrypted, where encryption happens in the Drop-in flow, and how we help ensure confidentiality and integrity—independent of transport security.

How encryption works

TaxBandits uses a hybrid model behind the scenes:

• Asymmetric Encryption (RSA-OAEP with SHA-256): Used to encrypt/decrypt the symmetric AES key.
• Symmetric Encryption (AES-GCM 256-bit): Used to encrypt/decrypt the actual request and response payload.

This combination leverages the speed of symmetric encryption for data processing and the security of asymmetric encryption for key exchange.

Key structure

• RSA public key: Used by the frontend (JavaScript) to encrypt the AES key before sending a request to the API.
• RSA private key: Used by the backend to decrypt the AES key and then decrypt the payload.

Key separation

• Request flow: The client encrypts with the public key; the server decrypts with the private key.
• Response flow: The reverse is used if needed, maintaining distinct key usage in each direction.

This separation supports end-to-end encryption in both directions.

Request/Response flow

Parameters:

Frontend → API	API → Frontend
Generate a random AES key and IV (initialization vector) for the request.	The server generates a fresh AES key and IV for the response.
Encrypt the request payload using AES-GCM.	Encrypt the response payload using AES-GCM.
Encrypt the AES key using the RSA public key.	Encrypt the AES key using the RSA public key (as expected by the client).
Send the encrypted AES key, encrypted payload, and IV as the request.	Send the encrypted key, encrypted payload, and IV in the response.
The API uses the RSA private key to decrypt the AES key and then uses it (with the IV) to decrypt the payload.	The client uses the RSA private key to decrypt the AES key and then decrypts the payload.

How encryption is applied in the Drop-in flow

1) Transient token issuance

• You create a JWS using your API credentials and call the transient token endpoint with allowed origins.
• Server validates and returns a short-lived transient token (default ~15 minutes).
• No recipient PII is placed in this token.

Why it matters: The token is scoped to your origins and time-boxed, preventing reuse elsewhere.

2) Form render (LoadFormW9)

• Your app calls LoadFormW9(<transientToken>, <options>).
• Server encrypts and binds the supplied options (e.g., PayeeRef, theme, IsTINMatching) to that token.
• Server returns a secure, encrypted Drop-in URL that is embedded as an iframe.

Result: The effective configuration is encrypted and token-bound server-side. The browser never sees plaintext config.

3) In-iframe W-9 completion

• The iframe loads securely from TaxBandits, decrypts server-side, and renders the form UI.
• Recipient data is captured and stored securely by TaxBandits —not exposed to your frontend.

4) Status and notifications (FYI)

• Completion status is delivered via Webhook and/or** Web Messaging** (postMessage).
• Payloads are minimized and designed to avoid exposing sensitive values in the browser.
• TIN visibility follows your TIN visibility settings (e.g., mask vs. include in webhook).

What is protected

• Configuration bound to the form (e.g., PayeeRef, theme, redirect URLs, IsTINMatching)
• Recipient inputs inside the form (e.g., name, TIN, address)
• The iframe render URL (an opaque, encrypted context)

Sensitive values are never exposed in browser DevTools (Network or Console) when using Drop-in UI.

Security benefits

• Confidentiality: Payloads are unreadable without the private RSA key.
• Perfect forward secrecy: Every request/response uses new AES keys and IVs.
• Replay protection: IVs are unique per encryption; replaying old payloads will not succeed.
• TLS-independent protection: Even if TLS is compromised, the encrypted data remains protected.
• Data integrity via AES-GCM: GCM provides built-in authentication to prevent tampering.
• No persistent keys shared: Only ephemeral keys are exchanged per session—no static secrets.

Key lifecycle and rotation (optional)

To enhance security, rotate keys periodically:

• Update the frontend with the new public key.
• Switch the backend to the corresponding private key.
• Maintain key versioning (e.g., a key ID) if necessary.

This reduces long-term risk and supports compliance with cryptographic standards.

This encryption model ensures

• All payloads are securely protected in transit.
• Each transaction uses fresh, non-reusable keys.
• The system is resilient against common attacks (MITM, replay, tampering).
• The design works with—or independently of—TLS, adding a defense-in-depth layer.