Visa Global ATM Locator Documentation

Ready to start coding?

Things To Know

The Global ATM Locator API can be used by any developer in the sandbox. To use the API in production, you must either be a Visa issuer or be pre-approved by Visa to use the service. The Global ATM Locator API Licensing Agreement and approval process is available as part of Production Onboarding.

The Geocode Inquiry and Routes Inquiry operations are provided by a third-party and may only be used in conjunction with the Global ATM Locator API. Any other use of these operations could violate the Terms of Use for the service.

Availability

The following table lists the regional availability for Visa Global ATM Locator. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
Visa Global ATM Locator
Product Name Availability Notes
Visa Global ATM Locator
Product Name Availability Notes
Visa Global ATM Locator
Product Name Availability Notes
Visa Global ATM Locator
Product Name Availability Notes
Visa Global ATM Locator

Getting Started

Visa Global ATM Locator enables cardholders to search for Visa/Plus ATM locations around the world, via the Web or from their internet-enabled mobile devices.

The Visa Global ATM Locator service lets cardholders find a convenient ATM when they need cash from over 1 million ATMs in over 200 countries.  The ATM Locator Service is a cost effective way to deliver user friendly, trusted information when users need cash while travelling or in emergencies. To use the Global ATM Locator service, follow these steps:

  1. Get the location where the user wants to center the search radius.  A street address works, or you can use the geo-location of the user’s mobile phone.
  2. Select any search criteria for the ATM (e.g. hours of operation, wheelchair accessibility, etc.) from the list of available ATM search criteria discussed below.
  3. Using the “Totals Inquiry” operation, check the number of ATMs that meet the user’s search criteria, before requesting the complete list of ATM details (which could be large).   Totals can be useful to refine search criteria, format displays, or pre-allocate memory resources.
  4. Based on the totals returned, help the user refine the search criteria if needed, iterating the Totals Inquiry request as appropriate.
  5. Request the detailed list of ATMs with the “ATMs Inquiry” operation, using the refined search criteria developed with Totals Inquiry.
  6. Display the list and let the user select the best fit from among the ATMs in the list.
  7. Finally, provide the user with the route from the current (or alternate) location to the ATM selected from the list by using the “Geocode Inquiry” to convert the local address(es) into a latitude and longitude.  Then use, the “Routes Inquiry” operation to provide walking or driving directions.

How Does It Work?

A cardholder submits a street address, city, postal/zip code, point of interest, or geolocation codes (latitude and longitude) and the Global ATM Locator service returns a list of nearby ATMs. Cardholders can further refine their search by adding filters, such as hours of operation, chip-capable ATMs, or wheelchair accessibility. Cardholders can then view the details about a particular ATM location and receive routing directions to it (if available).

Why Use It?

Issuers

Issuers can provide their cardholders with access to a broader set of available ATMs, not just the ones in their own network. 

Merchants

Merchants can enable cardholders to find ATMs in or near their retail locations.

Independent Developers 

Independent developers can offer an ATM locator service as part of their mobile applications.

API Included

Locate ATMs

The Locate ATMs API provides the means to find up to 100 ATM locations that match a set of filter criteria and are near a given location (near a given single-line input address/geocode). The Locate ATMs API can also find routing information for a given start and destination point.

Using the Totals Inquiry Operation

This operation returns a simple list of ATM Names located within the specified radius of the request location (separated by "|"), and subtotals of the number of ATMs that match each of the filter criteria included in the request. For a detailed description of each ATM, you should use the "ATMs Inquiry" operation instead.

E.g.:

“PLACENAMES”:“CHUCKS DONUTS|DONOVAN’S LIQUOR & DELI|PHOENIX RESTAURANT”, followed by totals for each filter criterion,

 “WHEELCHAIR”:”1”, “TOTALCOUNT”:“3”.

Up to 100 ATM locations may be returned, so it’s best to iterate the search criteria using the “Totals Inquiry” first to narrow in on the right set, before getting all the details from the “ATM Inquiry” operation details later.  This operation enables you to perform tasks like refine search criteria iteratively, prepare a user interface, or reserve storage for the detailed list.

For complete details, please refer to the API Reference link.

