Geolocation
/
Check Geolocation

Check Geolocation

POST
https://api.vivamo.co/v1/operators/check-geolocation

Check whether an IP address is in an allowed geolocation for your operator account. Use this to pre-check a customer's location before presenting payment UI, avoiding a poor experience where the customer fills out a form only to be denied at transaction time.

The IP's location is checked against your location rules, and the connection is checked for VPNs, proxies, Tor, data-centre ranges and known-bad addresses. Locations are blocked by default: an IP in a country with no location rule returns allowed: false.

This answer is advisory. The Vivamo SDK checks the customer's location again, using their own browser, before every payment and payout.

Request body

    ip
    string
    Required
    The IPv4 or IPv6 address to check.
    Examples:8.8.8.8
    externalCustomerId
    string
    Optional. Your ID for the customer this IP belongs to. When given, the check is recorded against that customer.
    Examples:cust_12345

Response

Geolocation check result.
    allowed
    boolean
    Whether the IP address is in an allowed location for this operator.
    reason
    string
    Why the check passed or failed.
      location_allowed
      string
      location_not_permitted
      string
      location_unconfirmed
      string
      anonymised_connection
      string
    flags
    array of string

    Connection checks that matched this IP, such as vpn, proxy, tor, datacenter, bogon, blocklist or trust_score_deny. A flag can appear on an allowed IP if Vivamo records that check without acting on it.

    checkId
    string
    The ID of the recorded check.
    country
    string or null
    Full country name.
    countryCode
    string or null
    ISO 3166-1 alpha-2 country code.
    state
    string or null
    Full state or region name.
    stateCode
    string or null
    ISO 3166-2 state or region code.
Built with