Verify Transactions

Call verify() at security-sensitive moments. The SDK collects device signals, performs attestation, and returns the backend's risk decision.

Basic Usage

PaymentScreen.tsx

import { useGuardian } from '@surtai/guardian-rn';

function PaymentScreen() {
  const { verify } = useGuardian();

  const handlePayment = async () => {
    try {
      const result = await verify('withdrawal', 'User Payment');

      if (result.allowed) {
        // Proceed with payment
      } else {
        // Transaction denied - check result.riskLevel
      }
    } catch (error) {
      // Handle SDK error (network, not initialized, etc.)
    }
  };

  return <Button onPress={handlePayment} title="Pay" />;
}

Customer Context

Set the customer context after your app's authentication. This links device signals to a user identity.

const { setCustomer, clearCustomer } = useGuardian();

// After login
setCustomer('user_abc123', 'John Doe', 'john@example.com');

// On logout
clearCustomer();

Transaction Types

Type	Use case
'login'	User login
'signUp'	New account creation
'deposit'	Adding funds
'withdrawal'	Withdrawing funds

Per-Call Location Override

Override the collectLocation default for a single call:

// Skip location for this call
const result = await verify('login', 'User Login', { collectLocation: false });

// Request location for this call
const result = await verify('withdrawal', 'User Payment', { collectLocation: true });

// Use init default
const result = await verify('login', 'User Login');

The override is one-shot. It only affects that single verify() call.

How Location Collection Is Decided

Location collection has two levels of control, evaluated together. Both must agree for GPS data to be collected:

1. Surt Dashboard: GPS enabled (highest priority)

GPS collection must be enabled in your Surt client panel. If GPS is disabled in the dashboard, location is never collected regardless of what you set in code. Enable it in Settings > Developer or contact your Surt account manager.

2. Client-side setting (your code)

This is resolved as: per-call override > init default.

• If you pass { collectLocation: true } to verify(), that wins over the init value.
• If you pass { collectLocation: false } to verify(), GPS is skipped even if init was true.
• If you omit it, the init default from GuardianProvider / initialize() is used.

In practice, this means:

Dashboard GPS	Your code says	Result
enabled	true (init or override)	GPS collected
enabled	false (init or override)	No GPS: you opted out
disabled	true (init or override)	No GPS: dashboard has it off
disabled	false (init or override)	No GPS

Key takeaway

Your client-side collectLocation setting can only opt out of location collection. It cannot force GPS collection if the dashboard has it disabled. To enable GPS collection, turn it on in your Surt client panel first, then set collectLocation: true in your code.

Verification Result

interface VerificationResult {
  allowed: boolean;               // Backend decision - true = proceed
  riskLevel: RiskLevel;           // 'low' | 'medium' | 'high' | 'blocked' | 'unknown'
  sessionId: string;              // Transaction ID for support reference
  errors?: string[];              // Backend error messages, if any
  timestamp: number;              // Response timestamp (ms)
  metadata?: Record<string, any>; // Additional backend metadata
}

For risk level details, see Risk Levels.

Full Example

App.tsx

import React, { useState } from 'react';
import { View, Button, Text, Alert } from 'react-native';
import {
  GuardianProvider,
  useGuardian,
  type VerificationResult,
} from '@surtai/guardian-rn';

function HomeScreen() {
  const { verify, setCustomer, clearCustomer, isInitialized } = useGuardian();
  const [result, setResult] = useState<VerificationResult | null>(null);

  const handleLogin = async () => {
    setCustomer('user_123', 'Jane Doe', 'jane@example.com');

    try {
      const res = await verify('login', 'User Login');
      setResult(res);
      Alert.alert(res.allowed ? 'Approved' : 'Denied', `Risk: ${res.riskLevel}`);
    } catch (e: any) {
      Alert.alert('Error', e.message);
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>SDK Ready: {isInitialized ? 'Yes' : 'No'}</Text>
      <Button title="Login & Verify" onPress={handleLogin} />
      <Button title="Logout" onPress={() => { clearCustomer(); setResult(null); }} />
      {result && <Text>Allowed: {result.allowed ? 'Yes' : 'No'}</Text>}
    </View>
  );
}

export default function App() {
  return (
    <GuardianProvider apiKey="YOUR_API_KEY" environment="production" collectLocation={true}>
      <HomeScreen />
    </GuardianProvider>
  );
}