Skip to main content
The Maven JS SDK is a thin wrapper that mounts the secure iframe into your page and forwards lifecycle events to callbacks. It does not ship business logic — all the heavy lifting (tokenization, gateway charging) happens server-side.

​
Installation

<script src="https://api.trymaven.com/widget/v1/widget.js"></script>
After load, the global Maven object is available.
The SDK is served with Cache-Control: public, max-age=31536000, immutable — the versioned URL (/v1/widget.js) never changes, so browsers cache it for a year. Bump the major version only for breaking changes.

​
Maven.createPayment(options)

Creates a widget controller. Does not mount until you call .mount(target).

​
Options

OptionTypeRequiredDescription
sessionIdstring✓Session ID returned by POST /v1/widget-sessions
baseUrlstringOverrides Maven API base (defaults to wherever widget.js is loaded from). Only needed for multi-region or pointing at staging.
onReady() => voidFires when the iframe is fully loaded and the form is interactive.
onSuccess(result) => voidFires when payment succeeds. See result shape below.
onFailure(error) => voidFires when payment fails. See error shape below.
Theme, labels, and fields are set per-project in the dashboard — not on the SDK call. See Customization.

​
Returns

A controller object: 
interface PaymentController {
  mount(target: string | HTMLElement): PaymentController;
  updateTheme(theme: Theme): PaymentController;
  updateLabels(labels: Labels): PaymentController;
  updateFields(fields: Fields): PaymentController;
  destroy(): void;
  iframe: HTMLIFrameElement;
}

​
controller.mount(target)

Inserts the iframe into the DOM. 
controller.mount("#chat-payment-slot");       // CSS selector
controller.mount(document.getElementById("slot"));  // element directly
The iframe fills 100% of the target’s width and auto-grows its height via maven:resize postMessage — your container controls the width, Maven handles the height.

​
onSuccess(result)

Fires when the gateway charge succeeds. 
onSuccess: (result) => {
  result.transaction_id  // gateway transaction ID
  result.card_brand      // "visa", "mastercard", "amex", "discover"
  result.card_last4      // "4242"
  result.amount_cents    // 10000
  result.currency        // "USD"
  result.status          // "succeeded"
}

​
onFailure(error)

Fires when the charge is declined or errors. 
onFailure: (error) => {
  error.error_code     // "card_declined", "insufficient_funds", etc.
  error.error_message  // Human-readable message to show the customer
}
The widget itself shows the failure state (red “Payment Failed” box + “Try Again” button). Your onFailure callback is for doing things in your UI — sending a follow-up chat message, tracking the failure in analytics, etc.

​
Cleanup

When the chat bubble unmounts (user navigates away, chat closes, etc.), destroy the widget to remove listeners: 
payment.destroy();

​
Full example

const payment = Maven.createPayment({
  sessionId: sessionIdFromServer,
  onReady: () => {
    console.log("widget loaded");
  },
  onSuccess: (result) => {
    chatbot.sendBotMessage(
      `Payment received — ${result.card_brand.toUpperCase()} ending ${result.card_last4}.`
    );
    orderService.markPaid(orderId, result.transaction_id);
  },
  onFailure: (error) => {
    chatbot.sendBotMessage(
      `Payment didn't go through: ${error.error_message}. Want to try another card?`
    );
  },
});

payment.mount("#chat-payment-slot");

​
Security model

  • The iframe is served from Maven’s domain, not yours — your page’s JavaScript cannot read the card inputs or inspect the form (enforced by the browser’s same-origin policy).
  • Communication between your page and the iframe is one-way via postMessage — the iframe posts events up, the SDK listens. No DOM access.
  • The sessionId is a single-use credential. It expires after a short TTL (default 5 minutes) and can only be used to charge the specific amount on the specific project it was created for.

​
Next

Customization

Theme, labels, fields, sizing.

Webhooks

Server-side confirmation events.