Skip to main content

ProximityVerifyRequest

customer_idstringrequired

Unique customer identifier from the bank's system. Feeds velocity & impossible-travel checks.

Example: CUST-001
device_idstring

Optional device hardware identity (IMEI hash or advertising ID). Strongly recommended — enables device-velocity and device-impossible-travel signals.

Example: iphone_uuid_1234
consent_tokenstringrequired

Unique per request. Replay-protected via SHA-256 hash + DB unique index per (token_hash, customer_id).

Example: ct_8f3a2b9c
declared_addressstringrequired

The GhanaPostGPS code the customer claims (e.g. AK-484-9321).

Example: GK-0846-6875
device_location objectrequired

Device's reported GPS state. Optional fields feed the integrity rubric — when absent, the corresponding integrity check yields NOT_PROVIDED. gps_accuracy_m is the single most load-bearing optional field; without it the confidence ceiling drops to 0.85, and a value > 100m hard-caps the score at 0.60.

latnumber<double>required
Example: 5.780952815725535
lngnumber<double>required
Example: -0.1137042570848795
gps_accuracy_mnumber<double>

From location.accuracy (Android) / horizontalAccuracy (iOS).

Example: 8.5
altitude_mnumber<double>

Spoofing apps frequently report exactly 0.0 — real devices almost never do.

Example: 42
speed_mpsnumber<double>

Should be ~0 if "at home". > 10 mps marks SUSPICIOUS.

Example: 0
bearing_degnumber<double>nullable
location_providerstring

Hardware (gps/fused) earns +0.03 in the rubric; network/passive does not.

Possible values: [gps, fused, network, passive]

Example: gps
is_mock_locationboolean

Android isMockProvider. iOS does not expose this — omit on iOS.

Example: false
location_age_msinteger<int64>

How stale the GPS fix is. Fresh < 5000 ms.

Example: 1200
device_signals object

Non-location device context. IP for the IP-geo integrity check is taken from the request socket (server-side), never from the client.

timezonestring
Example: Africa/Accra
ProximityVerifyRequest
{
  "customer_id": "CUST-001",
  "device_id": "iphone_uuid_1234",
  "consent_token": "ct_8f3a2b9c",
  "declared_address": "GK-0846-6875",
  "device_location": {
    "lat": 5.780952815725535,
    "lng": -0.1137042570848795,
    "gps_accuracy_m": 8.5,
    "altitude_m": 42,
    "speed_mps": 0,
    "bearing_deg": 0,
    "location_provider": "gps",
    "is_mock_location": false,
    "location_age_ms": 1200
  },
  "device_signals": {
    "timezone": "Africa/Accra"
  }
}