API References

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

Partner AppSAVA BaaS APIsvc.hosted_session.*Hosted Session UISAVA-ownedEnd Usercreate session (flow_type + data)hosted_url + iframe_url, result ID preallocatedredirect to hosted_url or embed iframe_urlreview prefilled data, consent, submitregulated submission + consent audit trailrecord created with the preallocated ID

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.

  1. Your system calls the SAVA BaaS API with the user, business entity, personal entity, or card request data
  2. SAVA preallocates the expected_result.id and returns hosted_url and iframe_url
  3. Your application presents one of those URLs to the end user
  4. The prefilled UI is for review and submission, not editing
  5. 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:

FlowCreatesexpected_result.id becomes
create_userA user under an entityThe future user_id
create_business_entityA business entityThe future entity_id
create_personal_entityA personal entity, and its user automaticallyThe future entity_id (the user_id is created after submission, see Create Personal Entity Session)
request_cardA card requestThe 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

Create user session
{
  "flow_type": "create_user",
  "create_user_request": {
    "entity_id": "<uuid>",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "phone_number": "<string>",
    "gender": "<string>",
    "date_of_birth": "<datetime>",     // Required: ISO 8601 format
    "country": "<ISO-3166-alpha-3-string>",
    "city": "<string>",
    "residency": "<string>",
    "id_number": "<string>",
    "id_type": "<string>",             // Required: National = no expiry, passport needs expiry
    "id_issue_date": "<datetime>",
    "id_issue_expiry_date": "<datetime>",
    "title": "<string>",
    "verified": false,
    "permit_number": "<string>",       // Required only if id_type is not national
    "address": {                       // Required
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<ISO-3166-alpha-3-string>",
      "postcode": "<string>"
    }
  }
}
FieldTypeRequiredDescription
flow_typestringrequiredMust be "create_user"
create_user_requestobjectrequiredThe user to create. See the fields below

create_user_request fields

FieldTypeRequiredDescription
entity_idstringrequiredUUID of the entity the user belongs to
first_namestringrequiredFirst name
last_namestringrequiredLast name
emailstringrequiredMust be a valid email
phone_numberstringrequiredPhone number including country code
genderstringrequiredOne of: male, female, other
date_of_birthstringrequiredISO 8601 format
countrystringrequiredISO 3-letter country code, e.g. "ZAF"
citystringrequiredCity of residence
residencystringrequiredResidency status
id_numberstringrequiredNational ID or passport number
id_typestringrequiredNational needs no expiry; passport requires id_issue_expiry_date
id_issue_datestringrequiredISO 8601 format
id_issue_expiry_datestringoptionalRequired for passport, not for a National ID
titlestringrequirede.g. Mr, Ms, Dr, Mx
verifiedbooleanrequiredSend false; verification happens through KYC
permit_numberstringoptionalRequired only if id_type is not national
addressobjectrequiredAddress: address_line_1, address_line_2, city, state, country, postcode

Response

Create user session response
{
  "session": {
    "id": "<hosted-session-id>",
    "partner_id": "<partner-id>",
    "flow_type": "create_user",
    "status": "created",
    "expected_result_id": "<preallocated-user-id>",
    "expires_at": "2026-05-15T00:15:00Z",
    "created_at": "2026-05-15T00:00:00Z",
    "updated_at": "2026-05-15T00:00:00Z"
  },
  "launch": {
    "hosted_url": "https://<sava-hosted-session-url>",
    "iframe_url": "https://<sava-hosted-session-iframe-url>"
  },
  "expected_result": {
    "type": "CreateUserResponse",
    "id": "<preallocated-user-id>"
  }
}
FieldTypeDescription
session.idstringHosted session ID
session.partner_idstringYour partner ID
session.flow_typestringThe flow this session was created for
session.statusstringAlways created in this response: the session exists and nothing has been submitted yet. See Session status
session.expected_result_idstringThe preallocated result ID (same value as expected_result.id)
session.expires_atstringExpiry timestamp, 15 minutes after creation
launch.hosted_urlstringLaunch URL for redirect, browser tab, or mobile WebView
launch.iframe_urlstringLaunch URL for embedding in an iframe
expected_result.typestringThe response type the flow will produce
expected_result.idstringFor 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

