Geolocation and Access Restrictions

Vivamo can restrict transactions based on the customer's physical location. When enabled, every client-authenticated request (payments and disbursements) is checked against your operator's location rules before the transaction is authorized.

How it works

When a customer initiates a transaction through the SDK, Vivamo resolves their IP address to a geographic location (country and state/region). This location is checked against the rules configured for your operator:

1. Country check — Is the customer in an allowed country?
2. State check — If the country has state-level restrictions, is the customer in an allowed state?

If the IP lookup fails, Vivamo falls back to other methods to establish the customer's location. The SDK may ask the customer to share their location to finish the check, and fires the location-required event when it does.

If the check fails, the request is denied with a 403 before it reaches the transaction handler.

Location rules

Vivamo maintains a platform-wide set of location rules that defines where transactions are allowed. Every location is blocked by default, so a country with no platform-wide rule is denied for every operator.

Rules operate at two levels:

• Country level — Allow transactions from specific countries (ISO 3166-1 alpha-2 codes, e.g. US, CA).
• State level — Within an allowed country, optionally restrict to specific states or regions (ISO 3166-2 codes, e.g. NY, CA, TX). If no state restrictions are set for a country, all states within that country are allowed.

Your operator can also have its own location rules, configured during onboarding. Operator rules can only narrow the platform-wide rules, never widen them:

• An operator rule can limit a country to fewer states than the platform-wide rule allows.
• An operator rule cannot open a country, or a state, that the platform-wide rule doesn't allow.
• Where the platform-wide rule and your operator rule both list states, only the states on both lists are allowed.

Sandbox behavior

In non-production environments, geolocation checks are relaxed. A request whose IP address can't be determined (common during local development) isn't refused for that reason alone.

In production, a request that arrives with no IP address is denied. If the IP address is there but Vivamo can't look it up, the SDK falls back to other methods to establish the customer's location. Check Geolocation has no fallback and returns a 400 (see Pre-checking customer location).

VPN and proxy detection

A VPN or proxy places the customer at its exit node rather than where they are. Vivamo checks the connection for VPNs, proxies, Tor and data-centre addresses, and a customer connecting through one of these can be refused with the reason anonymised_connection.

Pre-checking customer location

Use the /v1/operators/check-geolocation endpoint to verify a customer's IP address against your location rules before presenting payment UI. This avoids the poor experience where a customer fills out a form only to be denied at transaction time.

The response includes:

• allowed: whether the IP is in an allowed location for your operator.
• reason: why the check passed or failed, for example location_allowed, location_not_permitted (the country or state isn't allowed) or location_unconfirmed (Vivamo couldn't confirm the location). The API reference lists every value.
• flags: connection checks that matched the IP, if any.
• checkId: the ID of the recorded check. Quote it if you contact support about a result.
• country, countryCode, state and stateCode: the location the IP resolved to.

If allowed is false, the customer will usually be refused with a 403 when they try to transact.

The check fails closed. An IP in a country with no location rule returns allowed: false, whatever rules your operator has. Earlier versions of this endpoint returned allowed: true for operators with no location rules; that no longer happens.

This endpoint works from the IP address alone. If Vivamo can't resolve the IP to a location, it returns a 400 with the message Unable to resolve IP address to a geographic location. The SDK behaves differently. When the IP lookup fails during a customer's session, Vivamo falls back to other methods to establish their location, so a customer you couldn't pre-check may still be able to transact.

Pass the optional externalCustomerId field to record the check against that customer.

Key considerations

• Geolocation restrictions only apply to client-authenticated requests (payments and disbursements). Backend API calls using your secret key are not location-restricted.
• Use POST /v1/operators/check-geolocation to pre-check a customer's IP before starting a payment flow.
• Location rules cannot currently be modified via API. Reach out to support@vivamo.co to adjust your configuration.