Connect in a React Native WebView

# Uses your PORTAL SESSION (a signed-in dashboard user), not the
# API key pair used for the mint below.
# The client update endpoint is guarded by your dashboard login.
curl -X PUT https://api.billerapi.com/iam/clients/$BILLERAPI_CLIENT_ID \
  -H "Authorization: Bearer <portal-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_uris": ["https://yourapp.com/billerapi/callback"] }'

import React, { useEffect, useState } from 'react';
import {
  WebView,
  type WebViewNavigation,
  type ShouldStartLoadRequest,
} from 'react-native-webview';

// The exact https redirect_uri you registered + minted with.
const REDIRECT_URI = 'https://yourapp.com/billerapi/callback';

type ConnectResult = 'completed' | 'exited';

// Parse without the URL / URLSearchParams API — React Native's built-in URL
// does NOT implement .searchParams (it throws), so read the query with a regex.
function readLinkStatus(url: string): ConnectResult {
  const match = /[?&]link_status=([^&]+)/.exec(url);
  return match?.[1] === 'completed' ? 'completed' : 'exited';
}

export function ConnectWebView({
  onComplete,
  onError,
}: {
  onComplete: (status: ConnectResult) => void;
  onError: (message: string) => void;
}) {
  const [hostedUrl, setHostedUrl] = useState<string | null>(null);

  // 1. Ask YOUR server to mint the token and hand back only the hosted_url.
  useEffect(() => {
    fetch('https://your-backend.example.com/mint-connect-url', { method: 'POST' })
      .then((r) => r.json())
      .then((d: { hosted_url: string }) => setHostedUrl(d.hosted_url))
      .catch(() => onError('Could not start Connect'));
  }, [onError]);

  if (!hostedUrl) return null;

  // 2. Intercept the redirect back to our callback => the session finished.
  //    Returning false stops the WebView from loading the callback page.
  const shouldLoad = (req: ShouldStartLoadRequest): boolean => {
    if (req.url.startsWith(REDIRECT_URI)) {
      onComplete(readLinkStatus(req.url));
      return false; // handled — do not load
    }
    return true;
  };

  return (
    <WebView
      source={{ uri: hostedUrl }}
      onShouldStartLoadWithRequest={shouldLoad}
      onError={() => onError('WebView failed to load')}
      originWhitelist={['https://*']}
      javaScriptEnabled
      domStorageEnabled
    />
  );
}

{
  "id": "evt_01HX...",
  "object": "event",
  "type": "link.session_finished",
  "api_version": "2026-04-29",
  "created": 1714387260,
  "environment": "prod",
  "data": {
    "object": {
      "id": "lt_01HX5...",
      "object": "link_token",
      "link_token_id": "lt_01HX5...",
      "status": "completed",
      "link_id": "link_01HX5...",
      "biller_id": "test_electric_company",
      "user_id": "user_42"
    }
  },
  "request": { "id": null, "idempotency_key": null }
}

# no auth header — the lt_ token in the path is the credential
curl https://api.billerapi.com/v1/link/token/lt_01HX5.../status

# => { "status": "completed", "completed_at": "...", "redirect_uri": "https://yourapp.com/billerapi/callback" }
# public_token is stripped from this response

# call this when the user dismisses the WebView
curl -X POST https://api.billerapi.com/v1/link/token/lt_01HX5.../exit \
  -H "Content-Type: application/json" \
  -d '{ "exit_reason": "user_closed" }'
# => 201

# Production gateway with a bak_test_ (sandbox-tier) key — the
# simulated sandbox.api.billerapi.com host has no hosted mint.
curl -X POST https://api.billerapi.com/v1/link-tokens \
  -H "Authorization: Bearer bak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "client_user_id": "user_42",
    "consents": ["bills"],
    "hosted": {},
    "redirect_uri": "https://yourapp.com/billerapi/callback"
  }'