Paystar Embedded

Paystar Embedded is a secure iframe solution that adds payment processing and account management to your website. Your users can complete payments, enroll in autopay, manage their payment methods, and more — all without leaving your site.

How It Works

Every Embedded integration has two parts:

1. Backend (server-to-server) — Your server calls the Paystar API with the relevant payload (charges, account info, etc.) and receives a session URL in return.
2. Frontend (JavaScript SDK) — Your page includes the Paystar SDK snippet, which opens that session URL in a secure modal (or embedded container) for the user to interact with.

Your backend creates sessions; your frontend opens them. The SDK never handles API keys or payment data directly — all sensitive exchange happens server-to-server.

Security Model

Your API key is only used on your backend. The frontend SDK receives a short-lived session URL — it never touches credentials or raw payment data.

Data Sync

When you create sessions, Paystar creates and maintains its own records based on the data you provide:

• Account sync — Paystar creates an account record identified by AccountNumber (and SubAccountNumber if provided). On future requests, Paystar updates that record to reflect whatever you send — add, change, or remove field values and the record updates accordingly. (Note and custom account fields do not sync.) Payment sessions sync accounts automatically; AutoPay and Paperless sessions sync when SyncAccount: true is set. Wallet and Notification sessions don't use accounts.
• Customer sync — Paystar creates a customer record identified by EmailAddress and associates it with any accounts in the session. FirstName and LastName are optional but immutable — they are saved on the first request that introduces this customer and are not updated by future requests. Customer sync is always automatic when ClientUser is provided, and enables features like saved payment methods (wallet).

Available Flows

Flow	Description	API Endpoint	SDK Method
Payment	Accept one-time payments	POST /integrations/embedded/initiate	completePayment()
AutoPay	Enroll in or manage automatic payments	POST /integrations/embedded/initiate-manage-autopay	startFlow()
Wallet	Add, view, and delete payment methods	POST /integrations/embedded/initiate-manage-wallet	startFlow()
Paperless	Opt into paperless billing	POST /integrations/embedded/initiate-manage-paperless	startFlow()
Notifications	Manage email/SMS notification preferences	POST /integrations/embedded/initiate-manage-notifications	startFlow()

Quick Start

Step 1: Get Your API Credentials

Contact your Paystar Account Manager to receive:

• Your API Key
• Your Business Unit Slug

API Key Security

Your API key is a secret. Never expose it in client-side code, commit it to source control, or share it publicly. All API calls must be made from your backend server.

Step 2: Add the Paystar SDK

Add this snippet to your HTML:

<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 3: Create a Payment Session (Backend)

Make an API call from your server to exchange payment details for a session URL:

curl -X POST https://dev-gateway.paystar.io/integrations/embedded/initiate \
  -H "X-Paystar-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "BusinessUnitSlug": "your-slug",
    "Channel": "QuickPay",
    "Charges": [
      {
        "Description": "Invoice #123",
        "Amount": 15000
      }
    ]
  }'

You'll receive a session URL in the response:

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "PaymentSessionIdentifier": "abc123...",
    "PaymentLogInLink": "https://dev.paystar.io/app/embedded/your-slug/session/abc123...",
    "Status": "RequiresPaymentSource"
  }
}

Step 4: Open the Payment Form (Frontend)

Pass the session URL to the SDK to open it in a modal:

<button onclick="openPayment()">Pay Now</button>

<script>
  function openPayment() {
    Paystar.completePayment("SESSION_URL_FROM_API");
  }
</script>

That's it! Your users can now make payments through your site. See the Integration Guide for the full setup walkthrough.

Environments

All examples in this documentation use the development URLs. Build and test your integration here first.

	API Base URL	SDK Loader URL
Development	https://dev-gateway.paystar.io	https://dev.paystar.io/app/embedded.loader.js
Production	https://secure.paystar.io	https://secure.paystar.io/app/embedded.loader.js

Don't Mix Environments

The SDK must be loaded from the same environment where sessions were created. A session created against dev-gateway.paystar.io will not work with the production SDK loader, and vice versa.

Going to Production

When you're ready to go live, swap the two URLs in your code:

1. API key — Swap your development API key for your production API key (contact your Account Manager if you haven't received one)
2. SDK loader — In your HTML snippet, change the src from https://dev.paystar.io/app/embedded.loader.js to https://secure.paystar.io/app/embedded.loader.js
3. API base URL — In your backend API calls, change https://dev-gateway.paystar.io to https://secure.paystar.io

No other code changes are needed.

Test Credentials

Use these credentials in the development environment:

Test Cards

Card Number	Brand	Result
4788 2500 0012 1443	Visa	Success
5454 5454 5454 5454	Mastercard	Success
4387 7511 1111 1053	Visa	Decline

Use any future expiration date and any 3-digit CVV.

Test ACH

Field	Value
Routing Number	021000021
Account Number	123456789