Collect (Server-zu-Server)
Zwei Verifizierungswege
Das Guardian SDK bietet zwei Wege, Geräte zu verifizieren. Wählen Sie nach Ihrer Architektur:
verify() | collect() | |
|---|---|---|
| Wer Surt aufruft | Das SDK (vom Gerät aus) | Ihr Backend (Server-zu-Server) |
| JWT-Anforderung | Erforderlich, ein neues für jeden Aufruf | Optional |
| Ihr Backend beteiligt | Nein | Ja |
| Antwort | VerificationResult (erlaubt/abgelehnt) | CollectResult (verschlüsseltes Payload) |
| Am besten für | Einfache Integration, Frontend-gesteuerte Entscheidungen | Backend-gesteuerte Entscheidungen, eigene Logik, Audit-Anforderungen |
Ablauf von verify()
App → fetch fresh JWT from your backend → SDK.verify(jwt) → Surt backend → risk decision → App
Das SDK ruft Surt direkt auf und gibt allowed: true/false zurück. Ihre App handelt sofort nach der Entscheidung. Fordern Sie für jeden Aufruf ein neues JWT an.
Ablauf von collect()
App → SDK.collect() → encrypted payload → App → Your backend → Surt /evaluate → Your backend → App
Das SDK erfasst Gerätedaten und verschlüsselt sie auf dem Gerät. collect() sendet das Geräte-Payload nicht an Surt. Ihr Backend sendet das Payload an Surts Evaluate-Endpoint, erhält die Risikobewertung und entscheidet, was es an Ihre App zurückgibt.
Wann collect() verwenden
- Ihr Backend benötigt die Risikodaten, bevor es dem Client antwortet
- Sie möchten das Geräterisiko serverseitig mit Ihrer eigenen Geschäftslogik kombinieren
- Sie benötigen die volle Kontrolle darüber, was der Client sieht
Verwendung
1. Auf dem Gerät sammeln
import { useGuardian } from '@surtai/guardian-rn';
function PaymentScreen() {
const { collect } = useGuardian();
const handlePayment = async () => {
// The JWT is optional for collect(). Pass collect(jwt) to resolve the
// device's public IP into the payload and to apply your organization's
// attestation settings.
const { payload } = await collect();
// Send payload to YOUR backend
const response = await fetch('https://your-api.com/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
payload,
amount: 500,
currency: 'USD',
}),
});
const result = await response.json();
// Your backend already made the risk decision
};
}
Das JWT ist für collect() optional. Wenn Sie eines übergeben, nutzt das SDK es für zwei Dinge:
- Es ruft
GET /geolocation/client-ipauf und fügt die öffentliche IP des Geräts zum Payload hinzu. - Es wendet die Attestierungseinstellungen Ihrer Organisation an: wie oft ein Gerät attestiert und, unter Android, Ihr eigenes Play-Integrity-Projekt. Siehe Einrichtung der Geräte-Attestierung.
Ohne JWT enthält das Payload keine aufgelöste öffentliche IP, und das SDK attestiert bei jedem Aufruf mit den Standardeinstellungen. Fordern Sie für jede Transaktion ein neues JWT an. Ein JWT läuft 30 Minuten nach der Ausstellung ab.
2. Surt von Ihrem Backend aufrufen
Ihr Backend erhält das verschlüsselte Payload von der App und ruft dann Surts Evaluate-Endpoint auf:
POST https://api.surt.com/geolocation/transactions/evaluate
Content-Type: application/json
Authorization: Bearer YOUR_SURT_API_KEY
{
"customer_id": "user_123",
"transaction_type": "withdrawal",
"transaction_name": "User Payment",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+15555550100",
"event_id": "withdrawal-8841",
"payload": {
"type": "encrypted",
"data": "<payload from SDK>"
},
"config": {
"response": {
"address": { "type": "include" }
}
}
}
Anforderungsfelder
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
customer_id | string | Nein | Ihre Benutzerkennung. Lassen Sie das Feld weg oder senden Sie einen leeren String für eine anonyme Transaktion, zum Beispiel vor dem Login. |
transaction_type | string | Ja | login, sign_up, deposit, withdrawal oder ein eigener String mit bis zu 64 Zeichen. Siehe Transaktionstypen. |
transaction_name | string | Nein | Menschenlesbare Bezeichnung |
name | string | Nein | Der Name des Kunden |
email | string | Nein | Die E-Mail-Adresse des Kunden. Ein leerer String gilt als nicht vorhanden. Eine ungültige Adresse liefert 400. |
phone | string | Nein | Die Telefonnummer des Kunden. Ein leerer String gilt als nicht vorhanden. Eine Nummer, die sich nicht parsen lässt, liefert 400. |
event_id | string | Nein | Ihre ID für dieses Ereignis, eindeutig innerhalb Ihrer Organisation. 1 bis 128 Zeichen: Buchstaben, Ziffern, ., _, : und -. Siehe Idempotenz. |
payload.type | string | Ja | Immer "encrypted" |
payload.data | string | Ja | Das verschlüsselte Payload von collect() |
config.response.address | object | Nein | { "type": "include" }, um die vollständige Adresse zu erhalten, standardmäßig weggelassen |
Idempotenz
Senden Sie eine event_id, damit die Anfrage gefahrlos wiederholt werden kann. Surt wertet jede event_id einmal aus.
- Eine wiederholte Anfrage mit derselben
event_idliefert200mit der Antwort der ersten Auswertung. Surt bewertet das Ereignis nicht erneut. - Eine wiederholte Anfrage, die eintrifft, während die erste noch ausgewertet wird, liefert
409. Wiederholen Sie die Anfrage nach kurzer Wartezeit. - Schlägt die erste Auswertung fehl, gibt Surt die
event_idfrei, und eine Wiederholung wird als neue Anfrage ausgewertet.
Surt bewahrt eine event_id mindestens 24 Stunden auf. Ohne event_id erzeugt jede Anfrage eine neue Transaktion.
Config
Das config-Objekt steuert, welche optionalen Daten in der Antwort enthalten sind.
{
"config": {
"response": {
"address": { "type": "include" }
}
}
}
| Feld | Werte | Standard | Beschreibung |
|---|---|---|---|
config.response.address.type | "include" oder "omit" | "omit" | Ob die vollständige, per Reverse-Geocoding ermittelte Adresse (Straße, Stadt, Bundesland, Land, Postleitzahl) in der Antwort enthalten sein soll. Erfordert GPS-Daten im Payload. |
Wenn address weggelassen wird (Standard), hat die Antwort kein address-Feld, auch wenn Standortdaten erfasst wurden. Setzen Sie den Wert auf "include", wenn Ihr Backend die physische Adresse für Compliance, Betrugsprüfung oder Anzeige benötigt.
Authentifizierung
Verwenden Sie Ihren Surt-API-Schlüssel im Authorization-Header als Bearer-Token. Dies ist ein Server-zu-Server-Aufruf. Der API-Schlüssel erreicht das Gerät nie.
3. Antwort verarbeiten
Der Evaluate-Endpoint gibt die Transaktion mit ihrer Risikostufe und Entscheidung zurück. Das Beispiel zeigt die Felder, auf die Sie aufbauen können. Das transaction-Objekt enthält mehr Felder als diese, ignorieren Sie daher jedes Feld, das nicht in der Tabelle unten steht.
Mit config.response.address.type: "include"
{
"status_code": 200,
"message": "Transaction evaluated successfully",
"data": {
"transaction": {
"transaction_id": "1775514112-f2e3034b891e4c6a9d0b7a1c5e8f20",
"event_id": "withdrawal-8841",
"created_at": "2026-04-06T22:21:52Z",
"customer_id": "user_123",
"transaction_type": "withdrawal",
"transaction_name": "User Payment",
"risk_level": "low",
"status": "completed",
"details": {
"risk_level": "low",
"address": {
"street": "Main St",
"city": "San Francisco",
"state": "California",
"country": "United States",
"postal_code": "94103",
"formatted_address": "123 Main St, San Francisco, CA 94103, USA"
}
},
"result": {
"status": "accepted",
"review": false
},
"network_threat": {
"status": "clear"
},
"device": {
"device_id": "5b1f0c1e-8a43-5c0e-9d55-2f6c1d7a9b10",
"manufacturer": "Apple",
"model": "iPhone 15",
"os_version": "18.0"
}
}
}
}
Mit config.response.address.type: "omit" (Standard)
Dieselbe Antwort, aber details hat kein address-Feld:
"details": {
"risk_level": "low"
}
Antwortfelder
Alle Felder liegen in data.transaction.
| Feld | Typ | Vorhanden | Beschreibung |
|---|---|---|---|
transaction_id | string | Immer | Surts ID für die Transaktion |
event_id | string | Wenn Sie eine gesendet haben | Die event_id aus der Anfrage |
created_at | string | Immer | Erstellungszeit, ISO 8601 in UTC |
customer_id | string | Wenn Sie eine gesendet haben | Fehlt bei einer anonymen Transaktion |
transaction_type | string | Immer | Der Typ aus der Anfrage |
transaction_name | string | Wenn Sie einen gesendet haben | Die Bezeichnung aus der Anfrage |
risk_level | string | Immer | low, medium oder high. Siehe Risikostufen. |
status | string | Immer | completed, oder failed, wenn Surt die Transaktion nicht verarbeiten konnte |
details.risk_level | string | Wenn status completed ist | Derselbe Wert wie risk_level |
details.address | object | Wenn status completed ist, die Anfrage sie angefordert hat und eine Adresse ermittelt wurde | formatted_address (string, immer), dazu street, city, state, country und postal_code (strings, jeweils vorhanden, wenn bekannt) |
details.error | string | Wenn status failed ist | Warum die Verarbeitung fehlgeschlagen ist. risk_level ist in diesem Fall high. |
result.status | string | Immer | accepted oder rejected. Das ist die Entscheidung. |
result.review | boolean | Immer | true, wenn die Transaktion zur manuellen Prüfung markiert ist |
result.details | object | Wenn result.status rejected ist | Warum die Transaktion abgelehnt wurde. type ist scenarios (mit einem scenarios-Array von { scenario_id, scenario_name }), blacklisted, blocked (mit kind.type gleich deposits oder withdrawals) oder node_ids. |
network_threat.status | string | Immer | not_analyzed, clear oder detected |
network_threat.threats | string[] | Wenn network_threat.status detected ist | Beliebige aus vpn, proxy, tor |
device | object | Immer | device_id (string, immer), dazu manufacturer, model und os_version (strings, jeweils vorhanden, wenn bekannt) |
risk_level und result.status sind unabhängig voneinander: Eine Transaktion mit Risiko high kann accepted sein. Entscheiden Sie anhand von result.status, und nutzen Sie risk_level, result.review, network_threat und details.address für Ihre eigenen Regeln, bevor Sie dem Client antworten.
Fehler
| Code | Wann |
|---|---|
400 | Fehlerhaftes JSON, ein fehlendes Pflichtfeld, ein ungültiger Wert für email, phone, event_id oder transaction_type oder ein payload.data, das Surt nicht entschlüsseln kann |
401 | Die Anfrage hat keinen Authorization-Header |
403 | Der API-Schlüssel ist ungültig oder inaktiv, oder Guardian ist für Ihre Organisation nicht aktiviert |
409 | Eine andere Anfrage mit derselben event_id wird noch ausgewertet. Wiederholen Sie die Anfrage nach kurzer Wartezeit. |
503 | Vorübergehender Fehler. Wiederholen Sie die Anfrage. |
Die Antwort-Bodys finden Sie unter Fehlercodes.
Standortüberschreibung
Wie bei verify() können Sie die Standorterfassung pro Aufruf überschreiben:
// Collect with location
const { payload } = await collect(jwt, { collectLocation: true });
// Collect without location and without a JWT
const { payload } = await collect(undefined, { collectLocation: false });
Unter Android wirkt collectLocation: true bei einem Aufruf nur, wenn collectLocation auch bei der Initialisierung true war. Unter iOS aktiviert es den Standort für diesen Aufruf.
CollectResult
interface CollectResult {
/** Base64-encoded encrypted payload. Pass as payload.data in the evaluate request. */
payload: string;
}
Das Payload ist verschlüsselt und kann nur von Surts Backend entschlüsselt werden. Es enthält den Gerätefingerabdruck, Geräteintegritätssignale, Sicherheitssignale und optional den Standort.
Das collect()-Ergebnis enthält außerdem ein optionales diagnostics-Objekt, das beschreibt, was das SDK auf dem Gerät beobachtet hat. React Native gibt es ab v0.5.2 zurück. Sie können es ignorieren.
const { payload, diagnostics } = await collect();
// diagnostics?.location: 'collected' | 'denied' | 'unavailable' | 'timeout' | 'not_requested' | 'error'
// diagnostics?.attestation: 'collected' | 'unavailable' | 'failed' | 'not_supported' | 'not_requested'
// diagnostics?.networkIntel: 'collected' | 'unavailable' | 'not_requested'
// diagnostics?.warnings: { code, signal, detail? }[]
// diagnostics?.timings: { [phase]: ms } (Android; iOS from v0.5.3)
Siehe Fehlercodes → Ergebnis-Diagnose.
Backend-Beispiel
- Node.js
- Java
- Python
app.post('/verify-device', async (req, res) => {
const { payload, userId } = req.body;
const surtResponse = await fetch(
'https://api.surt.com/geolocation/transactions/evaluate',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.SURT_API_KEY}`,
},
body: JSON.stringify({
customer_id: userId,
transaction_type: 'login',
payload: { type: 'encrypted', data: payload },
config: { response: { address: { type: 'include' } } },
}),
}
);
if (!surtResponse.ok) {
return res.status(502).json({ allowed: false });
}
const { data } = await surtResponse.json();
const risk = data.transaction.risk_level;
const accepted = data.transaction.result.status === 'accepted';
res.json({ allowed: accepted, risk });
});
@PostMapping("/verify-device")
public ResponseEntity<Map<String, Object>> verifyDevice(@RequestBody Map<String, Object> body) {
String payload = (String) body.get("payload");
String userId = (String) body.get("userId");
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.set("Authorization", "Bearer " + System.getenv("SURT_API_KEY"));
Map<String, Object> request = Map.of(
"customer_id", userId,
"transaction_type", "login",
"payload", Map.of("type", "encrypted", "data", payload),
"config", Map.of("response", Map.of("address", Map.of("type", "include")))
);
ResponseEntity<Map> response = restTemplate.exchange(
"https://api.surt.com/geolocation/transactions/evaluate",
HttpMethod.POST,
new HttpEntity<>(request, headers),
Map.class
);
Map data = (Map) response.getBody().get("data");
Map transaction = (Map) data.get("transaction");
String risk = (String) transaction.get("risk_level");
Map result = (Map) transaction.get("result");
boolean accepted = "accepted".equals(result.get("status"));
return ResponseEntity.ok(Map.of("allowed", accepted, "risk", risk));
}
@app.post("/verify-device")
async def verify_device(request: Request):
body = await request.json()
surt_response = requests.post(
"https://api.surt.com/geolocation/transactions/evaluate",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['SURT_API_KEY']}",
},
json={
"customer_id": body["userId"],
"transaction_type": "login",
"payload": {"type": "encrypted", "data": body["payload"]},
"config": {"response": {"address": {"type": "include"}}},
},
)
surt_response.raise_for_status()
data = surt_response.json()["data"]
risk = data["transaction"]["risk_level"]
accepted = data["transaction"]["result"]["status"] == "accepted"
return {"allowed": accepted, "risk": risk}