Widget Quickstart

Set up your project

If you haven’t already: create an account, create an app, connect a gateway, and grab a test API key (mvn_test_*). Same setup as voice — gateway connections and API keys are shared.

Customize the widget (optional)

Open your app → Chat Payments tab in the dashboard. Set your colors, labels, and which fields to show (cardholder name, billing ZIP). Hit Save.These settings apply automatically to every session from this project. You can still override per-session via the API, but most merchants just set it once.

Server — create a session

When your chatbot is ready to collect payment, your backend calls:

curl https://api.trymaven.com/v1/widget-sessions \
  -H "Authorization: Bearer $MAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "gateway": "stripe",
    "amount_cents": 10000,
    "description": "Order #1234"
  }'

const res = await fetch("https://api.trymaven.com/v1/widget-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAVEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    project: "my-app",
    gateway: "stripe",
    amount_cents: 10000,
    description: "Order #1234",
  }),
});
const { session_id } = await res.json();

import os, requests

r = requests.post(
    "https://api.trymaven.com/v1/widget-sessions",
    headers={"Authorization": f"Bearer {os.environ['MAVEN_API_KEY']}"},
    json={
        "project": "my-app",
        "gateway": "stripe",
        "amount_cents": 10000,
        "description": "Order #1234",
    },
)
session_id = r.json()["session_id"]

Response:

{
  "session_id": "8a7f3d2b-...",
  "widget_url": "https://api.trymaven.com/widget/8a7f3d2b-...",
  "expires_at": "2026-04-14T19:15:00Z"
}

Hand the session_id to your frontend — via WebSocket message, HTTP response, whatever your chatbot uses.

Frontend — load the SDK once

Add this once to your page, ideally before your chatbot renders:

<script src="https://api.trymaven.com/widget/v1/widget.js"></script>

This exposes a global Maven object with one method: createPayment().

Frontend — mount the widget when ready

When your chatbot receives the session_id, mount the widget into a <div> inside the chat message:

const payment = Maven.createPayment({
  sessionId: "<SESSION_FROM_YOUR_SERVER>",
  onSuccess: (result) => {
    // result = { transaction_id, card_brand, card_last4, amount_cents, currency, status }

    // Typical things to do here (all optional — Maven already shows
    // a green "Payment confirmed" screen inside the iframe):
    chatbot.sendMessage(`Paid — ${result.card_brand} •• ${result.card_last4}`);
    await db.orders.markPaid(orderId, result.transaction_id);
    // or: window.location = `/thanks?txn=${result.transaction_id}`;
  },
  onFailure: (error) => {
    // error = { error_code, error_message }
    chatbot.sendMessage(`Payment didn't go through: ${error.error_message}`);
  },
});

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

The iframe appears inline. Customer types their card, hits pay. Your callbacks fire — onSuccess and onFailure are hooks into your app so you can continue the chatbot conversation, update your database, or redirect the customer. The widget itself handles the card form, charging, and the success/failure UI inside the iframe.

Handle webhook (recommended)

Configure a webhook URL on the project. Maven fires the same payment-success / payment-failed event for widget payments as it does for voice — with an additional source: "chat" field.See Webhooks for the full payload.

Common errors

POST /v1/widget-sessions can return these if something’s off in your setup:

Status	Code	What it means	Fix
`401`	—	Bad or missing API key	Check the `Authorization: Bearer mvn_test_...` header
`404`	`project_not_found`	Project slug doesn’t exist in your org	Double-check the `project` value matches a slug in your dashboard
`422`	`gateway_not_connected`	Gateway isn’t connected for this env	Connect the gateway in the dashboard (Gateways tab). Test keys need test credentials; live keys need live credentials.
`422`	`invalid_amount`	`amount_cents` is 0 or negative in charge mode	Pass `amount_cents > 0`, or use `mode: "tokenize"` to save a card without charging
`429`	—	Rate limited	Back off; defaults are 20 session creates/minute per IP

If the widget mounts but doesn’t render, check your browser console. The usual culprit is Maven is not defined — that means the <script src="…"> tag didn’t load. Hard-refresh and check the URL is reachable.

Test cards

Use these with your mvn_test_* key against a gateway in sandbox mode:

Outcome	Number	CVV	Expiry
Success	`4242 4242 4242 4242`	Any 3 digits	Any future date
Declined	`4000 0000 0000 0002`	Any 3 digits	Any future date
Amex	`3782 822463 10005`	Any 4 digits	Any future date

Full example — vanilla JS chatbot

<!doctype html>
<html>
<body>
  <div id="chat">
    <!-- messages appended here -->
  </div>

  <script src="https://api.trymaven.com/widget/v1/widget.js"></script>
  <script>
    async function collectPayment(amount) {
      // 1. Ask your server to create the session
      const { sessionId } = await fetch("/api/create-payment-session", {
        method: "POST",
        body: JSON.stringify({ amount }),
      }).then(r => r.json());

      // 2. Add a chat bubble that will host the widget
      const bubble = document.createElement("div");
      bubble.className = "chat-message bot";
      bubble.innerHTML = `<div class="slot"></div>`;
      document.getElementById("chat").appendChild(bubble);

      // 3. Mount the widget into that bubble
      Maven.createPayment({
        sessionId,
        onSuccess: (result) => {
          addBotMessage(`Paid — ${result.card_brand} •• ${result.card_last4}`);
        },
        onFailure: (error) => {
          addBotMessage(`Payment failed: ${error.error_message}`);
        },
      }).mount(bubble.querySelector(".slot"));
    }
  </script>
</body>
</html>

SDK Reference

Complete options, callbacks, and controller methods.

Customization

Theme, labels, fields, and sizing options.

​Common errors

​Test cards

​Full example — vanilla JS chatbot

​Next

SDK Reference

Customization

Common errors

Test cards

Full example — vanilla JS chatbot

Next