> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Lifecycle

> Session states, idempotency, and locale configuration for Embedded Account Capture sessions.

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

| State                 | Meaning                                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Active                | Session has been created and the `authorized_url` is valid.                                                                                    |
| Expired               | The `authorized_url` was not mounted within 30 seconds. The session itself remains valid — use idempotency to generate a new `authorized_url`. |
| Completed             | The recipient successfully tokenized an account (`TOKEN_SUCCESS`). The session cannot be mounted again.                                        |
| Canceled / Terminated | The recipient canceled, or the session was terminated due to a terminal failure. A new session must be created to retry.                       |
| Max Attempts Exceeded | The 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:

```http theme={null}
Idempotency-Key: 70646041-01ea-4cd6-b657-18ff88e465c7
```

| Header            | Description                                                            | Max Length |
| ----------------- | ---------------------------------------------------------------------- | ---------- |
| `Idempotency-Key` | A 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

| Status  | Message                  | Description                                                                     |
| ------- | ------------------------ | ------------------------------------------------------------------------------- |
| `100`   | Success                  | New session created.                                                            |
| `101`   | Success - Idempotent     | Existing session returned; new `authorized_url` issued. No new session created. |
| `13723` | Idempotency key mismatch | Incoming 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "language_locale_code": "es-US",
  ...
}
```

### Supported locale codes

| Code       | Language / Region        |
| ---------- | ------------------------ |
| `ar-SA`    | Arabic (Saudi Arabia)    |
| `cs-CZ`    | Czech (Czech Republic)   |
| `da-DK`    | Danish (Denmark)         |
| `de-DE`    | German (Germany)         |
| `en-GB`    | English (United Kingdom) |
| `en-US`    | English (United States)  |
| `es-ES`    | Spanish (Spain)          |
| `es-US`    | Spanish (United States)  |
| `fa-IR`    | Farsi (Iran)             |
| `fi-FI`    | Finnish (Finland)        |
| `fr-FR`    | French (France)          |
| `hmn-Latn` | Hmong (Latin)            |
| `it-IT`    | Italian (Italy)          |
| `ja-JP`    | Japanese (Japan)         |
| `km-KH`    | Khmer (Cambodia)         |
| `ko-KR`    | Korean (Korea)           |
| `nb-NO`    | Norwegian (Norway)       |
| `nl-NL`    | Dutch (Netherlands)      |
| `pl-PL`    | Polish (Poland)          |
| `pt-BR`    | Portuguese (Brazil)      |
| `ru-RU`    | Russian (Russia)         |
| `sv-SE`    | Swedish (Sweden)         |
| `tl-PH`    | Tagalog (Philippines)    |
| `tr-TR`    | Turkish (Turkey)         |
| `vi-VN`    | Vietnamese (Vietnam)     |
| `zh-CN`    | Chinese (China)          |
| `zh-Hans`  | Chinese (Simplified)     |
| `zh-TW`    | Chinese (Taiwan)         |