How tonderio/tonder-sdk works
Project type and purpose
• This is a front‑end JavaScript/TypeScript SDK (tonder-web-sdk) designed to be embedded into merchant websites to provide payment checkout functionality (InlineCheckout and LiteCheckout).
• It exposes a widget that runs entirely in the browser, communicates with Tonder’s REST APIs, integrates with Skyflow (for card tokenization) and OpenPay (for APMs), and supports HMAC signature validation.
Top‑level structure highlights
• src/ – Contains all SDK source code, organized by concern:
• classes/: Core classes (InlineCheckout, LiteInlineCheckout, 3DS handling, loaders)
• data/: Modules to call each external API (checkoutApi, cardApi, customerApi, apmApi, skyflowApi, openPayApi, businessApi)
• helpers/: Templating, style injection, validation utilities
• shared/: Constants, catalogs (logos, payment methods), shared utils (apiFetch)
• index.js / index-dev.js / index.html: Entry points for bundling and local dev/demo
• types/ – TypeScript definitions for public interfaces and domain objects
• webpack.config.js – Bundles the SDK into a minified UMD/ESM library (v1/bundle.min.js)
• samples/ – Example React app demonstrating SDK integration
• cypress/ – End‑to‑end test suite with scenarios for widget mounting and payment flows
Key architectural patterns
• Modular layering:
a. Presentation layer (templating + style injection)
b. SDK façade (InlineCheckout and LiteCheckout classes, providing a simple public API)
c. Business logic (3DS flow, checkout configuration, event callbacks)
d. Data access layer (one module per external HTTP endpoint)
e. Shared utilities (HTTP fetch wrapper, HMAC helpers, validation, constants)
• Dependency inversion: public classes depend on abstracted API modules (e.g., customerApi, skyflowApi)
• Plugin‑style injection: the SDK dynamically injects HTML/CSS into the host page’s DOM
Main components
A. Host Web Application
• Optionally imports via NPM or <script> tag
• Instantiates new InlineCheckout() or new LiteCheckout()
• Provides merchant API key, returnUrl, styles, callbacks
B. Tonder Web SDK
1. Public API (InlineCheckout, LiteCheckout)
2. UI Engine (template-skeleton.js, template.js, styles.js)
3. Business Controllers (3dsHandler, BaseInlineCheckout, inlineCheckout.js, liteInlineCheckout.js)
4. Data Access Modules (checkoutApi.js, customerApi.js, cardApi.js, apmApi.js, skyflowApi.js, openPayApi.js, businessApi.js)
5. Shared Utils/Constants (apiFetch, validation functions, catalogs, constants)
6. Type Definitions (types/*.d.ts)
C. External Services
• Tonder REST API (the backend servicing payment creation, 3DS verification)
• Skyflow Tokenization Service (card field tokenization)
• OpenPay APM Scripts (handle certain payment methods)
• HMAC Signing (performed client‑side for the SDK or server‑side for direct REST calls)
D. Testing & Build Tools
• Webpack (build pipeline)
• Cypress (E2E tests mounting the widget and simulating payments)
• ESLint / Prettier / Husky (code quality and pre‑commit hooks)
Relationships & data flow
• Host App → instantiate SDK → configureCheckout() (loads initial payload)
• SDK → injectCheckout() → renders HTML into DOM
• User enters card/APM data → SDK Validation Helpers →
• for card: invokes Skyflow JS to tokenize sensitive data
• for APM: invokes OpenPay scripts if required
• SDK Data Access → calls Tonder REST via checkoutApi (attaching HMAC signature headers)
• For 3DS: SDK 3dsHandler intercepts redirect flow, returns result via verify3dsTransaction()
• Responses & errors bubble back to Host App via callbacks or returned Promises