​
Overview

This guide covers advanced implementation details for webview integration. For a quick start, see the Quickstart Guide. Integration Method: OAuth 2.0 authorization code flow with hosted verification UI

​
How It Works

​
Testing and Debugging

​
Pre-build Callback receiver

Use https://gateway-result.vercel.app/{your_client_id}/callback as your redirect URI for quick testing without setting up a backend.
provides:
  • Automatic callback handling
  • Frontend token exchange (test environment only)
  • Decoded ID token display with all claims
  • PKCE flow testing support
  • Copy token functionality for further debugging

​
Dashboard Configuration

​
Redirect URI Management

Configure your application’s redirect URIs in the hConnect Developer Dashboard:
  1. Navigate to Application Settings
    • Log in to your dashboard
    • Select your application
    • Go to “Developers” section
  2. Add Redirect URIs
URI Priority and Default Behavior: When redirect_uri parameter is omitted from the verification URL, hConnect automatically uses the first URI in your whitelist. Order your URIs strategically with your primary URI first.
// Without redirect_uri parameter - uses first whitelisted URI
const verifyUrl = `https://verify.hopae.com?client_id=${CLIENT_ID}`;

// With explicit redirect_uri - must be whitelisted
const verifyUrl = `https://verify.hopae.com?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}`;
If you provide a redirect_uri that is not whitelisted, it will be automatically replaced with your default (first) whitelisted URI.

​
Implementation Details

​
Verification URL Construction

Build the verification URL with required and optional parameters: 
// Base URL
const BASE_URL = "https://verify.hopae.com"; // Production
// const BASE_URL = 'https://sandbox.verify.hopae.com';  // Sandbox

// Required parameter
const params = new URLSearchParams({
  client_id: "YOUR_CLIENT_ID",
});

// Optional parameters
params.append("redirect_uri", "https://yourapp.com/callback"); // Must be whitelisted

// PKCE parameters (recommended for public clients)
const codeVerifier = generateCodeVerifier(); // Your function to generate verifier
const codeChallenge = generateCodeChallenge(codeVerifier); // Your function to generate challenge
params.append("code_challenge", codeChallenge);
params.append("code_challenge_method", "S256");

const verifyUrl = `${BASE_URL}?${params.toString()}`;

​
URL Parameters Reference

ParameterRequiredDescriptionExample
client_idYesYour hConnect Client ID5SZdu0fn
redirect_uriNoCallback URL (must be whitelisted). If omitted, uses first whitelisted URIhttps://yourapp.com/callback
code_challengeNoPKCE code challenge for enhanced securityE9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
code_challenge_methodNoMethod used to generate code challenge (only S256 supported)S256

​
PKCE Support

hConnect supports PKCE (Proof Key for Code Exchange) for enhanced security, especially recommended for public clients like SPAs and mobile apps: 
// Generate PKCE parameters
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64urlEncode(array);
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest("SHA-256", data);
  return base64urlEncode(new Uint8Array(hash));
}

// Include in verification URL
const verifyUrl = `https://verify.hopae.com?client_id=${CLIENT_ID}&code_challenge=${codeChallenge}&code_challenge_method=S256`;

// Store code_verifier for token exchange
sessionStorage.setItem("code_verifier", codeVerifier);
PKCE adds an extra layer of security by ensuring that only the client that initiated the authorization request can exchange the code for tokens.

​
Callback Handling

​
Response Parameters

Success Response: 
{YOUR_REDIRECT_URI}?code=auth_abc123
Error Response: 
{YOUR_REDIRECT_URI}?error=access_denied&error_description=User%20cancelled
ParameterDescription
codeAuthorization code (valid for 5 minutes, single use)
errorError code (see error handling section)
error_descriptionHuman-readable error message

​
Token Exchange

Exchange the authorization code for user data: 
curl -X POST https://sandbox.connect.hopae.com/api/v1/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
      "grant_type": "authorization_code",
      "code": "auth_abc123",
      "client_id": "client123",
      "client_secret": "secret456",
      "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
    }'

​
ID Token Claims

ClaimTypeDescriptionExample
issstringToken issuer (always “hopae”)"hopae"
substringUnique user identifier"wPqH84Q4pDiE..."
audstringYour Client ID"5SZdu0fn"
eidstringProvider type identifier"bankidse"
provider_idstringProvider-specific user ID"198507124567"
namestringFull name"Anders Eriksson"
given_namestringFirst name"Anders"
family_namestringLast name"Eriksson"
birthdatestringDate of birth (YYYY-MM-DD)"1985-07-12"
iatnumberIssued at (Unix timestamp)1755611261
expnumberExpiration (Unix timestamp)1755614861
Not all providers return all claims. Only sub, name, and eid are guaranteed. Always implement fallbacks for optional fields.

​
Mobile Integration

​
React Native with WebView

import React from "react";
import { WebView } from "react-native-webview";

function VerificationScreen({ onSuccess, onError }) {
  const CLIENT_ID = "YOUR_CLIENT_ID";
  const REDIRECT_URI = "yourapp://callback";

  const verifyUrl = `https://verify.hopae.com?client_id=${CLIENT_ID}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;

  const handleNavigationChange = (navState) => {
    if (navState.url.startsWith(REDIRECT_URI)) {
      const url = new URL(navState.url);
      const code = url.searchParams.get("code");
      const error = url.searchParams.get("error");

      if (code) {
        onSuccess(code);
      } else if (error) {
        onError(error);
      }
    }
  };

  return <WebView source={{ uri: verifyUrl }} onNavigationStateChange={handleNavigationChange} startInLoadingState={true} />;
}

​
Expo SDK Integration

hConnect Expo SDK

Official Expo SDK for hConnect integration

​
Common Issues and Solutions

​
Next Steps

API Integration

Build custom verification UI with direct API calls

Provider Reference

Explore supported countries and identity providers

Token Exchange API

Detailed token exchange documentation

Verification Flow

Understand the complete verification process