Create business entity session
{
  "flow_type": "create_business_entity",
  "create_business_entity_request": {
    "entity_type": "business",         // Required: must be "business"
    "name": "<string>",
    "trading_name": "<string>",
    "registration_number": "<string>",
    "tax_number": "<string>",
    "country": "<ISO-3166-alpha-3-string>",  // "ZAF" or "KEN"
    "email": "<string>",
    "source_of_funds": "<string>",     // Free text, up to 300 characters
    "industry": "<string>",            // Free text, up to 64 characters
    "business_size": "<string>"        // "5", "10-30" or "10+"
  }
}
FieldTypeRequiredDescription
flow_typestringrequiredMust be "create_business_entity"
create_business_entity_requestobjectrequiredThe business entity to create, same shape as the Entity Service create request

create_business_entity_request fields

FieldTypeRequiredDescription
entity_typestringrequiredMust be "business"
namestringrequiredCompany name
trading_namestringrequiredTrading name
registration_numberstringrequiredCompany registration number: 12 characters once any "/" are removed, e.g. "2020/123456/07"
tax_numberstringoptionalTax number
countrystringrequiredISO 3-letter country code: "ZAF" or "KEN"
emailstringrequiredBusiness email
source_of_fundsstringrequiredWhere the business's funds come from. Free text, up to 300 characters
industrystringrequiredThe business's industry. Free text, up to 64 characters
business_sizestringrequiredBusiness size, as a string: a single count ("5"), a range ("10-30") or open-ended ("10+")

Response

Create business entity session response
{
  "session": {
    "id": "<hosted-session-id>",
    "partner_id": "<partner-id>",
    "flow_type": "create_business_entity",
    "status": "created",
    "expected_result_id": "<preallocated-entity-id>",
    "expires_at": "2026-05-15T00:15:00Z",
    "created_at": "2026-05-15T00:00:00Z",
    "updated_at": "2026-05-15T00:00:00Z"
  },
  "launch": {
    "hosted_url": "https://<sava-hosted-session-url>",
    "iframe_url": "https://<sava-hosted-session-iframe-url>"
  },
  "expected_result": {
    "type": "CreateEntityResponse",
    "id": "<preallocated-entity-id>"
  }
}

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

Create personal entity session
{
  "flow_type": "create_personal_entity",
  "create_personal_entity_request": {
    "entity_type": "personal",         // Required: must be "personal"
    "name": "<string>",                // Full name, e.g. "<first_name> <last_name>"
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "phone_number": "<string>",
    "gender": "<string>",              // One of: male, female, other
    "date_of_birth": "<datetime>",     // ISO 8601 format
    "country": "<ISO-3166-alpha-3-string>",
    "city": "<string>",
    "residency": "<string>",
    "id_number": "<string>",           // National ID = exactly 13 digits
    "id_type": "<string>",             // "National" or "Passport"
    "id_issue_date": "<datetime>",
    "id_issue_expiry_date": "<datetime>",  // Required for passport
    "title": "<string>",
    "permit_number": "<string>",
    "address": {
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postcode": "<string>"
    }
  }
}
FieldTypeRequiredDescription
flow_typestringrequiredMust be "create_personal_entity"
create_personal_entity_requestobjectrequiredThe personal entity to create. See the fields below

create_personal_entity_request fields

FieldTypeRequiredDescription
entity_typestringrequiredMust be "personal". Any other value is rejected when the session is created
namestringrequiredFull name of the individual (first name + last name)
first_namestringrequiredFirst name, at least 2 characters
last_namestringrequiredLast name, at least 2 characters
emailstringrequiredMust be a valid email
phone_numberstringrequiredPhone number including country code
genderstringrequiredOne of: male, female, other
date_of_birthstringrequiredISO 8601 format; must not be in the future
countrystringrequiredISO 3-letter country code, e.g. "ZAF"
citystringoptionalCity of residence
residencystringoptionalResidency status
id_numberstringrequiredNational ID or passport number. A National ID must be exactly 13 digits. Checked for uniqueness when the session is created
id_typestringrequired"National" or "Passport". A passport requires id_issue_expiry_date
id_issue_datestringrequiredISO 8601 format; must not be in the future or after the expiry date
id_issue_expiry_datestringoptionalRequired for a passport, not for a National ID
titlestringoptionale.g. Mr, Ms, Dr, Mx
permit_numberstringoptionalFor critical skills permits and similar, when id_type is Passport
addressobjectoptionalAddress: 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

