Guides
/
Geolocation & Access Restrictions

Geolocation and Access Restrictions

Location-based transaction 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 check fails, the request is denied with a 403 before it reaches the transaction handler.

Location rules

Location rules are configured per operator during onboarding. 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.

Operator-specific rules take priority over any platform-wide defaults.

Location rules are configured during onboarding and managed by the Vivamo team. Contact support@vivamo.co to view or update your location settings.

Sandbox behavior

In non-production environments, geolocation checks are relaxed. If the customer's IP address cannot be determined (common during local development), the request is allowed through. In production, requests without a resolvable IP are denied.

VPN and proxy detection

Customers using VPNs or proxies may be geolocated to the VPN exit node rather than their actual location. The resolved IP location is used as-is.

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.

If allowed is false, the customer's location is restricted and presenting a payment flow will result in a 403 at transaction time.

If your operator has no location rules configured, the endpoint returns { "allowed": true } without performing an IP lookup.

This is a server-to-server endpoint authenticated with your operator secret key. It is independent of payment or disbursement intents — call it at any point to check a customer's eligibility.

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.
Built with