Checking access…

Skip to main content
Version: v2

HSID

Use this guide to integrate HealthSafe ID system for customer journeys that depend on merchant-level authenticationStrategy configuration at the time of merchant onboarding see Merchant Settings Authentication Strategy. The strategy determines whether identity-provider authentication is mandatory (IDP_REQUIRED) or not (IDP_NOT_REQUIRED) before wallet-sensitive actions continue.

Integration Details
  • Merchant Strategies: IDP_REQUIRED, IDP_NOT_REQUIRED
  • Where strategy is set: Merchant onboarding/configuration
  • Where strategy is enforced: Session creation API resolution flows
  • Session creation URL (staging): https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/sessions

Overview​

This integration pattern ensures the customer identity requirement is applied consistently for each merchant.

  • IDP_REQUIRED: Identity authentication must be completed before protected actions proceed.
  • IDP_NOT_REQUIRED: Wallet flows will continue without mandatory identity login; customer identity will be based on request input.

Typical usage:

  1. Merchant configures authenticationStrategy during onboarding.
  2. Merchant creates Session.
  3. CCG evaluates strategy and customer identity context.
  4. Flow continues, blocks, or prompts for next-step identity action.
🔒 InternalInternal information — not visible in the public (merchant) site.

IDP Processing Flow​

Internal Session LifeCycle​

Merchant facing Session LifeCycle​

API Request​

Use Session creation with your configured authenticationStrategy behavior.

API Response​

The authentication strategy affects the response path and next actions.

FAQ​

What should an IDP_REQUIRED merchant do after creating a session?​

Open the hostedURL returned by POST /v2/sessions so the customer enters the hosted flow and completes HSID authentication.

What is the response of GET /v2/checkout-sessions/{sessionId} and GET /v2/sessions/{sessionId} when session status is AWAITING_AUTHN?​

  • When session status is AWAITING_AUTHN , Response of GET /v2/checkout-sessions/{sessionId} is HTTP 401
  • When session status is AWAITING_AUTHN , Response of GET /v2/sessions/{sessionId} is HTTP 202 with status PENDING

What should happen after the customer completes HSID authentication?​

Call GET /v2/sessions/{sessionId} again to retrieve the latest public session status.

What status should I expect while the customer is authenticating?​

During HSID authentication, GET /v2/sessions/{sessionId} can return PENDING until the session reaches a final status.

Which final statuses can be returned for the public merchant session?​

The public final statuses are COMPLETED, FAILED, and CANCELED.

Do I need to send HSID in the session request for IDP_REQUIRED?​

No. For IDP_REQUIRED, customer identity is resolved through the hosted HSID authentication flow.

Can IDP_NOT_REQUIRED still use customer identifiers from the request?​

Yes. For IDP_NOT_REQUIRED, customer identity can be resolved using merchant-provided identifiers.

Integration Checklist​

  • Confirm merchant authenticationStrategy is configured in merchant settings as expected.
  • Calling POST /v2/sessions
  • Opening the returned hostedURL
  • Test both IDP_REQUIRED and IDP_NOT_REQUIRED paths in staging.