ATM Nearby
Information Service Developer Merchant Acquirer Issuer
ATM Nearby is used to query the nearby ATM through the current position or the specified longitude and latitude.
API Introduction
API Introduction
What is it?

Through the current location or the specified longitude and latitude , developers can query the nearby ATM information. In necessary situation, customers can report wrong ATM information through this API.

Key Features

Periodic Update:

ATM data and customers' feedback will be updated regulary.

Integration Convenience:

The returned total ATM information data includes longitude and latitude data, which can not only meet the query requirements, but also facilitate integration with map app.

When to Use it?

Applicable for app side scenarios and 'where is ATM and how to go' app integration for LBS(Location Based Services ) scenarios.

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


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
Interface description
The interface allows a user to provide UPI with the error details of ATM information returned by UPI.
Request Method
Request Parameter
Field name Identifier Type Length Request Default value Note
ATM ID atmId S 1-100 C:Conditional The ATM ID that get from the result of ATM_LIST_INQUIRY and NEARBY_ATM_INQUIRY interface.
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 O:Optional “+30” Longitude of the ATM's location.
Latitude latitude S 1-100 O:Optional “-120” Latitude of the ATM's location.
Report Reason reportReason N 1 M:Mandatory "0" This provides the error of ATM information, including the following values:“0”: "There is no ATM at this address"“1”: "The ATM belongs to the wrong bank or city"“2”: "The address description of ATM is not accurate"“3”: "The ATM belongs to the wrong bank or city"“4”: "ChipCard not supported"“5”: “There is a new ATM at this address”“6”: “Others”
Other Reason otherReason S 1-100 O:Optional 0 This provides other error of ATM information.
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.
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 Operation Team

  • Contact Us
  • If you have any further questions, please register and submit order in your user center.