UnionPay International Developer

Open API >Information Service >ATM Nearby

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

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

数据调用类流程图.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

ATM_FEEDBACK_INFORM
NEARBY_ATM_INQUIRY

Interface description

The interface allows a user to provide UPI with the error details of ATM information returned by UPI.

Request Method

HTTP POST

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.

Interface description

The interface can return the list of ATM locations nearest to a given location.

Request Method

HTTP POST

Request Parameter

Field name	Identifier	Type	Length	Request	Default value	Note
Longitude	longitude	ANS	1-100	M:Mandatory	“+30”	Longitude of the user's location.
Latitude	latitude	ANS	1-100	M:Mandatory	“-120”	Latitude of the user's location.
Distance Unit	distanceUnit	A	1-4	M:Mandatory	“mile”	The unit for the radius.The combination of "distanceUnit" and “radius” shall be no more than 5miles. Valid Values:• “mile”• “km”
Radius	radius	ANS	1-4	O:Optional	“2.11”	The radius from the search point.The combination of "distanceUnit" and “radius” shall be no more than 5miles.The value shall only include (numeric) digits "0" to "9" and may contain a single "." character as the decimal mark. The maximum decimal digits is 2.
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. The value shall be constant value “20”.

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. Please refer to the Definition of Elements in Message Response for the valid values.
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. Please refer to the Definition of Elements in Message Response for details.
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.Please refer to the Definition of Elements in Message Response for examples.

Total Page

totalPage

1-10

M:Mandatory

“5”

The page number that the response will include.

Total Number

totalNo

1-100

M:Mandatory

“100”

The total number that the response will include.

Nearby ATM List

nearbyAtmList

Array

M:Mandatory

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		Longitude of the ATM's location.
Latitude	latitude	S	1-100	M:Mandatory		Latitude of the ATM's location.
Distance Unit	distanceUnit	S	1-5	M:Mandatory		The unit of the distance.
Distance	distance	ANS	1-6	M:Mandatory		The distance from the search point to the ATM.

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

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

Card Product

Online Payment

Mobile QuickPass

QR Code

Cross-Border B2B Service

Token Program

SaaS Card Issuing Service Platform

Block Chain

Platforms

Global Service

Digital Solutions

Industry Solutions

Deferred Online ODA Mode

Real-Time Mode

Frictionless Parking

Transit QR Code Mode

Prompt

Kindly Reminder

Prompt