By continuing your navigation on our website, you consent to the use of cookies to provide you with better services. To learn more, read our cookies policy.
x
APIs
Products & Solutions
Partner
Support
Sign in
Search
International
中国站
Open API >Information Service >ATM Locator
ATM Locator
Information Service Developer Merchant Acquirer Issuer
ATM Locator allows users to query ATM accepting UnionPay card through the country code and other conditions.
Sandbox Testing
API Introduction
API Introduction
What is it?

Through the country code, city, bank and keyword, users can query ATM information with latitude and longitude.

Key Features

Periodic Update

Pay attention to the frequent changes in ATM data of financial institutions and acquiring institutions, and UnionPay international will update the data regularly。

Integration Convenience

ATM Locator API returns the longitude and latitude data, which can not only meet the query requirements, but also facilitate the integration with map app.


When to Use it?

It is applicable for customers to query ATM information according conditions such as country code in PC or App. For APIs more suitable for LBS (Location Based Services)scenarios, please refer to ATM nearby API.

Who Use it?
Issuer, Acquirer, Merchant, Developer
Where to Use it?
This API is available globally
Flow Chart
Flow Chart

数据调用类流程图.png

Access Flow:

1. API Caller apply to use APIs

2. UPI approve application, update white list and generate key pair, then provide API Caller the public key and user ID (appID)


Call Flow:

3. API Caller uses the public key to encrypt the request message which include caller’s user identity information

4. UPI verify API Caller’s identity, decrypt request message, and return response data encrypted by using private key.
API Reference
API Reference
  • ATM_LIST_INQUIRY
  • ATM_CITY_AND_BANK_LIST_INQUIRY
Interface description
The interface provides detailed information about ATMs with specified conditions. For example, it provides the name, address, coordinates and special features of all the ATMs in the country.
Request Method
HTTP POST
Request Parameter
Field name Identifier Type Length Request Default value Note
Country Code countryCode N 3 M:Mandatory "156" A 3-digit numeric value, as defined by [ISO 3166], that indicates the country code.
City Name cityName S 1-100 O:Optional The name of the city for an ATM location.The name shall be the response result from the ATM_CITY_AND_BANK_LIST_INQUIRY interface.
Bank Name bankName S 1-100 O:Optional The owner of the ATM.The name shall be the response result from the ATM_CITY_AND_BANK_LIST_INQUIRY interface.
Keyword keyword S 1-10 O:Optional Some words that used to match
Page Number pageNo N 1-10 M:Mandatory “1” The page number where the response will start.
Page Size pageSize N 1-10 M:Mandatory “20” Maximum number of items to retrieve within the current page.
Synchronous Response parameters
Filed name Identifier Type Length Request Default value Note
Message Response 　msgResponse 　Object M:Mandatory
Response Code responseCode AN 2 M:Mandatory "00" It contains a code that defines the response to a request.
Response Message responseMsg S 1-100 M:Mandatory "Approved" It contains the request result and the rejection reason if the request fails. The value of this field can be displayed by the Gateway to notify the user of the request outcome.
Error Details errorDetail S 1-255 O:Optional “The Issuer response is time out.” It contains additional detail regarding the problem identified in the message. The information is only for debug purpose. It shall not be displayed to the user.
Total Page totalPage N 1-10 M:Mandatory “5” The page number that the response will include.
Total Number totalNo N 1-100 M:Mandatory “100” The total number that the response will include.
ATM List atmList Array M:Mandatory The returned ATM list
ATM ID atmId S 1-100 M:Mandatory The ATM ID.
Country Code countryCode N 3 M:Mandatory "156" A 3-digit numeric value, as defined by [ISO 3166], that indicates the country code.
City Name cityName S 1-100 M:Mandatory The name of the city for an ATM location.
Bank Name bankName S 1-100 M:Mandatory The owner of the ATM.
Address address S 1-500 M:Mandatory The address of an ATM
Longitude longitude S 1-100 M:Mandatory 37.119999999999997 Longitude of the ATM's location.
Latitude latitude S 1-100 M:Mandatory -121.23 Latitude of the ATM's location.
Security Requirement
Security Requirement


UnionPay International has adopted unified security requirement, please refer to UPI Server-based API General Requirements  for signature and encryption guide.
Steps to Launch
Steps to Launch

If you are UPI member, you need to fill in the Application Form of API Service Product with Terms and Conditions.

If not, you need to sign the Protocol of API Usage and fill in the Application Form of API Service Product.


Please submit order to contact Developer Team
  • Contact Us
  • If you have any further questions, please register and submit order in your user center.
©Copyright 2002 - 2023. All rights reserved