Geocompliance
Geocompliance enforces geographic restrictions on money movement using spatial geofencing. When an account has the geo_compliance capability, frameOS evaluates the account holder's location at transaction time and blocks charges that originate from restricted territories — automatically, with no additional integration required beyond your existing Frame.js or mobile SDK setup.
Geocompliance is a background service. There is no hosted onboarding step for the account holder to complete — location is captured continuously via Frame Sonar and evaluated at the moment a charge is initiated.
Geocompliance requires Frame.js or the Frame iOS or Android SDK to be initialized in your client. Location data is captured through Frame Sonar — without a valid Sonar session, transactions cannot be evaluated and will be blocked.
How it works
Location capture
When Frame.js or the mobile SDK is initialized, Frame Sonar runs in the background to capture the account holder's location. This happens automatically — no additional configuration is required. Location data is attached to a Sonar session and linked to the account.
If a VPN is detected during onboarding, the account holder is shown an inline warning. VPN detection does not block account creation, but a VPN-detected session is flagged and factored into transaction evaluation.
Transaction enforcement
When a charge is initiated for an account with the geo_compliance capability, frameOS evaluates the account's most recent Sonar session against your configured geofence rules. If the account holder's location falls within a restricted territory, the charge is blocked before it reaches the network.
If no Sonar session is available when a charge is attempted, the transaction is blocked until a valid session exists.
Evaluation outcomes
| Status | Description |
|---|---|
| clear | Location is not within any restricted territory — charge proceeds |
| blocked | Location is within a restricted territory — charge is rejected |
| unknown | No location data available — charge is blocked |
Block reasons
| Reason | Description |
|---|---|
| restricted_territory | Account holder's location falls within a geofenced region |
| vpn_detected | A VPN was detected on the account holder's session |
| no_location_data | No Sonar session or location data available |
Geofences
Geofences define the geographic boundaries where restrictions apply. frameOS provides a set of predefined platform-level geofences for common regulatory use cases — including prohibited states for gaming and other regulated industries — which apply automatically to all accounts with the geo_compliance capability.
Geofences support two shapes — polygon for state or regional boundaries, and circle for radius-based restrictions. Each geofence has one or more rules that define what happens when a location event is triggered.
Geofence rules
| Trigger | Action | Description |
|---|---|---|
| enter | block_transaction | Block charges when the account holder enters the geofenced area |
| exit | block_transaction | Block charges when the account holder leaves the geofenced area |
| dwell | block_transaction | Block charges after the account holder has been within the area for a set duration |
Enabling geocompliance
Geocompliance must be enabled for your platform before it can be requested as a capability on accounts. Contact your Frame account manager or reach out to sales to have geocompliance enabled.
Once enabled, add geo_compliance to the capabilities array when creating an account.
curl --request POST \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "individual",
"capabilities": ["geo_compliance"],
"profile": {
"individual": {
"email": "marcia@example.com",
"name": {
"first_name": "Marcia",
"last_name": "Longo"
},
"phone": {
"number": "3107484186",
"country_code": "1"
}
}
}
}'
Requesting geo_compliance on an account before geocompliance has been enabled for your platform will return a 422 geo_compliance_not_enabled error.
List geofences
Returns all active geofences for your platform, including Frame's predefined platform-level geofences and any custom geofences configured for your account.
Parameters
No parameters.
Returns
A dictionary with a data property containing an array of geofence objects. Returns a 422 error if geocompliance is not enabled for your platform.
curl --request GET \
--url https://api.framepayments.com/v1/geofences \
--header 'Authorization: Bearer API_KEY'
{
"data": [
{
"id": "geo_abc123",
"object": "geofence",
"name": "California",
"geofence_type": "polygon",
"active": true,
"geofence_rules": [
{
"trigger_on": "enter",
"action_type": "block_transaction"
}
]
}
]
}
Get account compliance status
Evaluates the account's most recent Sonar session and returns the current geocompliance status. Use this endpoint to check whether an account holder is currently in a restricted territory before initiating a transaction.
Parameters
No parameters.
Returns
Returns the current geocompliance status for the account, including the block reason and matched geofence if applicable.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/99c6b0da-2570-42a7-838a-5eaa318b07df/geo_compliance \
--header 'Authorization: Bearer API_KEY'
{
"status": "blocked",
"reason": "restricted_territory",
"geofence": {
"id": "geo_abc123",
"name": "California"
},
"sonar_session_id": "son_xyz789",
"evaluated_at": 1740614400
}
Charge intent errors
When a charge is blocked by geocompliance, the charge intent creation returns an error. The error code indicates the reason for the block.
| Error code | Description |
|---|---|
| geo_compliance_blocked | Account holder's location is within a restricted territory |
| geo_compliance_vpn_detected | A VPN was detected on the account holder's session |
| sonar_session_required | No Sonar session is available for the account |