Hosted Session
Create users, business entities, personal entities, and card requests through a secure, SAVA-hosted interface with consent capture and audit trail owned end to end by SAVA.
Overview
A hosted session is a short-lived, single-purpose URL that SAVA generates on your behalf. The end user opens it to review prefilled information, give consent, and submit the regulated request inside a SAVA-owned UI.
The hosted session exists so that the final regulated submission, including consent capture and audit trail, is owned end to end by SAVA. This isolates you from the regulated submission boundary while keeping the rest of the integration on the existing SAVA BaaS API.
A regulatory measure, not a permanent surface
The hosted session was introduced in response to the current regulatory landscape: the final regulated submission must happen inside a SAVA-owned experience. If that requirement falls away, the hosted session will be deprecated and these flows will revert to the normal API integration, creating users, business entities, personal entities, and card requests directly through their existing endpoints.
Integrate with the BaaS API only
Hosted session routes, form URLs, and status URLs are SAVA-internal. Do not call or construct them directly; the only URLs you use are the launch URLs returned when you create a session.
How it works
The partner only creates the session and opens a launch URL. Everything after launch, the form, consent capture, and the audit trail, is SAVA-owned, and the final record is created with the preallocated expected_result.id. Sessions expire after 15 minutes.
- Your system calls the SAVA BaaS API with the user, business entity, personal entity, or card request data
- SAVA preallocates the
expected_result.idand returnshosted_urlandiframe_url - Your application presents one of those URLs to the end user
- The prefilled UI is for review and submission, not editing
- SAVA captures consent inside the UI and records it in the submission audit trail (version, timestamp, source, flow context)
The hosted session sits alongside your existing SAVA BaaS API integration, it does not replace it. Everything else, KYC and KYB flows, transaction notifications, authorization flows, and account, user, entity, and card follow-up operations, continues through the existing API unchanged. Use only the hosted flows your product needs: business entity for business onboarding, personal entity for individual onboarding, and create user and request card for cardholders.
Supported flows
Subject: svc.hosted_session.{partner_id}.create
You create a hosted session for exactly one flow, and SAVA returns launch URLs you can redirect to or embed:
| Flow | Creates | expected_result.id becomes |
|---|---|---|
create_user | A user under an entity | The future user_id |
create_business_entity | A business entity | The future entity_id |
create_personal_entity | A personal entity, and its user automatically | The future entity_id (the user_id is created after submission, see Create Personal Entity Session) |
request_card | A card request | The future card_request_id |
The expected_result.id is preallocated when the session is created, but the actual resource is created only after the user completes and submits the hosted flow. When they do, SAVA BaaS creates the record with that same UUID, so you can correlate ahead of time.
Payloads are validated at mint time: a bad field fails the create call itself, before anything is shown to the end user. You will not receive a successful mint that later errors inside the hosted UI because of your data.
Create User Session
The create_user_request fields are listed below.
Request
| Field | Type | Required | Description |
|---|---|---|---|
flow_type | string | required | Must be "create_user" |
create_user_request | object | required | The user to create. See the fields below |
create_user_request fields
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | required | UUID of the entity the user belongs to |
first_name | string | required | First name |
last_name | string | required | Last name |
email | string | required | Must be a valid email |
phone_number | string | required | Phone number including country code |
gender | string | required | One of: male, female, other |
date_of_birth | string | required | ISO 8601 format |
country | string | required | ISO 3-letter country code, e.g. "ZAF" |
city | string | required | City of residence |
residency | string | required | Residency status |
id_number | string | required | National ID or passport number |
id_type | string | required | National needs no expiry; passport requires id_issue_expiry_date |
id_issue_date | string | required | ISO 8601 format |
id_issue_expiry_date | string | optional | Required for passport, not for a National ID |
title | string | required | e.g. Mr, Ms, Dr, Mx |
verified | boolean | required | Send false; verification happens through KYC |
permit_number | string | optional | Required only if id_type is not national |
address | object | required | Address: address_line_1, address_line_2, city, state, country, postcode |
Response
| Field | Type | Description |
|---|---|---|
session.id | string | Hosted session ID |
session.partner_id | string | Your partner ID |
session.flow_type | string | The flow this session was created for |
session.status | string | Always created in this response: the session exists and nothing has been submitted yet. See Session status |
session.expected_result_id | string | The preallocated result ID (same value as expected_result.id) |
session.expires_at | string | Expiry timestamp, 15 minutes after creation |
launch.hosted_url | string | Launch URL for redirect, browser tab, or mobile WebView |
launch.iframe_url | string | Launch URL for embedding in an iframe |
expected_result.type | string | The response type the flow will produce |
expected_result.id | string | For create_user: the future user_id. SAVA creates the user with this same UUID when the session is submitted |
Create Business Entity Session
The create_business_entity_request fields are listed below.
Request
| Field | Type | Required | Description |
|---|---|---|---|
flow_type | string | required | Must be "create_business_entity" |
create_business_entity_request | object | required | The business entity to create, same shape as the Entity Service create request |
create_business_entity_request fields
| Field | Type | Required | Description |
|---|---|---|---|
entity_type | string | required | Must be "business" |
name | string | required | Company name |
trading_name | string | required | Trading name |
registration_number | string | required | Company registration number: 12 characters once any "/" are removed, e.g. "2020/123456/07" |
tax_number | string | optional | Tax number |
country | string | required | ISO 3-letter country code: "ZAF" or "KEN" |
email | string | required | Business email |
source_of_funds | string | required | Where the business's funds come from. Free text, up to 300 characters |
industry | string | required | The business's industry. Free text, up to 64 characters |
business_size | string | required | Business size, as a string: a single count ("5"), a range ("10-30") or open-ended ("10+") |
Response
Same shape and fields as the create user session response. For this flow, expected_result.id is the future entity_id.
Create Personal Entity Session
The create_personal_entity_request uses the same shape as the Entity Service create request, with entity_type set to "personal". A personal entity represents an individual (a natural person) rather than a company. Its fields are listed below.
The user is created automatically. Once the personal entity is created at submission, SAVA creates its user for you. You don't send a separate create-user request, and the user_id you later need for a card request comes from this automatically created user.
Request
| Field | Type | Required | Description |
|---|---|---|---|
flow_type | string | required | Must be "create_personal_entity" |
create_personal_entity_request | object | required | The personal entity to create. See the fields below |
create_personal_entity_request fields
| Field | Type | Required | Description |
|---|---|---|---|
entity_type | string | required | Must be "personal". Any other value is rejected when the session is created |
name | string | required | Full name of the individual (first name + last name) |
first_name | string | required | First name, at least 2 characters |
last_name | string | required | Last name, at least 2 characters |
email | string | required | Must be a valid email |
phone_number | string | required | Phone number including country code |
gender | string | required | One of: male, female, other |
date_of_birth | string | required | ISO 8601 format; must not be in the future |
country | string | required | ISO 3-letter country code, e.g. "ZAF" |
city | string | optional | City of residence |
residency | string | optional | Residency status |
id_number | string | required | National ID or passport number. A National ID must be exactly 13 digits. Checked for uniqueness when the session is created |
id_type | string | required | "National" or "Passport". A passport requires id_issue_expiry_date |
id_issue_date | string | required | ISO 8601 format; must not be in the future or after the expiry date |
id_issue_expiry_date | string | optional | Required for a passport, not for a National ID |
title | string | optional | e.g. Mr, Ms, Dr, Mx |
permit_number | string | optional | For critical skills permits and similar, when id_type is Passport |
address | object | optional | Address: address_line_1, address_line_2, city, state, postcode. When sent, address_line_1, city, state and postcode are required. The entity's country is used as the address country |
Response
Same shape and fields as the create user session response.
entity_id now, user_id later
For create_personal_entity, expected_result.id is the future entity_id, not the user_id. The user doesn't exist yet, so its ID can't be preallocated: SAVA creates it automatically after the entity is created at submission, with its own new UUID.
The order is: session created (entity_id reserved), the user submits the hosted flow, the personal entity is created with the reserved entity_id, then SAVA creates its user. Because that last step runs in the background, the user_id can lag the entity by a few seconds. See Confirming the result server side; don't treat a briefly missing user as a failure.
Request Card Session
The request_card_request fields are listed below.
Request
| Field | Type | Required | Description |
|---|---|---|---|
flow_type | string | required | Must be "request_card" |
request_card_request | object | required | The card request, same shape as the Cards Service RequestCardRequest |
request_card_request fields
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID (UUID) |
user_id | string | required | User ID (UUID). The user must be KYC-approved |
name | string | required | Name to appear on the card |
type | number | required | Card type: 1=Virtual, 2=Physical |
use_type | number | required | Card use type: 1=Single (rejected), 2=Multi |
features | object | required | Card feature toggles, see Card Features on the Cards Service page |
limits | object | required | Card spending limits: at least one non-zero amount and at most one periodic limit (daily, monthly, or yearly), optionally combined with a transaction limit. Send inactive limits as 0. See Card Limits on the Cards Service page |
KYC comes first
The user must already exist and be KYC-approved before the hosted card request is submitted. If the user is not verified, the card request is rejected. Run your KYC flow against the user_id first, then mint the card session. For individuals onboarded through the personal entity flow, complete that session, resolve the automatically created user_id, run KYC against it, then mint the card session.
Response
Same shape and fields as the create user session response. For this flow, expected_result.id is the future card_request_id. The eventual card uses the same UUID once approved and issued.
Launching the hosted flow
Use one URL from the launch object. Both URLs open the same hosted session, they are provided for different integration surfaces.
Recommended: launch.iframe_url. Embed the session inside your product, in a web app through an HTML iframe or in a mobile app by loading it in a WebView (React Native included). This is the recommended integration for two reasons:
- The iframe flow emits a completion message (see Iframe integration), so your app knows deterministically when to close the view instead of guessing from the status page
- It keeps the end user inside your journey, which fits the channel-partner referral model the hosted session exists to support under the current regulatory position
launch.hosted_url opens the session as a normal full page: redirecting from a web app or opening a new browser tab.
Treat launch URLs as sensitive
The returned URLs include a session token. Do not log them or expose them outside the intended user session.
Iframe integration
Embedding permissions
Pages served at iframe_url do not send X-Frame-Options or a restrictive Content-Security-Policy: frame-ancestors, so your web origin can embed them in an iframe. In a mobile WebView the page loads top-level, so frame restrictions do not apply there at all.
Completion and failure detection
The hosted UI emits a postMessage event to the parent window when the flow finishes, so you never have to scrape the status page. Accept messages only from the SAVA hosted-flow origins:
status | Meaning | What your app should do |
|---|---|---|
submitted | The user completed the flow and the regulated submission succeeded | Close the iframe, WebView, or modal and continue your journey |
failed | The submission failed inside the hosted UI | Show an error or retry UI |
There is no separate message for cancel or expiry; the 15 minute session lifetime is the upper bound on how long to keep the view open.
React Native WebViews
Load iframe_url in the WebView and receive the same message through the WebView's onMessage handler. The message contract is identical.
Confirming the result server side
The completion message is a client-side signal. There is currently no partner-facing hosted-session completion notification or status endpoint, so confirm the record from your backend using the preallocated ID:
create_user: pollsvc.user.<partner_id>.get_userorsvc.user.<partner_id>.listuntil the preallocateduser_idappearscreate_business_entity: pollsvc.entity.<partner_id>.list-entitiesuntil the preallocatedentity_idappearscreate_personal_entity: pollsvc.entity.<partner_id>.list-entitiesuntil the preallocatedentity_idappears. Its user is created automatically moments later: resolve theuser_idby pollingsvc.user.<partner_id>.listfor the user linked to that entity. A short delay between the entity and its user appearing is normalrequest_card: thecard_request_idfollows the normal card issuance lifecycle; the card becomes visible throughlist_cardsonce issued, and its details are shown to the cardholder through the Card Reveal (authorize_reveal) flow
User experience
You only open or embed the launch URL. SAVA owns the hosted session user experience after launch:
There is no partner-side route integration. Do not construct form or status URLs manually.
Session status
The create response always returns session.status as created. SAVA moves the session through these statuses as the user goes through the flow:
status | Meaning |
|---|---|
created | The session was created. The user has not submitted the form yet |
submitted | The user submitted the form and SAVA is creating the record |
completed | SAVA created the record with the preallocated expected_result.id |
failed | Creating the record failed and nothing was created. The user can retry in the hosted UI while the session is still valid; otherwise create a new session |
You can't read the status after the create call: there is no status endpoint or notification for hosted sessions. To follow the outcome, use the iframe completion message on the client (submitted once the record is created, or failed), then confirm the record server side with the preallocated ID.
Session expiry
Hosted sessions are valid for 15 minutes from creation. You do not need to send an expiry value. Expired sessions cannot be loaded or submitted. On expiry, minting a new session is the only action expected from you, there is no cleanup.
Abandoned sessions and duplicates
Every new session gets a new session ID and a new preallocated expected_result.id; abandoned sessions are simply never fulfilled. Minting a session is not idempotent from your side, so guard against creating duplicate users or entities in your own flow, and reconcile which session completed by looking up the final record with its preallocated ID.