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:

closedOnProcessed: boolean | undefined;
onComplete: (data: PaymentIntent) => void | undefined;
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:

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 }
• Payment Session
  • PAYMENT-SESSION.LOADED : PaymentIntent
  • PAYMENT-SESSION.UPDATED : PaymentIntent
  • PAYMENT-SESSION.PROCESSED : PaymentIntent

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.