Skip to main content

Interpret session results

Understand what a session's status and outcome mean, and what to do next​

A session has two layers. Telling them apart is the key to using the Trust Platform correctly:

  • Where the session got to: its sessionStatus, one of CREATED, RUNNING, COMPLETED, ABORTED, EXPIRED or ERROR. This is the technical state of the flow.
  • What the business decision was: its outcome, either accepted or rejected. It is only set when the session reached COMPLETED. For every other status, outcome is NO_OUTCOME.

So COMPLETED does not mean "approved". It means the flow finished, and the flow may have finished by rejecting the user. Your integration should branch on the outcome, not only on the status, and read the reason codes when the outcome is rejected.

This page puts the whole picture in one place: what each status means, which webhook fires, and what your backend should do next.

Decision matrix​

sessionStatusoutcomeWhat happenedWebhookRecommended action
COMPLETEDacceptedThe flow finished and the user passedsession.completedGrant access. Fetch the data blocks for your records
COMPLETEDrejectedThe flow finished and the user was declinedsession.completedRead the reason code from the data blocks. Decide whether to retry or stop
ABORTEDNO_OUTCOMEThe user stopped, or rollback retries ran outsession.abortedIf the user returns, start a new session
EXPIREDNO_OUTCOMEThe session lifetime was reached (default 24 h)session.expiredStart a new session
ERRORNO_OUTCOMEA technical failure occurred in a stepsession.errorCheck lastStep.stepStatusDetails. Contact support with the eventId
warning

session.completed means the flow finished, not that the user passed. The accepted or rejected decision is in the outcome. The same applies to the mobile SDK: a completed result (FlowOutcome.completed on iOS, TrustPlatformResult.Completed on Android) only tells you that the flow ended. Always read the outcome before acting.

From webhook to action​

When a session ends, IDnow notifies you with a webhook. Getting from that notification to a decision in your system takes five steps:

  1. Receive the webhook. The request body is a JWT, not plain JSON. Verify its signature and standard claims (iss, aud, sub, exp, iat) before trusting anything inside it. aud must match the endpoint URL you configured, and sub is the event ID. See Webhook events.
  2. Read the event. Decode the payload and look at the fields under data, in particular eventName (session.completed, session.aborted, session.expired or session.error) and payload.sessionStatus.
  3. Check whether there is a decision to read. If sessionStatus is COMPLETED, the flow finished with a business outcome. For any other terminal status there is no outcome: use the decision matrix above.
  4. Fetch the result. Call GET /api/v1/{environment}/sessions/{sessionId} and read outcome. If it is accepted, act on the success. If it is rejected, you need the reason. See Get session results.
  5. Read the reason and act. Fetch the session's data blocks with GET /api/v1/{environment}/sessions/{sessionId}/datablocks. Steps that make a decision record why: look for Verification.terminationReason.code (verification steps) or DigitalSignals.reasons[].code (signal steps), then decide whether to retry or stop. See Get data blocks and Rejection reasons.
PageWhat it covers
SessionsEvery sessionStatus value and how sessions move between them
Rejection reasonsWhere decision details live in the data blocks
Get session resultsThe session endpoint and its response
Get data blocksThe data blocks endpoint and its response
Webhook eventsEvent types, payload fields and JWT verification
Error codesErrors returned by the API itself
note

API error codes and verification reason codes are two different families. API error codes describe a failed API request. Reason codes describe why a verification step reached its decision, and are found in the data blocks.