JavaScript SDK Reference

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

Option	Type	Required	Description
`sessionId`	string	✓	Session ID returned by `POST /v1/widget-sessions`
`baseUrl`	string		Overrides Maven API base (defaults to wherever `widget.js` is loaded from). Only needed for multi-region or pointing at staging.
`onReady`	`() => void`		Fires when the iframe is fully loaded and the form is interactive.
`onSuccess`	`(result) => void`		Fires when payment succeeds. See result shape below.
`onFailure`	`(error) => void`		Fires 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.

Customization

Theme, labels, fields, sizing.

Webhooks

Server-side confirmation events.

​Installation

​Maven.createPayment(options)

​Options

​Returns

​controller.mount(target)

​onSuccess(result)

​onFailure(error)

​Cleanup

​Full example

​Security model

​Next

Customization

Webhooks

Installation

`Maven.createPayment(options)`

Options

Returns

`controller.mount(target)`

`onSuccess(result)`

`onFailure(error)`

Cleanup

Full example

Security model

Next