Skip to main content

Embedded Services Overview

Introduction​

Paystar's Embedded services consist primary of the following components:

Paystar API Gateway: The API endpoints that generate the secure embedded URLs for the desired action.

Paystar JS SDK: JavaScript library that is used to embed the Paystar UI into the client's website. It is responsible for displaying the Paystar UI and handling communication between the client's website and the Paystar UI.

Client Response Handlers aka responding to Paystar events. Paystar offers multiple mechanisms for the client to respond to events including webhooks, Javascript callbacks, and query APIs. Additionally, Paystar offers a file transfer mechanism for clients to receive payment data.

General Component Flow​

Generate a Secure URL: Initiate an request to the Paystar API Gateway to generate a secure embedded URL for the desired action.

Pass the URL to the Paystar JS SDK: The URL is returned to the client, which subsequently forwards it to the Paystar JS SDK.

Handle the Response: The client receives responses in two ways:

  • via pre-configured webhooks
  • via the Paystar JS SDK callbacks
  • via file transfer (typically daily)
  • via query APIs

Embedded Session Types​

Data Sync​

For developers integrating Paystar's Embedded Services, understanding the consistent role of "Client Account" and "Client User" across different session types is essential:

"Client Account": Represents the customer's account as recognized within the client's system. Its synchronization with Paystar’s system is a uniform process across various session types. Any "Client Account" information provided through the API request is systematically synchronized with Paystar's "Account Cache". This ensures that the account details are updated and available in Paystar’s system for further processing.

"Client User": The authenticated user on the client’s platform, important for personalizing and securing the service.

Initiate Payment Session​

  • Client Account: Optional. If provided, the account details are synchronized with Paystar's system.
  • Client User: Optional. Enhances session by enabling access to saved payment methods.
  • Workflow: Initiates a payment session for the client's customer.

Autopay Enrollment Session​

  • Client Account: Required.
  • Client User: Required.
  • Workflow: Manages settings for automated payments and synchronizes provided account details with Paystar's system.

Paperless Enrollment Session​

  • Client Account: Required.
  • Client User: Required.
  • Workflow: Manages settings for opting into electronic billing services, with account details synced with Paystar.

Manage Wallet Session​

  • Client Account: N/A.
  • Client User: Required.
  • Workflow: Manages payment sources available for the clients authenticated user.

Responding to Paystar Events​

Webhooks​

Most events that occur in the Paystar UI can trigger a webhook to be sent to the client's server. The type of event determines the available webhook payloads. The client's server should respond to the webhook with a 200 status code. If the client's server does not respond with a 200 status code, Paystar will retry the webhook up to 5 times.

Configuration Note: Payloads for Payments or Account based actions can typically include the payment or account meta configured for the specific client.

See #Webhooks for more details.

Javascript Callbacks​

Paystar JS SDK callbacks are used when the client wants their UI to respond to Paystar events without having to wait for a webhook. Any events that have corresponding Query APIs should have the key information to make a query request in the event that the client system doesn't want to wait for a webhook.

Query APIs​

Paystar provides query APIs for the following actions:

  • Payment Status
    • By Client Reference
    • By Session Identifier

Planned Query APIs:

  • Account Details by Client Identifier (Account Number / Subaccount Number OR "UniqueAccountIdentifier")
  • Get Payments (Filtered)
    • Timespan
    • Status
    • Payment Channel
    • Payment Method
    • "Not Exported" Flag

See #Query-APIs for more details.

File Transfer​

While Paystar offers multiple "real-time" response mechanisms, file transfer and query APIs are recommended as a backup in case the real-time response mechanisms fail. This allows the client to detect when real-time response mechanisms fail and to respond accordingly. Paystar supports file transfer via SFTP and FTPS. See #File-Transfer for more details.