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 used up the maximum number of retries allowed by the flowsession.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.errorSee Technical errors
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 event (.completed on iOS, TrustPlatformEvent.Completed on Android) only tells you that the flow ended. Always read the outcome before acting.

Step events follow the same rule: a step that ended normally finished, it does not mean the user passed. See Track step progress.

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. For verification steps, read the codes in the Verification data block and look them up on Verification reason codes. For signal steps, read DigitalSignals.reasons[].code; those codes are defined by the signal provider (see DigitalSignals). Then decide whether to retry or stop. See Get data blocks and Rejection reasons.

Technical errors​

ERROR means a step failed for a technical reason. It is not a business decision, so the session has no outcome and no reason code. Handling is the same for every step:

  • If the user returns, start a new session.
  • Don't branch on lastStep.stepStatusDetails. It is diagnostic text for support and may change without notice.
  • If errors persist, contact support with the sessionId, the eventId and the lastStep.stepStatusDetails value.
PageWhat it covers
SessionsEvery sessionStatus value and how sessions move between them
Rejection reasonsWhere decision details live in the data blocks
Verification reason codesEvery reason code and what it means
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
Track step progressFollow a session step by step while it runs
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.