Collect (Server-to-Server)
Two Verification Paths
Guardian SDK offers two ways to verify devices. Choose based on your architecture:
verify() | collect() | |
|---|---|---|
| Who calls Surt | The SDK (from the device) | Your backend (server-to-server) |
| JWT requirement | Required, a new one for each call | Optional |
| Your backend involved | No | Yes |
| Response | VerificationResult (allowed/denied) | CollectResult (encrypted payload) |
| Best for | Simple integration, frontend-driven decisions | Backend-driven decisions, custom logic, audit requirements |
verify() flow
App → fetch fresh JWT from your backend → SDK.verify(jwt) → Surt backend → risk decision → App
The SDK calls Surt directly and returns allowed: true/false. Your app acts on the decision immediately. Request a new JWT for each call.
collect() flow
App → SDK.collect() → encrypted payload → App → Your backend → Surt /evaluate → Your backend → App
The SDK collects device data and encrypts it on the device. collect() does not send the device payload to Surt. Your backend sends the payload to Surt's evaluate endpoint, receives the risk assessment, and decides what to return to your app.
When to Use collect()
- Your backend needs the risk data before responding to the client
- You want to combine device risk with your own business logic server-side
- You need full control over what the client sees
Usage
1. Collect on the device
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
};
}
The JWT is optional for collect(). When you pass one, the SDK does two things with it:
- It calls
GET /geolocation/client-ipand adds the device's public IP to the payload. - It applies your organization's attestation settings: how often a device attests and, on Android, your own Play Integrity project. See Device attestation setup.
Without a JWT, the payload carries no resolved public IP and the SDK attests on every call with the default settings. Request a new JWT for each transaction. A JWT expires 30 minutes after it is issued.
2. Call Surt from your backend
Your backend receives the encrypted payload from the app, then calls Surt's evaluate endpoint:
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" }
}
}
}
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | string | No | Your user identifier. Omit it, or send an empty string, for an anonymous transaction, for example before login. |
transaction_type | string | Yes | login, sign_up, deposit, withdrawal, or a custom string of up to 64 characters. See Transaction Types. |
transaction_name | string | No | Human-readable label |
name | string | No | The customer's name |
email | string | No | The customer's email. An empty string counts as absent. An invalid address returns 400. |
phone | string | No | The customer's phone number. An empty string counts as absent. A number that cannot be parsed returns 400. |
event_id | string | No | Your ID for this event, unique within your organization. 1 to 128 characters: letters, digits, ., _, : and -. See Idempotency. |
payload.type | string | Yes | Always "encrypted" |
payload.data | string | Yes | The encrypted payload from collect() |
config.response.address | object | No | { "type": "include" } to get the full address, omitted by default |
Idempotency
Send an event_id to make the request safe to retry. Surt evaluates each event_id once.
- A repeated request with the same
event_idreturns200with the response of the first evaluation. Surt does not score the event again. - A repeated request that arrives while the first one is still being evaluated returns
409. Retry after a short wait. - If the first evaluation fails, Surt releases the
event_idand a retry is evaluated as a new request.
Surt keeps an event_id for at least 24 hours. Without an event_id, every request creates a new transaction.
Config
The config object controls what optional data is included in the response.
{
"config": {
"response": {
"address": { "type": "include" }
}
}
}
| Field | Values | Default | Description |
|---|---|---|---|
config.response.address.type | "include" or "omit" | "omit" | Whether to include the full reverse-geocoded address (street, city, state, country, postal code) in the response. Requires GPS data in the payload. |
When address is omitted (default), the response has no address field, even if location data was collected. Set it to "include" if your backend needs the physical address for compliance, fraud review, or display.
Authentication
Use your Surt API key in the Authorization header as a Bearer token. This is a server-to-server call. The API key never reaches the device.
3. Handle the response
The evaluate endpoint returns the transaction with its risk level and decision. The example shows the fields to build on. The transaction object carries more fields than these, so ignore any field that is not in the table below.
With 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"
}
}
}
}
With config.response.address.type: "omit" (default)
Same response, but details has no address field:
"details": {
"risk_level": "low"
}
Response fields
All fields are inside data.transaction.
| Field | Type | Present | Description |
|---|---|---|---|
transaction_id | string | Always | Surt's ID for the transaction |
event_id | string | When you sent one | The event_id from the request |
created_at | string | Always | Creation time, ISO 8601 in UTC |
customer_id | string | When you sent one | Absent for an anonymous transaction |
transaction_type | string | Always | The type from the request |
transaction_name | string | When you sent one | The label from the request |
risk_level | string | Always | low, medium, or high. See Risk Levels. |
status | string | Always | completed, or failed when Surt could not process the transaction |
details.risk_level | string | When status is completed | Same value as risk_level |
details.address | object | When status is completed, the request asked for it, and an address was resolved | formatted_address (string, always), plus street, city, state, country and postal_code (strings, each present when known) |
details.error | string | When status is failed | Why processing failed. risk_level is high in this case. |
result.status | string | Always | accepted or rejected. This is the decision. |
result.review | boolean | Always | true when the transaction is flagged for manual review |
result.details | object | When result.status is rejected | Why the transaction was rejected. type is scenarios (with a scenarios array of { scenario_id, scenario_name }), blacklisted, blocked (with kind.type set to deposits or withdrawals), or node_ids. |
network_threat.status | string | Always | not_analyzed, clear, or detected |
network_threat.threats | string[] | When network_threat.status is detected | Any of vpn, proxy, tor |
device | object | Always | device_id (string, always), plus manufacturer, model and os_version (strings, each present when known) |
risk_level and result.status are independent: a high risk transaction can be accepted. Decide on result.status, and use risk_level, result.review, network_threat, and details.address for your own rules before responding to the client.
Errors
| Code | When |
|---|---|
400 | Malformed JSON, a missing required field, an invalid email, phone, event_id or transaction_type, or a payload.data that Surt cannot decrypt |
401 | The request has no Authorization header |
403 | The API key is invalid or inactive, or Guardian is not enabled for your organization |
409 | Another request with the same event_id is still being evaluated. Retry after a short wait. |
503 | Temporary failure. Retry the request. |
See Error Codes for the response bodies.
Location Override
Same as verify(), you can override location collection per call:
// Collect with location
const { payload } = await collect(jwt, { collectLocation: true });
// Collect without location and without a JWT
const { payload } = await collect(undefined, { collectLocation: false });
On Android, collectLocation: true on a call has an effect only when collectLocation was also true at initialization. On iOS it enables location for that call.
CollectResult
interface CollectResult {
/** Base64-encoded encrypted payload. Pass as payload.data in the evaluate request. */
payload: string;
}
The payload is encrypted and can only be decrypted by Surt's backend. It contains the device fingerprint, device integrity signals, security signals, and optionally location.
The collect() result also includes an optional diagnostics object that describes what the SDK observed on the device. React Native returns it from v0.5.2. You can ignore it.
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)
See Error Codes → Result diagnostics.
Backend Example
- 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}