To use the Totals Inquiry operation, you need:

  • Location of the search center, Required, either as a comma separated string containing a single line address of {street, city, state, zip, country} (e.g. “101 Main St, Bigtown, OH, 10040, USA”), or as geo-coordinates (e.g. “Latitude": 37.394664,"Longitude": -122.062304)
  • Search radius, Required, e.g. “distance”:”10” and “distanceUnit”:”mi” (or “km”)
  • Search filter criteria, Optional, from the list below, e.g., "WHEELCHAIR" accessible:
ACCEPTS_PLUS_SHARED_DEPOSIT ATM will accept a deposit from another Financial Institution’s customer.
CARD_ACCEPT ATM accepts both Visa and Plus, Plus Only or Visa Only. Most ATMs accept both Visa and Plus.
WHEELCHAIR ATM is wheelchair accessible.
PLUS_ALLIANCE_NO_SURCHARGE_FEE ATM allows customers of Financial Institutions that participate in Plus Alliance to use their ATM at no charge. Plus Alliance is a program that is only available in the U.S.
READY_LINK ATM allows customers to add funds to their Visa Prepaid card.
LOC_DESC Description of where the ATM is located such as: Shopping Mall Name, Gas Station Name, Store Name.
RESTRICTED ATM is in a restricted area such as a secured area of a building, in an ATM room at a branch or at a club where membership is required.
BALANCE_INQUIRY ATM has balance inquiry capability.
OPER_HRS Hours of operation.
BRAILLE_AUDIO ATM has braille audio capability.
PIN_CHANGE ATM supports PIN change functionality.
AIRPORT_CD ATM is in an airport and if so, which one.
CHIP_CAPABLE ATM is chip capable.
V_PAY_CAPABLE Highly secure, chip-only, PIN based debit product issued by European banks for use in shops to make purchases and at ATMs to withdraw cash. V Pay is only available in the European Union.

Using the ATMs Inquiry Operation

This operation allows a project to retrieve complete details, such as the name, address, geo-coordinates and attributes (e.g., wheelchair accessibility) for up to 100 ATMs near a given location. The list can be modified using the same search criteria discussed above in “Totals Inquiry”.

Using the Geocode Inquiry Operation

The “Geocode Inquiry” operation returns the geo-coordinates (latitude and longitude) that correspond to a specified street address.   A user might be interested in finding ATMs starting from a location other than his or her current location.

For example, a user is in New York preparing for a business trip and is looking up ATMs in San Francisco, starting from his or her hotel in San Francisco.  Geocode Inquiry would allow the project to request the geo-coordinates of the hotel in San Francisco, using the street address of the hotel as the starting point.

  • Specify the street address for inquiry as a comma separated single string of text of the form "street, city, state, zip, country" (e.g., "101 Main St., Bigtown, OH, 10040, USA").

Using the Routes Inquiry Operation

This operation returns the route and directions between two or more specified geolocations (Latitude/Longitude). The directions can be either for walking or driving. The distance between two points and the estimate time of arrival is also provided.

If your project UI supports it, you can provide the output to a mapping service of your choice such as Google Maps or Microsoft Bing.

To use the Routes Inquiry operation, you must provide:

  • Starting location (expressed as a Latitude/Longitude pair, e.g. “Latitude": 37.394664,"Longitude": -122.062304)
  • Ending location (expressed as a Latitude/Longitude pair)
  • Routing travelMode preference, for “WALKINGTIME” or “DRIVINGTIME”.

Security and Authentication Requirements

No additional required beyond standard VDP project authentication. Note that Two Way SSL is recommended for the ATM Locator API.

You can get test credentials for sandbox testing online in the Developer Dashboard for the project.  Production credentials will be issued as part of the production on-boarding process.  Contact developer@visa.com for more information or to begin production onboarding.

Service Activation Requirements

As mentioned elsewhere, please note that the Routes Inquiry and Geocode Inquiry operations are provided strictly for use in conjunction with the ATM Locator functions, and are not intended to be used outside of that context.  Use of the Routes and Geocode inquiry operations outside of their intended application may void your license agreement.

Final deployment of the service is subject to Visa approval.