Skip to main content

API Reference

Interactive API Spec

For an interactive view of the API with try-it-out functionality, see the OpenAPI Spec.

All API requests must be made from your backend server. Never call these endpoints from the browser.

Base URLs​

EnvironmentAPI Base URLSDK Loader URL
Developmenthttps://dev-gateway.paystar.iohttps://dev.paystar.io/app/embedded.loader.js
Productionhttps://secure.paystar.iohttps://secure.paystar.io/app/embedded.loader.js

All examples below use the development URLs. See Going to Production for switching to production.

Authentication​

Include your API key in the X-Paystar-Api-Key header on every request:

X-Paystar-Api-Key: YOUR_SECRET_API_KEY

Contact your Paystar Account Manager to receive your API key. Keep it secret — never expose it in client-side code.

Endpoints​

Create Payment Session​

POST /integrations/embedded/initiate

Creates a session for one-time payments. Supports accountless, single-account, and multi-account modes. See Payment Sessions for detailed configuration.

Accounts in Charges[].ClientAccount are automatically synced to Paystar. Future requests with the same account update the record (except Note and custom fields). Any ClientUser provided is automatically synced — FirstName/LastName are immutable after the first request.

{
  "BusinessUnitSlug": "acme-utilities",
  "Channel": "QuickPay",
  "ClientUser": {
    "EmailAddress": "[email protected]",
    "FirstName": "John",
    "LastName": "Doe"
  },
  "Charges": [
    {
      "Amount": 15000,
      "Description": "January Water Bill",
      "ClientAccount": {
        "AccountNumber": "ACC-12345",
        "Name": "John Doe",
        "Balance": 15000
      }
    }
  ],
  "SuccessUrl": "https://yoursite.com/payment-success",
  "ReturnUrl": "https://yoursite.com/payment-cancelled"
}

Required fields: BusinessUnitSlug, Channel, Charges (with at least one charge containing Amount)

Create AutoPay Session​

POST /integrations/embedded/initiate-manage-autopay

Creates a session for AutoPay enrollment or management. Set SyncAccount: true to sync the provided account to Paystar — this must be true when introducing a new account. ClientUser is always automatically synced (FirstName/LastName are immutable).

{
  "BusinessUnitSlug": "acme-utilities",
  "SyncAccount": true,
  "ClientAccount": {
    "AccountNumber": "ACC-12345",
    "Name": "John Doe"
  },
  "ClientUser": {
    "EmailAddress": "[email protected]",
    "FirstName": "John",
    "LastName": "Doe"
  }
}

Required fields: BusinessUnitSlug, ClientAccount.AccountNumber, ClientUser.EmailAddress

Create Wallet Session​

POST /integrations/embedded/initiate-manage-wallet

Creates a session for managing payment methods (add, view, delete). Wallet sessions are per-customer — no ClientAccount is needed. ClientUser is always automatically synced.

{
  "BusinessUnitSlug": "acme-utilities",
  "ClientUser": {
    "EmailAddress": "[email protected]",
    "FirstName": "John",
    "LastName": "Doe"
  }
}

Required fields: BusinessUnitSlug, ClientUser.EmailAddress

Create Paperless Session​

POST /integrations/embedded/initiate-manage-paperless

Creates a session for paperless billing enrollment. Set SyncAccount: true to sync the provided account — this must be true when introducing a new account. ClientUser is always automatically synced (FirstName/LastName are immutable).

{
  "BusinessUnitSlug": "acme-utilities",
  "SyncAccount": true,
  "ClientAccount": {
    "AccountNumber": "ACC-12345",
    "Name": "John Doe"
  },
  "ClientUser": {
    "EmailAddress": "[email protected]",
    "FirstName": "John",
    "LastName": "Doe"
  }
}

Required fields: BusinessUnitSlug, ClientAccount.AccountNumber, ClientUser.EmailAddress

Create Notification Session​

POST /integrations/embedded/initiate-manage-notifications

Creates a session for managing email and SMS notification preferences. ClientUser is always automatically synced.

{
  "BusinessUnitSlug": "acme-utilities",
  "ClientUser": {
    "EmailAddress": "[email protected]",
    "FirstName": "John",
    "LastName": "Doe"
  }
}

Required fields: BusinessUnitSlug, ClientUser.EmailAddress

Session Expiration​

Session TypeExpiration
Payment sessions30 minutes
Management sessions (AutoPay, Wallet, Paperless, Notifications)60 minutes

Expired sessions display an error when opened. Create a new session if the previous one has expired.

Webhooks​

Paystar can send real-time webhook notifications to your server when events occur (payments processed, AutoPay enrolled, etc.). See the Webhooks page for full details on configuration, payloads, and signature verification.

Best Practices​

  1. Store session IDs returned from the API for tracking and support
  2. Handle errors gracefully — show user-friendly messages when API calls fail
  3. Log API responses for debugging, but never log your API key
  4. Implement retry logic with exponential backoff for transient network failures
  5. Check hasErrors in every response before accessing data