Skip to main content
API docs by Redocly

Paystar Embedded Session API (1.0.0)

Download OpenAPI specification:Download

The Paystar Embedded API lets you create secure session URLs for payment processing and account management flows. Your backend calls these endpoints to generate sessions, then your frontend opens them using the Paystar JavaScript SDK.

Authentication

All requests require an X-Paystar-Api-Key header. Contact your Paystar Account Manager to receive your API key.

Session Types

  • Payment Sessions — Accept one-time payments (accountless, single-account, or multi-account)
  • AutoPay Sessions — Enroll customers in automatic payments
  • Wallet Sessions — Manage saved payment methods
  • Paperless Sessions — Enroll in paperless billing
  • Notification Sessions — Manage email/SMS notification preferences

Data Sync

  • Account sync: Paystar creates an account record identified by AccountNumber / SubAccountNumber. Future requests update the record to reflect what you send (except Note and custom account fields). Payment sessions sync automatically; AutoPay and Paperless sessions sync when SyncAccount: true (must be true when introducing a new account). Wallet and Notification sessions don't use accounts.
  • Customer sync: Paystar creates a customer record identified by EmailAddress and associates it with accounts in the session. FirstName and LastName are immutable — set on the first request, not updated by future requests. This is always automatic when ClientUser is provided.

Create Payment Session

Creates a session for one-time payments. Supports QuickPay (customer self-service) and POS (agent-initiated) channels. 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.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
BusinessUnitSlug
required
string

Your business unit identifier (provided by Paystar)

PaymentDescriptor
string

Custom descriptor that appears on the payment

Channel
required
string
Default: "QuickPay"
Enum: "QuickPay" "POS"

Payment channel — QuickPay for customer self-service, POS for agent-initiated payments

ClientReference
string

Your system's reference ID for tracking this payment. Must be unique if provided.

required
Array of objects (EmbeddedCharges)

Line items for the payment (max 25). Each charge can optionally include a ClientAccount.

object

Key-value pairs for pre-configured custom fields. Must be configured with your Account Manager before use. If a configured field is omitted from the payload, the user is prompted to provide it. If included, the value is used directly.

object

Arbitrary key-value metadata recorded onto the session. No prior configuration needed. Returned to you via webhooks, Query API, and SDK events.

object (ClientUserDto)
PosUser
string

Agent's Paystar email address for POS channel payments. Cannot be set with ClientUser. The agent's account must have POS permission enabled.

ReturnUrl
string

URL for the 'Go back' button after payment. Must be paired with SuccessUrl — provide both or neither.

SuccessUrl
string

URL for the 'I'm done' button after payment. Must be paired with ReturnUrl — provide both or neither.

Responses

Request samples

Content type
application/json
Example
{
  • "BusinessUnitSlug": "acme-utilities",
  • "Channel": "QuickPay",
  • "Charges": [
    ]
}

Response samples

Content type
application/json
{}

Create AutoPay Session

Creates a session for AutoPay enrollment or management. When SyncAccount is true, the provided ClientAccount data is synchronized with Paystar. Must be true when introducing a new account. Future requests update the account record (except Note and custom fields). ClientUser data is always automatically synced — FirstName/LastName are immutable after the first request.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
BusinessUnitSlug
required
string

Your business unit identifier (provided by Paystar)

required
object (ClientAccountDto)
required
object (ClientUserDto)
SyncAccount
boolean

When true, synchronizes the provided ClientAccount data with Paystar. Must be true when introducing a new account. Future requests update the record (except Note and custom fields).

Responses

Request samples

Content type
application/json
{
  • "BusinessUnitSlug": "acme-utilities",
  • "SyncAccount": true,
  • "ClientAccount": {
    },
  • "ClientUser": {}
}

Response samples

Content type
application/json
{}

Create Paperless Session

Creates a session for paperless billing enrollment or management. When SyncAccount is true, the provided ClientAccount data is synchronized with Paystar. Must be true when introducing a new account. Future requests update the account record (except Note and custom fields). ClientUser data is always automatically synced — FirstName/LastName are immutable after the first request.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
BusinessUnitSlug
required
string

Your business unit identifier (provided by Paystar)

required
object (ClientAccountDto)
required
object (ClientUserDto)
SyncAccount
boolean

When true, synchronizes the provided ClientAccount data with Paystar. Must be true when introducing a new account. Future requests update the record (except Note and custom fields).

Responses

Request samples

Content type
application/json
{
  • "BusinessUnitSlug": "acme-utilities",
  • "SyncAccount": true,
  • "ClientAccount": {
    },
  • "ClientUser": {}
}

Response samples

Content type
application/json
{}

Create Wallet Session

Creates a session for managing saved payment methods (add, view, delete). Wallet sessions are per-customer — no ClientAccount is needed. ClientUser data is always automatically synced — FirstName/LastName are immutable after the first request.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
BusinessUnitSlug
required
string

Your business unit identifier (provided by Paystar)

required
object (ClientUserDto)

Responses

Request samples

Content type
application/json
{
  • "BusinessUnitSlug": "acme-utilities",
  • "ClientUser": {}
}

Response samples

Content type
application/json
{}

Create Notification Session

Creates a session for managing email and SMS notification preferences. ClientUser data is always automatically synced — FirstName/LastName are immutable after the first request.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
BusinessUnitSlug
required
string

Your business unit identifier (provided by Paystar)

required
object (ClientUserDto)

Responses

Request samples

Content type
application/json
{
  • "BusinessUnitSlug": "acme-utilities",
  • "ClientUser": {}
}

Response samples

Content type
application/json
{}