Skip to main content
Each session is a point-in-time object created by the Session Management API. It carries the recipient’s information, governs the iFrame interaction lifecycle, and expires or terminates based on the outcome of the recipient’s account capture flow.

​
Session states

StateMeaning
ActiveSession has been created and the authorized_url is valid.
ExpiredThe authorized_url was not mounted within 30 seconds. The session itself remains valid — use idempotency to generate a new authorized_url.
CompletedThe recipient successfully tokenized an account (TOKEN_SUCCESS). The session cannot be mounted again.
Canceled / TerminatedThe recipient canceled, or the session was terminated due to a terminal failure. A new session must be created to retry.
Max Attempts ExceededThe recipient exceeded the configured verification attempt threshold. The session is terminated and cannot be reused.

​
Idempotency

The Session Management API supports idempotency to prevent duplicate sessions from being created when a network error or session event requires you to generate a new authorized_url for an existing session. To make an idempotent request, include the Idempotency-Key header with the same value used in the original request: 
Idempotency-Key: 70646041-01ea-4cd6-b657-18ff88e465c7
HeaderDescriptionMax Length
Idempotency-KeyA unique value you generate per session. Recommended: V4 UUID or GUID.250
When the server receives a request with a previously used idempotency key, it returns the original session with a new authorized_url — no new session is created. Idempotency keys remain active for 2 hours. After expiration, the same key will generate a new session. If the incoming request parameters do not match the original, the server returns an error to prevent accidental misuse.

​
Response codes

StatusMessageDescription
100SuccessNew session created.
101Success - IdempotentExisting session returned; new authorized_url issued. No new session created.
13723Idempotency key mismatchIncoming parameters do not match the original request.

​
Common scenarios

Network error on session create — If the initial request times out before you receive a response, retry with the same idempotency key. You are guaranteed to receive at most one session regardless of how many retries are sent. Non-terminal verification failure — If the recipient fails verification (e.g., RVDM mismatch) but has not yet exceeded the maximum attempt threshold, the session remains active. Retry with the same idempotency key to generate a fresh authorized_url and allow the recipient to re-enter the flow. 
{
  "status": 101,
  "client_message": "Success - Idempotent",
  "data": {
    "session_identifier": "5cf34a7d-25b6-4400-b19d-53a171d324e1",
    "authorized_url": "https://iip-webplugin-uat.ingo.money/session/5cf34a7d-...",
    "authorized_url_expiration_utc": "2024-01-17T20:30:30Z",
    "participant_unique_id1": "2639d2ce-2e74-48a4-be74-9bb90a62b40b",
    "participant_unique_id2": ""
  }
}

​
Locale

The iFrame UI can be rendered in any of the supported languages by passing the language_locale_code parameter in the session create request. If omitted, the iFrame defaults to the first configured language for your program. 
{
  "language_locale_code": "es-US",
  ...
}

​
Supported locale codes

CodeLanguage / Region
ar-SAArabic (Saudi Arabia)
cs-CZCzech (Czech Republic)
da-DKDanish (Denmark)
de-DEGerman (Germany)
en-GBEnglish (United Kingdom)
en-USEnglish (United States)
es-ESSpanish (Spain)
es-USSpanish (United States)
fa-IRFarsi (Iran)
fi-FIFinnish (Finland)
fr-FRFrench (France)
hmn-LatnHmong (Latin)
it-ITItalian (Italy)
ja-JPJapanese (Japan)
km-KHKhmer (Cambodia)
ko-KRKorean (Korea)
nb-NONorwegian (Norway)
nl-NLDutch (Netherlands)
pl-PLPolish (Poland)
pt-BRPortuguese (Brazil)
ru-RURussian (Russia)
sv-SESwedish (Sweden)
tl-PHTagalog (Philippines)
tr-TRTurkish (Turkey)
vi-VNVietnamese (Vietnam)
zh-CNChinese (China)
zh-HansChinese (Simplified)
zh-TWChinese (Taiwan)