Session states
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 newauthorized_url for an existing session.
To make an idempotent request, include the Idempotency-Key header with the same value used in the original request:
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
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 freshauthorized_url and allow the recipient to re-enter the flow.
Locale
The iFrame UI can be rendered in any of the supported languages by passing thelanguage_locale_code parameter in the session create request. If omitted, the iFrame defaults to the first configured language for your program.