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 the SDK snippet to your HTML <head> or before the closing </body> tag. See Step 1: Install the SDK in the Integration Guide for the full snippet and staging/production variants.

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. The element must have a defined height — the session fills 100% of it. See Custom Containers
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, One Time Scheduled Payment, Manage Scheduled Payments, 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. The element must have a defined height — the session fills 100% of it. See Custom Containers
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 Height​

The SDK renders a wrapper element with height: 100% inside your container, and the session fills that wrapper. The session has no height of its own — your container element must have a resolved CSS height for the session to expand into.

Set an explicit height on the container (as in the example above). A percentage height (e.g. height: 100%) only works if every ancestor element also has a defined height. If the container has no resolved height, the session will render collapsed or at an unexpected size.

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://stage.paystar.io;
frame-src 'self' https://stage.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.