Skip to main content

SDK Reference

The Paystar JavaScript SDK provides methods to open payment forms and manage user flows on your website.

Installation​

Add this snippet to your HTML <head> or before the closing </body> tag:

<script>
  !(function () {
    var n = (window.Paystar = window.Paystar || []);
    if (!n.x) {
      ((n.x = !0),
        (n.m = [
          "initialize",
          "completePayment",
          "startFlow",
          "subscribe",
          "destroy",
        ]),
        (n.f = function (t) {
          return function () {
            var e = Array.prototype.slice.call(arguments);
            (e.unshift(t), n.push(e), n);
          };
        }));
    }
    for (var o = 0; o < n.m.length; o++) {
      var c = n.m[o];
      n[c] = n.f(c);
    }
    ((n.load = function (t, e) {
      var a = document.createElement("script");
      ((a.type = "text/javascript"),
        (a.async = !0),
        (a.src = "https://dev.paystar.io/app/embedded.loader.js"));
      var r = document.getElementsByTagName("script")[0];
      (r.parentNode.insertBefore(a, r), (n._loadOptions = e));
    }),
      (n.SNIPPET_VERSION = "0.1.0"));
  })();

  Paystar.initialize();
  Paystar.load();
</script>

This snippet creates a lightweight command queue that buffers method calls while the full SDK loads asynchronously. All examples use the development environment. For production, replace dev.paystar.io with secure.paystar.io — see Going to Production.

Methods​

Paystar.initialize()​

Initializes the SDK. Called automatically by the SDK snippet — you do not need to call this separately.

Paystar.completePayment(sessionUrl, options)​

Opens a payment form for one-time payments.

Parameters:

ParameterTypeRequiredDescription
sessionUrlstringYesThe session URL returned by your backend API call
optionsobjectNoConfiguration options (see below)

Options:

OptionTypeDefaultDescription
onCompletefunction—Called when payment completes. Receives the payment result object
onEventfunction—Called for all events. Receives { event, data }
closeOnCompletebooleanfalseAuto-close modal after payment, before rendering confirmation
containerstring | Element—CSS selector or DOM element to render into instead of the modal
closeButtonbooleantrueShow the close button on the modal
debugbooleanfalseEnable debug logging to the browser console

Examples:

// Basic usage
Paystar.completePayment(sessionUrl, {
  onComplete: function (result) {
    console.log("Payment completed!", result);
  },
});

// With custom container (inline instead of modal)
Paystar.completePayment(sessionUrl, {
  container: "#payment-div",
});

// With event handling
Paystar.completePayment(sessionUrl, {
  onEvent: function ({ event, data }) {
    console.log("Event:", event, "Data:", data);
  },
});

Paystar.startFlow(sessionUrl, options)​

Opens management flows: AutoPay, Wallet, Paperless Billing, and Notifications.

Parameters:

ParameterTypeRequiredDescription
sessionUrlstringYesThe session URL returned by your backend API call
optionsobjectNoConfiguration options (see below)

Options:

OptionTypeDefaultDescription
onEventfunction—Called for all events. Receives { event, data }
containerstring | Element—CSS selector or DOM element to render into instead of the modal
closeButtonbooleantrueShow the close button on the modal
debugbooleanfalseEnable debug logging to the browser console

Examples:

Paystar.startFlow(autopaySessionUrl, {
  onEvent: function ({ event, data }) {
    if (event === "AUTOPAY-SESSION.ENROLLED") {
      console.log("AutoPay successfully enabled!");
    }
    if (event === "AUTOPAY-SESSION.UNENROLLED") {
      console.log("AutoPay has been disabled.");
    }
  },
});

Paystar.subscribe(event, handler)​

Subscribes to a specific event. Returns an unsubscribe function.

Parameters:

ParameterTypeRequiredDescription
eventstringYesEvent name to subscribe to
handlerfunctionYesFunction called when the event fires

Returns: A function that unsubscribes the handler when called.

const unsubscribe = Paystar.subscribe(
  "PAYMENT-SESSION.PROCESSED",
  function (data) {
    console.log("Payment processed:", data);
  },
);

// Later: unsubscribe
unsubscribe();

See the Events page for all available event names.

Paystar.destroy()​

Cleans up the SDK instance and removes all event listeners. Call this when you're done with the SDK (e.g., on page teardown in a SPA).

Paystar.destroy();

Custom Containers​

Instead of the default modal, embed forms directly in your page by providing a container option:

<div id="payment-container" style="height: 600px; width: 100%;"></div>

<script>
  // Using a CSS selector
  Paystar.completePayment(sessionUrl, {
    container: "#payment-container",
  });

  // Or pass a DOM element directly
  const el = document.getElementById("payment-container");
  Paystar.completePayment(sessionUrl, {
    container: el,
  });
</script>
Container Size Requirements
  • Minimum height: 500px
  • Minimum width: 320px
  • Recommended: 600px height, 100% width

Content Security Policy​

If your site uses CSP headers, add these directives:

script-src 'self' https://dev.paystar.io;
frame-src 'self' https://dev.paystar.io;
connect-src 'self' https://dev-gateway.paystar.io;

TypeScript​

TypeScript definitions are not yet published. For now, you can declare the global:

declare global {
  interface Window {
    Paystar: {
      initialize: () => void;
      completePayment: (url: string, options?: any) => void;
      startFlow: (url: string, options?: any) => void;
      subscribe: (event: string, handler: Function) => () => void;
      destroy: () => void;
    };
  }
}

FAQ​

Can I have multiple forms open at once? No, only one Paystar form can be open at a time.

How do I update a session after it's created? Sessions are immutable. Create a new session with the updated data.

What happens if the session expires? The user sees an error message. Create a new session — payment sessions expire after 30 minutes, management sessions after 60 minutes.

Can I customize the form fields? Form fields are configured at the business unit level. Contact your Account Manager for customization.