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

Environment	API Base URL	SDK Loader URL
Staging	https://stage-gateway.paystar.io	https://stage.paystar.io/app/embedded.loader.js
Production	https://gateway.paystar.io	https://secure.paystar.io/app/embedded.loader.js

All examples below use the staging 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.

Optionally pass a PaymentMethods array ("Credit Card", "ACH") to specify which payment methods are available in the session. Only the values you list are shown — any method enabled for your business unit but not in the list is removed from this session. This cannot enable a method that is not already configured for the business unit. Omit the field to use whichever payment methods are enabled for the business unit. See PaymentMethods for details.

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "PaymentSessionIdentifier": "abc123-def456-ghi789",
    "PaymentLogInLink": "https://stage.paystar.io/app/embedded/acme-utilities/session/abc123...",
    "Status": "RequiresPaymentSource"
  }
}

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

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "SessionLink": "https://stage.paystar.io/embedded/acme-utilities/flow/account/manage-autopay/...",
    "SessionStatus": "Created",
    "ValidUntil": "2025-03-01T12:00:00Z"
  }
}

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.

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "SessionLink": "https://stage.paystar.io/embedded/acme-utilities/flow/customer/manage-wallet/...",
    "SessionStatus": "Created",
    "ValidUntil": "2025-03-01T12:00:00Z"
  }
}

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

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "SessionLink": "https://stage.paystar.io/embedded/acme-utilities/flow/account/manage-paperless/...",
    "SessionStatus": "Created",
    "ValidUntil": "2025-03-01T12:00:00Z"
  }
}

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

---

Create One Time Scheduled Payment Session

POST /integrations/embedded/initiate-schedule-payment-session

Creates a session that lets a user schedule a one-time future payment. 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).

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "SessionLink": "https://stage.paystar.io/embedded/acme-utilities/flow/account/schedule-payment/...",
    "SessionStatus": "Created",
    "ValidUntil": "2025-03-01T12:00:00Z"
  }
}

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

---

Create Manage Scheduled Payments Session

POST /integrations/embedded/initiate-manage-schedule-payments

Creates a session that lets a user view and cancel their scheduled payments. 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).

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "SessionLink": "https://stage.paystar.io/embedded/acme-utilities/flow/account/manage-schedule-payments/...",
    "SessionStatus": "Created",
    "ValidUntil": "2025-03-01T12:00:00Z"
  }
}

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.

Request

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

Response

{
  "hasErrors": false,
  "errors": [],
  "data": {
    "SessionLink": "https://stage.paystar.io/embedded/acme-utilities/flow/customer/manage-notifications/...",
    "SessionStatus": "Created",
    "ValidUntil": "2025-03-01T12:00:00Z"
  }
}

Required fields: BusinessUnitSlug, ClientUser.EmailAddress

Session Expiration

Session Type	Expiration
Payment sessions	30 minutes
Management sessions (AutoPay, Wallet, Paperless, Notifications, One Time Scheduled Payment, Manage Scheduled Payments)	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