Verificar transacciones
Llama a verify() en momentos sensibles para la seguridad. El SDK recopila señales del dispositivo, ejecuta verificaciones de integridad del dispositivo y devuelve la decisión de riesgo del backend.
verify() requiere un JWT que genera tu backend. El SDK nunca maneja una clave de API de Surt. Tu backend tiene la clave sp_live_* (solo del lado del servidor) y la intercambia por un JWT que expira después de 30 minutos.
Uso básico
Primero, obtén un JWT nuevo desde tu propio backend y luego pásalo a verify():
import { useGuardian } from '@surtai/guardian-rn';
// Your backend calls Surt's POST /geolocation/preflight with the
// sp_live_* API key and returns the minted JWT to the client.
async function fetchVerifyJwt(): Promise<string> {
const res = await fetch('https://your-api.com/guardian/jwt', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
transaction_type: 'withdrawal',
transaction_name: 'User Payment',
}),
});
const { token } = await res.json();
return token;
}
function PaymentScreen() {
const { verify } = useGuardian();
const handlePayment = async () => {
try {
const jwt = await fetchVerifyJwt();
const result = await verify(jwt);
if (result.allowed) {
// Proceed with payment
} else {
// Transaction denied - check result.riskLevel
}
} catch (error) {
// Handle SDK error (network, not initialized). See Error Codes.
}
};
return <Button onPress={handlePayment} title="Pay" />;
}
Solicita un JWT nuevo justo antes de cada llamada a verify(). Un JWT expira 30 minutos después de emitirse.
Diagnósticos del resultado
A partir de v0.5.2 el resultado de verify() incluye un objeto opcional diagnostics que describe lo que el SDK observó durante la transacción. Puedes ignorarlo.
const result = await verify(jwt);
if (result.diagnostics?.location === 'denied') {
// prompt the user to enable location
}
diagnostics.location es collected · denied · unavailable · timeout · not_requested · error; diagnostics.attestation es collected · failed · unavailable · not_supported · not_requested; diagnostics.networkIntel es collected · unavailable · not_requested; diagnostics.warnings es un arreglo de { code, signal, detail? }; diagnostics.timings (solo Android) son los milisegundos por fase más total. Consulta Códigos de error → Diagnósticos del resultado para conocer el significado de cada valor y los códigos de advertencia.
De dónde provienen el contexto de cliente y de transacción
El cliente no pasa un cliente ni un tipo de transacción a verify(). Tu backend establece este contexto al generar el JWT.
Cuando tu backend llama a POST /geolocation/preflight, incluye transaction_type y, opcionalmente, customer_id, transaction_name, name, email y phone. Esos valores quedan incorporados en el JWT, por lo que el cliente solo necesita pasar el token:
const jwt = await fetchVerifyJwt(); // backend set customer + transaction context
const result = await verify(jwt);
Tipos de transacción
Estos valores los envía tu backend en el campo transaction_type del preflight. No se pasan a verify() en el cliente.
| Tipo | Caso de uso |
|---|---|
login | Inicio de sesión del usuario |
sign_up | Creación de una cuenta nueva |
deposit | Agregar fondos |
withdrawal | Retirar fondos |
| Cualquier otra cadena | Un tipo personalizado que tú defines, de hasta 64 caracteres |
Consulta Tipos de transacción.
Anulación de ubicación por llamada
Anula el valor predeterminado de collectLocation para una sola llamada:
// Skip location for this call
const result = await verify(jwt, { collectLocation: false });
// Request location for this call
const result = await verify(jwt, { collectLocation: true });
// Use init default
const result = await verify(jwt);
La anulación es de un solo uso. Solo afecta esa única llamada a verify().
Cómo se decide la recopilación de ubicación
La recopilación de ubicación tiene dos niveles de control, que se evalúan en conjunto. Ambos deben coincidir para que se recopilen datos GPS:
1. Panel de Surt: GPS habilitado (máxima prioridad)
La recopilación GPS debe estar habilitada en tu panel de cliente de Surt. Si el GPS está deshabilitado en el panel, la ubicación nunca se recopila, sin importar lo que configures en el código. Habilítalo en Settings > Developer o contacta a tu gerente de cuenta de Surt.
2. Configuración del lado del cliente (tu código)
Se resuelve así: anulación por llamada > valor predeterminado de la inicialización.
- Si pasas
{ collectLocation: true }averify(), eso prevalece sobre el valor de la inicialización en iOS. En Android solo tiene efecto cuandocollectLocationtambién eratrueen la inicialización. - Si pasas
{ collectLocation: false }averify(), se omite el GPS aunque la inicialización fueratrue. - Si lo omites, se usa el valor predeterminado de la inicialización de
GuardianProvider/initialize().
En la práctica, esto significa:
| GPS en el panel | Tu código dice | Resultado |
|---|---|---|
| habilitado | true (inicialización o anulación) | GPS recopilado |
| habilitado | false (inicialización o anulación) | Sin GPS: lo desactivaste |
| deshabilitado | true (inicialización o anulación) | Sin GPS: el panel lo tiene desactivado |
| deshabilitado | false (inicialización o anulación) | Sin GPS |
Tu configuración collectLocation del lado del cliente solo puede desactivar la recopilación de ubicación. No puede forzar la recopilación GPS si el panel la tiene deshabilitada. Para habilitar la recopilación GPS, actívala primero en tu panel de cliente de Surt y luego establece collectLocation: true en tu código.
En Android el SDK no espera la respuesta del usuario al diálogo de permiso, por lo que la llamada que muestra el diálogo no lleva ubicación. La ubicación se incluye a partir de la siguiente llamada. Android reporta la última ubicación conocida del dispositivo y no solicita una posición nueva.
Resultado de la verificación
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
diagnostics?: GuardianDiagnostics; // What the SDK observed (v0.5.2+)
}
Para los detalles de los niveles de riesgo, consulta Niveles de riesgo.
Ejemplo completo
import React, { useState } from 'react';
import { View, Button, Text, Alert } from 'react-native';
import {
GuardianProvider,
useGuardian,
type VerificationResult,
} from '@surtai/guardian-rn';
// Your backend calls Surt's POST /geolocation/preflight with the
// sp_live_* API key and returns the minted JWT to the client.
async function fetchVerifyJwt(): Promise<string> {
const res = await fetch('https://your-api.com/guardian/jwt', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
transaction_type: 'login',
transaction_name: 'User Login',
}),
});
const { token } = await res.json();
return token;
}
function HomeScreen() {
const { verify, collect, isInitialized } = useGuardian();
const [result, setResult] = useState<VerificationResult | null>(null);
const handleLogin = async () => {
try {
const jwt = await fetchVerifyJwt();
const res = await verify(jwt);
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} />
{result && <Text>Allowed: {result.allowed ? 'Yes' : 'No'}</Text>}
</View>
);
}
export default function App() {
return (
<GuardianProvider collectLocation={true}>
<HomeScreen />
</GuardianProvider>
);
}