Create personal entity session response
{
  "session": {
    "id": "<hosted-session-id>",
    "partner_id": "<partner-id>",
    "flow_type": "create_personal_entity",
    "status": "created",
    "expected_result_id": "<preallocated-entity-id>",
    "expires_at": "2026-05-15T00:15:00Z",
    "created_at": "2026-05-15T00:00:00Z",
    "updated_at": "2026-05-15T00:00:00Z"
  },
  "launch": {
    "hosted_url": "https://<sava-hosted-session-url>",
    "iframe_url": "https://<sava-hosted-session-iframe-url>"
  },
  "expected_result": {
    "type": "CreateEntityResponse",
    "id": "<preallocated-entity-id>"
  }
}

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

Request card session
{
  "flow_type": "request_card",
  "request_card_request": {
    "account_id": "<uuid>",    // Required: account ID
    "user_id": "<uuid>",       // Required: user ID
    "name": "John Doe",        // Required: name on the card
    "type": 1,                 // Required: 1=Virtual, 2=Physical
    "use_type": 2,             // Required: 1=Single (rejected), 2=Multi
    "features": {              // Required: API honours these (international ignored)
      "domestic": true,
      "international": false,
      "e_commerce": true,
      "atm": true,
      "pos": true,
      "contactless": true
    },
    "limits": {                // Required: at most one periodic limit
      "transaction_enabled": true,
      "transaction": 20000,
      "daily_enabled": true,
      "daily": 20000,
      "monthly_enabled": false,
      "monthly": 0,
      "yearly_enabled": false,
      "yearly": 0
    }
  }
}
FieldTypeRequiredDescription
flow_typestringrequiredMust be "request_card"
request_card_requestobjectrequiredThe card request, same shape as the Cards Service RequestCardRequest

request_card_request fields

FieldTypeRequiredDescription
account_idstringrequiredAccount ID (UUID)
user_idstringrequiredUser ID (UUID). The user must be KYC-approved
namestringrequiredName to appear on the card
typenumberrequiredCard type: 1=Virtual, 2=Physical
use_typenumberrequiredCard use type: 1=Single (rejected), 2=Multi
featuresobjectrequiredCard feature toggles, see Card Features on the Cards Service page
limitsobjectrequiredCard 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

Request card session response
{
  "session": {
    "id": "<hosted-session-id>",
    "partner_id": "<partner-id>",
    "flow_type": "request_card",
    "status": "created",
    "expected_result_id": "<preallocated-card-request-id>",
    "expires_at": "2026-05-15T00:15:00Z",
    "created_at": "2026-05-15T00:00:00Z",
    "updated_at": "2026-05-15T00:00:00Z"
  },
  "launch": {
    "hosted_url": "https://<sava-hosted-session-url>",
    "iframe_url": "https://<sava-hosted-session-iframe-url>"
  },
  "expected_result": {
    "type": "RequestCardResponse",
    "id": "<preallocated-card-request-id>"
  }
}

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:

Listen for completion (browser iframe)
const ALLOWED_ORIGINS = new Set([
  "https://dytna.sava.africa",                  // production hosted flow origin
  "https://staging--daytona-sava.netlify.app",  // staging hosted flow origin
]);
 
window.addEventListener("message", (event) => {
  if (!ALLOWED_ORIGINS.has(event.origin)) return;
  if (event.data?.type !== "daytona.hostedFlow.close") return;
  if (event.data?.version !== 1) return;
 
  const { sessionId, status } = event.data;
 
  if (status === "submitted") {
    // Submission succeeded: close the iframe or modal and continue
  }
 
  if (status === "failed") {
    // Submission failed: show an error, keep the iframe open, or offer retry
  }
});
Message shape
{
  "type": "daytona.hostedFlow.close",
  "version": 1,
  "sessionId": "uuid",
  "status": "submitted"
}
statusMeaningWhat your app should do
submittedThe user completed the flow and the regulated submission succeededClose the iframe, WebView, or modal and continue your journey
failedThe submission failed inside the hosted UIShow 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: poll svc.user.<partner_id>.get_user or svc.user.<partner_id>.list until the preallocated user_id appears
  • create_business_entity: poll svc.entity.<partner_id>.list-entities until the preallocated entity_id appears
  • create_personal_entity: poll svc.entity.<partner_id>.list-entities until the preallocated entity_id appears. Its user is created automatically moments later: resolve the user_id by polling svc.user.<partner_id>.list for the user linked to that entity. A short delay between the entity and its user appearing is normal
  • request_card: the card_request_id follows the normal card issuance lifecycle; the card becomes visible through list_cards once 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:

Launch URL -> flow-specific form -> status page

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:

statusMeaning
createdThe session was created. The user has not submitted the form yet
submittedThe user submitted the form and SAVA is creating the record
completedSAVA created the record with the preallocated expected_result.id
failedCreating 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.