Skip to main content

JS SDK Overview

JS SDK​

JS Initialization​

After receiving your API keys, you need to initialize the Paystar JS SDK on your website.

<script>
  !(function () {
    var n = (window.Paystar = window.Paystar || []);
    if (!n.x) {
      (n.x = !0),
        (n.m = [
          "initialize",
          "collectPaymentSource",
          "completePayment",
          "subscribe",
        ]),
        (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://secure.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("YOUR_PUBLIC_CLIENT_IDENTIFIER");
  Paystar.load();
</script>

In the Paystar.initialize method, replace YOUR_PUBLIC_CLIENT_IDENTIFIER with the API key you received during account setup. This initialization script will load the Paystar SDK onto your webpage, enabling it to interact with Paystar's services.

After successfully setting up your account and initializing the SDK, you can use Paystar's services to initiate payments, manage wallets (customer driven), manage paperless billing settings (customer driven), and enroll in autopay (customer driven).

JS Methods​

Complete Payment

Used to open a Payment Session.

Paystar.completePayment(sessionUrl, options)

The sessionUrl is the URL returned from the Paystar API Gateway when initiating the session. options is an object with the following properties:

// optional, defaults to `true`, when `false` omits rendering the session's close button
closeButton: boolean | undefined

// optional, renders the session into the given container (selector or Element) instead of the popup
container: string | Element | undefined;

// optional, closes the session automatically when processed instead of showing the receipt
closedOnProcessed: boolean | undefined;

// optional, opts into additional console logs
debug: boolean

// optional, callback fired for the PAYMENT-SESSION.PROCESSED event
onComplete: (data: PaymentIntent) => void | undefined;

// optional, callback fired for all events
onEvent: ({ event: string, data: unknown }) => void | undefined;

Start Flow

Used to open all other embedded session types (Autopay, Paperless Billing, Wallet).

Paystar.startFlow(sessionUrl, options)

The sessionUrl is the URL returned from the Paystar API Gateway when initiating the session. options is an object with the following properties:

// optional, renders the session into the given container (selector or Element) instead of the popup
container: string | Element | undefined;

// optional, defaults to `true`, when `false` omits rendering the session's close button
closeButton: boolean | undefined

// optional, opts into additional console logs
debug: boolean

// optional, callback fired for all events
onEvent: ({ event: string, data: unknown }) => void | undefined;

Events​

The SDK provides a subscribe function which allows you to subscribe to specific events.

Paystar.subscribe(EVENT_NAME, (payload: unknown) => {
  ...
})

Additionally, both completePayment and startFlow provide an onEvent option which will execute the callback for all events.

Paystar.startFlow(sessionUrl, {
  onEvent: ({ event, data }) => { ... }
})

Events List​

The available events and their payloads:

  • COMPONENT.DISMISS : undefined
  • FRAME.LOADED : undefined
  • USER.AUTHENTICATED : { user: User }
  • USER.LOADED : { user: User }
  • Autopay Session
    • AUTOPAY-SESSION.ENROLLED:
      • { enrolled: boolean, processingLeadTimeInDays: number, maximumBalanceAllowed: number, paymentSourceId: number }
    • AUTOPAY-SESSION.UNENROLLED: undefined
    • AUTOPAY-SESSION.SCHEDULED_PAYMENT_CANCELED: undefined
  • Paperless Session
    • PAPERLESS-SESSION.ENROLLED: undefined
    • PAPERLESS-SESSION.UNENROLLED: undefined
    • PAPERLESS-SESSION.SCHEDULED_PAYMENT_CANCELED: undefined
  • Payment Session
    • PAYMENT-SESSION.LOADED : PaymentIntent
    • PAYMENT-SESSION.UPDATED : PaymentIntent
    • PAYMENT-SESSION.PROCESSED : PaymentIntent
  • Wallet Session
    • PAYMENT-SOURCE.ADDED: undefined
    • PAYMENT-SOURCE.REMOVED: undefined

A PaymentIntent is typed as:

type PaymentIntent {
  businessUnitId: number;
  sessionIdentifier: string;
  channel: 'QuickPay' | 'POS';
  status: string;
  clientReference: string | null;
  successUrl: string | null | undefined;
  returnUrl: string | null | undefined;
  scope: "Embedded";
  id: number;
  organizationId: number;
  lineItems: LineItem[];
  paymentSource: PaymentSource;
  accounts: AccountSummaryDto[];
  isMultiAccount: boolean;
  paymentFields: Record<string, unknown>;
  paymentFieldsJson: string;
  subtotal: number;
  serviceFeeCalculation: ServiceFeeCalculationDto | null;
}

API Overview​

View the API Spec here.