Location

The Location step in HYPR Affirm checks where the requester is. Affirm asks the browser for the requester's location, reads the IP address of the connection and compares the result with the address on file and with the location policy configured on the step. The step is disabled by default. Enable it for verification flows that need a location signal in the decision.

Prerequisites

• Address on file: The requester's directory record must hold Street Address, City, State, Postal Code and Country Code. Affirm measures distances to this address. See Identity Provider Prerequisites.
• Policy controls: The Known Locations, IP list, Distance Threshold and Country Block List controls appear when network and location policy controls are enabled for your tenant.

Configure the Step

The step card reads Requester's geolocation will be collected and compared to the address we have on file. The following table lists its settings.

Setting	What It Does	Allowed Values	Default
Known Locations	Adds locations from Advanced Settings > Location Settings as places the requester may be near, in addition to the address on file	Any saved known locations	None selected
IP Address Block List	Fails the step when the requester's IP address matches a rule	IPv4 or IPv6 rules, each with an optional description	Cleared
IP Address Allow List	Lists trusted IP address rules; while it is enabled, the IP addresses of selected known locations are added to it	IPv4 or IPv6 rules, each with an optional description	Cleared
Strict Enforcement	Under the allow list; fails the step when the IP address matches no allow-list rule	Checkbox	Cleared
Distance Threshold	Fails the step when the requester is this far or farther from the nearest expected location	0 to 20,000,000 meters, entered in miles, kilometers or meters; 0 turns the check off	Cleared
Country Block List	Fails the step when the requester's country is on the selected list	Any list from Location Settings, or - (No Country Block List) -	No list
Retry Limit	Number of failed attempts allowed before the failure outcome applies	1 to 10 attempts, within 0 to 60 minutes in 5-minute steps	3 attempts within 0 minutes
Failure Outcome	What happens when the retry limit is reached	Deny Verification, Redirect to URL or Continue Workflow (optionally with Escalate to Live Chat)	Continue Workflow

For rule formats and list management, see Network and Location Policy.

When your tenant uses the Affirm Risk Policy Builder, the Policy Evaluation Kit assigned to the flow sets retries and failure outcomes instead of the Retry Limit and Failure Outcome controls.

What the Requester Sees

The Location screen starts the check as soon as it loads.

1. Affirm shows Checking your location and asks the browser for the device location. The browser displays its own permission prompt the first time a site asks; its wording comes from the browser.
2. If the requester allows location access, Affirm shows Verifying your location while it evaluates the location.
3. If the step passes, Affirm shows Location verified with the approximate address it determined. The requester clicks Next.
4. If the browser cannot share a location, Affirm shows Unable to access your location with Proceed with IP location and Retry check. Proceed with IP location continues with the IP address only.
5. If the step fails, Affirm shows Unable to verify your location with the same two buttons while retries remain. When the retry limit is reached, the step's failure outcome applies; see Results, Retries and Failure Outcomes.

The following table lists the default text for each state. Administrators can change this text in Affirm Studio.

State	Title	Message	Buttons
Asking for location	"Checking your location"	"Please accept sharing your location, so we can verify you are coming from a trusted area."	None
Evaluating	"Verifying your location"	"Please wait while we verify your location."	None
Passed	"Location verified"	The determined address, then "Your location has been verified. Please proceed with your verification process by clicking Next."	Next
No location from the browser	"Unable to access your location"	"You may proceed without granting location access but it may impact our ability to successfully verify your identity."	Proceed with IP location, Retry check
Failed	"Unable to verify your location"	"You can re-attempt verification or skip this check. Skipping the location check may impact our ability to successfully verify your identity."	Proceed with IP location, Retry check

The screen footer shows a caption in two cases:

• When the requester has blocked location access, Retry check is disabled and the footer reads "Location access is required. Enable it in your browser settings to continue with verification." When the requester changes the browser permission, the check restarts automatically.
• When the browser does not answer in time, the footer reads "Location request timed out. Please try again."

What Data Is Collected

The Location step uses two sources of location data:

• Browser location: the latitude and longitude the browser reports, only when the requester allows location access. Affirm requests standard accuracy (not the browser's high-accuracy mode), accepts a position the browser cached within the last 30 seconds and waits up to 27 seconds for an answer.
• IP address: the IP address of the requester's connection, read on every attempt.

Affirm resolves the browser coordinates to an approximate address (locality, postal code and region) and a country, and the IP address to an approximate location. Affirm then measures the distance from each position to the address on file and to any selected known locations. It uses the route distance when a route exists and the straight-line distance otherwise.

The verification record keeps the determined addresses, the distances, the result of each check and any IP rule that matched. Approvers see the results on the scorecard: Determined location, Distance from expected location, IP address allowed, Within distance threshold, Country allowed and an overall Passed or Failed status.

Results, Retries and Failure Outcomes

How the Step Passes or Fails

The step passes when every configured check passes: the Country Block List, the IP Address Block List, the IP Address Allow List with Strict Enforcement and the Distance Threshold. Affirm must also resolve an address and a distance from the browser location or from the IP address. A check that is not configured does not affect the result, so without any of the policy controls the step passes whenever Affirm can resolve an address and a distance to the address on file. If the assigned Country Block List can no longer be found, the country check fails.

For the rule each check applies, how known locations count, and the order in which Affirm records failures, see Order of Precedence in Network and Location Policy.

Retries and Failure Outcomes

Each failed evaluation counts as one attempt; Affirm counts attempts separately for each failure reason, such as missing location data, a blocked country, a blocked IP address or the distance threshold. While attempts remain, the requester can click Retry check or Proceed with IP location. When the requester reaches the Retry Limit, the Failure Outcome applies.

This step's defaults are 3 attempts and Continue Workflow. With Continue Workflow, the Verification Unsuccessful screen reads "We are unable to verify your location. You will be taken to the next step momentarily." For what each failure outcome does, including the redirect and escalation to live chat, see Injectable Outcomes and Retry Limits.

Related

• Network and Location Policy: rule formats, known locations and country block lists
• Configure Verification Steps: table of all verification steps
• Injectable Outcomes and Retry Limits: retry and failure-outcome configuration