UI Integration Overview
Paysense supports embedding the Payroll UI inside an <iframe> in your own application so end users can manage payroll without leaving your product. Authentication is handled by short-lived, server-issued codes - there is no login screen or redirect for the embedded user.
This page is a public overview. Full implementation details, code samples, and required credentials are released to integration partners under a partnership agreement.
What you get
- A pre-built payroll UI that drops into any iframe in your application.
- Transparent single-sign-on - the embedded user is authenticated automatically using a code your server issues.
- Configurable UI chrome (side navigation and top app bar can be shown or hidden per render).
- Programmatic navigation from the parent frame.
- Per-tenant isolation - each tenant has its own credentials.
How it works (at a high level)
- Your server issues a short-lived, encrypted authentication code for the embedding user using a shared secret provisioned by Paysense.
- Your application embeds a Paysense URL in an iframe and appends the code as a query parameter.
- Paysense validates the code, establishes a session inside the iframe, and renders the payroll UI for that user.
The user's credentials are never exposed to your application. Codes are generated per-render and expire quickly.
Browser and hosting requirements
| Requirement | Notes |
|---|---|
| HTTPS | The embedding application must be served over HTTPS in production. |
CSP frame-src | If your application sends a Content-Security-Policy header, it must permit framing your assigned Paysense tenant origin. |
iframe sandbox | Standard iframe sandbox attributes are supported; required tokens are documented in the partner pack. |
sessionStorage access | Browsers that block third-party storage may require additional handling. Safari and Firefox private-browsing modes should be tested before going live. |
Security model
- Server-side code generation only. The shared secret must never be exposed to client-side code.
- Short-lived codes. Codes are time-bounded; integration partners receive specific guidance on validity windows.
- Origin allowlist. Paysense enforces an origin allowlist for embedded contexts. Your origin must be registered before framing succeeds.
- Authenticated cross-frame messaging. Programmatic navigation messages from the parent frame are validated against the registered origin allowlist; messages from other origins are silently dropped.
- Authenticated encryption. Tampered or replayed-out-of-window codes are rejected.
Prerequisites
Before integrating you'll need the following from Paysense:
| Item | Description |
|---|---|
| Tenant subdomain | The Paysense URL your users will be served from. |
| Partner credentials | A secret used to issue authentication codes, delivered through a secure channel. |
| Origin registration | Your application origin(s) added to the embed allowlist for your tenant. |
| Partner integration pack | The implementation-detail document, including reference code, sandbox token list, error handling, and operational guidance. |
Getting started
Embedding the Paysense Payroll UI requires a partnership agreement. To begin:
- Contact your Paysense partner manager (or reach out via the website) to discuss your use case.
- Once your tenant is provisioned, you'll receive the partner integration pack with the implementation details, your tenant's credentials, and origin registration.
- Implement the embed flow against a staging tenant. Paysense provides a sandbox environment for end-to-end verification before production.
The full technical specification - including encryption algorithm choice, payload schema, endpoint paths, sandbox token rationale, available routes, error responses, and code samples in C#, TypeScript, Python, and Java - is delivered to partners after a partnership agreement is in place. This page is intentionally light on those specifics.