Skip to main content

Integration Guide

This guide walks you through integrating Paystar Embedded into your website step by step.

Prerequisites​

Before you begin, you'll need:

  1. API Credentials from Paystar — an API Key and a Business Unit Slug (contact your Account Manager)
  2. A backend server to store your API key securely and make API calls to create sessions
  3. HTTPS in production (localhost works for development)

Step 1: Install the SDK​

Add the Paystar SDK snippet to your HTML. This creates a lightweight command queue that buffers method calls while the full SDK loads asynchronously.

<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>

Step 2: Create Sessions (Backend)​

All sessions must be created from your backend server. Each session type has its own endpoint and returns a session URL.

Error Handling

If a session creation call fails (network error, validation error, non-success response, etc.), Paystar Embedded will not have a session URL to display — your application is responsible for catching the error and showing an appropriate message to the user.

Payment Session​

Create a session for one-time payments. Accounts in Charges[].ClientAccount are automatically synced to Paystar — no flag needed. Future requests with the same account update the record.

const axios = require("axios");

async function createPaymentSession(amount, description) {
  const response = await axios.post(
    "https://dev-gateway.paystar.io/integrations/embedded/initiate",
    {
      BusinessUnitSlug: "your-business-unit-slug",
      Channel: "QuickPay",
      Charges: [
        {
          Description: description,
          Amount: amount, // Amount in cents: 15000 = $150.00
        },
      ],
      // Optional: Include customer info to enable wallet features
      // and attribute the payment to a customer
      ClientUser: {
        EmailAddress: "[email protected]",
        FirstName: "John",
        LastName: "Doe",
      },
    },
    {
      headers: {
        "Content-Type": "application/json",
        "X-Paystar-Api-Key": process.env.PAYSTAR_API_KEY,
      },
    },
  );

  return response.data.data.PaymentLogInLink;
}

AutoPay Session​

Create a session for autopay enrollment. Set SyncAccount: true to sync the account to Paystar (required when introducing a new account). ClientUser is always automatically synced.

async function createAutopaySession(accountNumber, customerEmail) {
  const response = await axios.post(
    "https://dev-gateway.paystar.io/integrations/embedded/initiate-manage-autopay",
    {
      BusinessUnitSlug: "your-business-unit-slug",
      SyncAccount: true,
      ClientAccount: {
        AccountNumber: accountNumber,
        Name: "John Doe",
      },
      ClientUser: {
        EmailAddress: customerEmail,
        FirstName: "John",
        LastName: "Doe",
      },
    },
    {
      headers: {
        "Content-Type": "application/json",
        "X-Paystar-Api-Key": process.env.PAYSTAR_API_KEY,
      },
    },
  );

  return response.data.data.SessionLink;
}

Wallet Session​

Create a session for payment method management. Wallet sessions are per-customer (no ClientAccount). ClientUser is always automatically synced.

async function createWalletSession(customerEmail) {
  const response = await axios.post(
    "https://dev-gateway.paystar.io/integrations/embedded/initiate-manage-wallet",
    {
      BusinessUnitSlug: "your-business-unit-slug",
      ClientUser: {
        EmailAddress: customerEmail,
        FirstName: "John",
        LastName: "Doe",
      },
    },
    {
      headers: {
        "Content-Type": "application/json",
        "X-Paystar-Api-Key": process.env.PAYSTAR_API_KEY,
      },
    },
  );

  return response.data.data.SessionLink;
}

Paperless Session​

Create a session for paperless billing enrollment. Set SyncAccount: true to sync the account (required when introducing a new account). ClientUser is always automatically synced.

async function createPaperlessSession(accountNumber, customerEmail) {
  const response = await axios.post(
    "https://dev-gateway.paystar.io/integrations/embedded/initiate-manage-paperless",
    {
      BusinessUnitSlug: "your-business-unit-slug",
      SyncAccount: true,
      ClientAccount: {
        AccountNumber: accountNumber,
      },
      ClientUser: {
        EmailAddress: customerEmail,
      },
    },
    {
      headers: {
        "Content-Type": "application/json",
        "X-Paystar-Api-Key": process.env.PAYSTAR_API_KEY,
      },
    },
  );

  return response.data.data.SessionLink;
}

Notification Session​

Create a session for managing email/SMS notification preferences. ClientUser is always automatically synced.

async function createNotificationSession(customerEmail) {
  const response = await axios.post(
    "https://dev-gateway.paystar.io/integrations/embedded/initiate-manage-notifications",
    {
      BusinessUnitSlug: "your-business-unit-slug",
      ClientUser: {
        EmailAddress: customerEmail,
        FirstName: "John",
        LastName: "Doe",
      },
    },
    {
      headers: {
        "Content-Type": "application/json",
        "X-Paystar-Api-Key": process.env.PAYSTAR_API_KEY,
      },
    },
  );

  return response.data.data.SessionLink;
}

Step 3: Open Sessions (Frontend)​

Once you have a session URL from your backend, use the SDK to open it.

Payment Sessions​

Use completePayment() to open payment sessions:

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

All Other Flows​

Use startFlow() for AutoPay, Wallet, Paperless, and Notification sessions:

Paystar.startFlow(sessionUrl, {
  onEvent: function ({ event, data }) {
    console.log("Event:", event, "Data:", data);
  },
});

See the SDK Reference for the full options available on each method.

Step 4: Handle Events​

Subscribe to events to track user actions:

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

// Later: unsubscribe if needed
unsubscribe();

See the Events page for all available events and their payloads.

Step 5: Customize (Optional)​

Custom Container​

Instead of the default modal, embed the form directly in your page:

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

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

See the SDK Reference for container requirements.

Security Best Practices​

warning

Follow these rules to keep your integration secure:

  1. Never expose your API key in client-side code, HTML, or JavaScript
  2. Always create sessions from your backend — the frontend only receives session URLs
  3. Validate webhook signatures if using webhooks
  4. Use HTTPS in production — localhost is acceptable for development only