Discover_Image ATM Locator > Documentation

Overview


The ATM Locator V2 Service provides the ATM Locations based on the location info.

Authentication-Making the first API request is only few steps away


  1. All projects start in Sandbox mode. Once you’re invited to gain access to this API you can login here to get Client Application ID (API Key) Client Application Secret, Consumer Application Certificate and API Plan name.

  2. All API requests must be authenticated with an OAuth token. To get the OAuth token, follow these simple steps

    1. Make a HTTP POST request to the endpoint /auth/oauth/v2/token with HTTP Authorization Header as Basic base64encoded(client_application_id:client_application_secret), Content-Type as application/x-www-form-urlencoded and Cache-Control as no-cache

    2. The response would contain an OAuth token along with token type and token expiry in seconds

      SAMPLE OAUTH TOKEN REQUEST

      POST /auth/oauth/v2/token?grant_type=xyz&scope=RWDS_xyz HTTP/1.1
      Authorization: sdlfsdf0dskladfk123456
      Content-Type: application/x-www-form-urlencoded
      Cache-Control: no-cache

      SAMPLE RESPONSE

      Response-Status: HTTP/1.1 200 OK
      Cache-Control: no-store
      Content-Type: application/json;charset=UTF-8
      Pragma: no-cache
      {
      "access_token": "sdlfsdf0dskladfk123456"
      "token_type": "xyz"
      "expires_in": 3600
      "scope": "RWDS_xyz"
      }

  3. Once an OAuth token is obtained, you can use the token along with Consumer Application Secret and API Plan name provided during Sandbox access in the HTTP Header of an API to make your first call. The same OAuth can be used for multiple API calls as long as it is not expired.

Access Error


User authentication failed with error code 1001 and HTTP Status Code as 401

Not authorized to access the resource! With the error code 1003 and HTTP Status Code as 403

Unsupported Media Type with HTTP status Code 415

API Structure


A typical API request would contain the sections HTTP Header, Request Header, Request Body as part of the request and HTTP Header, Response Header and Response Body as part of the response with some exception due to the nature of the API. Refer the individual end points to know more.

HTTP Header


We follow a robust standard for HTTP Header which includes the following parameters to be supplied while you are making an API request

Accept
Content-Type
Authorization
X-DFS-API-PLAN
The value for Authorization will be Basic access_token
The value for X-DFS-API-PLAN will be provided during App registration in the portal
Our HTTP Header in the response will include Access, Content-Type and Cache-Control

HTTP Status Codes


The HTTP Status Code returned in the response follows an industry API standard and designed to help you better interpret the underlying error.
User authentication failed with error code 1001 and HTTP Status as 401
Not authorized to access the resource! With the error code 1003 and HTTP Status as 403
Unsupported Media Type with HTTP status as 415
Validation error with the error code 10001 and HTTP Status as 400
Internal server error with the error code 10002 and HTTP Status as 500

/globalpymt/atmlocator/v2/atmlocations

/globalpymt/atmlocator/v2/atmlocations


This API provides List of ATM’s based on the provided location info.

REQUEST ARGUMENTS


maxresults: integer | optional

Maximum number of results required to be obtained as response

longitude: double | mandatory

Longitude of the location

latitude: double | mandatory

Latitude of the location

radius: double | mandatory

Results within how many miles

appType: string | mandatory

Application type (3 characters alphabet value)

surchargeFree: Boolean | optional

ASurcharge or no Surcharge

availability: string | optional

Availability of location (1 character numeric value)

airportCode: string | optional

Airport code of location

dccFlag: string | optional

Dynamic currency conversion enabled

emvFlag: string | optional

EMV enabled

institutionName: string | optional

Valid name of the institution

locationType: string | optional

Type of location

open24: Boolean | optional

ATM Location available 24 hours

overTheCounter: Boolean | optional

Over the counter enabled

Units: string | optional

Distance Units in miles or kilometers

REQUEST HTTP HEADERS


Authorization:

The value of the header is Bearer access_token

X-DFS-API-PLAN:

Name of the API plan assigned to the app during registration approval (e.g. ATMLOCATOR_V2_PROD, ATMLOCATOR_V2_Sandbox)

SAMPLE CURL REQUEST

curl -X GET \
/globalpymt/atmlocator/v2/atmlocations\ longitude=87.641206&latitude=41.884315&radius=10\
-H 'authorization: access_token ' \
-H 'cache-control: no-cache' \
-H 'x-dfs-api-plan: ATMLOCATOR_V2_PROD '

RESPONSE VALUES


atmIdentifier: Integer

ATM ID

terminalId: string

Terminal ID

geoPoint: latitude: double

ATM Location latitude

geoPoint: longitude: double

ATM Location longitude

geoPoint: geoCodeAccuracyCode: Integer

ATM Location accuracy score

address: address1: string

Address of the ATM

address: address2: string

Address of the ATM

address: address3: string

Address of the ATM

address: postalCode: string

Zipcode of the location.

address: postalCodeExt : string

Extended zipcode of the location.

address: cityName: string

City where the ATM is located.

address: stateProvinceCode: string

State where ATM is located.

address: countryCode: string

Country where ATM is located.

address: intersection: string

Is it Intersection?

availability: availability: string

ATM Availability

location: locationName: string

ATM Location Name

location: locationDescription: string

ATM Location Description

institutionDetail: institutionId: string

Institution Id

institutionDetail: institutionName: string

Institution Name

restricted: string

Is ATM restricted?

braille: string

Braille Indicator

driveUp: string

Drive Up Indicator

walkUp: string

Walk up Indicator

handicapIndicator: string

Handicap Indicator

dccIndicator: string

DCC Indicator

emvIndicator: string

EMV indicator

sharedDepositIndicator: string

Shared Deposit Indicator

airportCode: string

Airport code

Sample Response

{
"atmLocations" : [
{
"atmIdentifier" : 3792556,

"terminalId" : "CR018008",

"geoPoint" : {
"latitude": 38.825085,
"longitude": -76.94785,
"geoCodeAccuracyCode": 8
},

"address" : {
"address1": "4717 ST. BARNABAS RD.,SE",
"address2": "New Building",
"address3": "South block",
"postalCode": "20748",
"postalCodeExt": "",
"cityName": "TEMPLE HILLS",
"stateProvinceCode": "MD",
"countryCode": "USA",
"intersection": "YES"
},

"availability" : {
"atmHoursAvailCode": "1"
},

"location" : {
"locationName": "AMF Marlow Heights Lanes",
"locationDescription": "Marlow Heights Lanes"
},

"institutionDetail" : {
"institutionId": "1234567890",
"institutionName": "One Bank"
},

"restricted" : "Y",

"braille" : "U",

"driveUp" : "U",

"walkUp" : "N",

"handicapIndicator" : "Y",

"dccIndicator" : "N",

"emvIndicator" : "U",

"sharedDepositIndicator" : "N",

"airportCode" : ""
}
]
}

/globalpymt/atmlocator/v2/healthcheck

/globalpymt/atmlocator/v2/healthcheck


This API can be used to check if the service is up and running

REQUEST HTTP HEADERS


Accept:

Only accept application/json type

Authorization:

The value of the header is Bearer access_token

X-DFS-API-PLAN:

Name of the API plan assigned to the app during registration approval (e.g. ATMLOCATOR_V2_PROD, ATMLOCATOR_V2_Sandbox)

SAMPLE CURL REQUEST

curl -X POST /globalpymt/atmlocator/v2/healthcheck
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "Cache-Control:no-store" \
--header "x-dfs-api-plan:ATMLOCATOR_V2_PROD" \
--request POST \

RESPONSE VALUES


statusCode: string

HTTP Status Code

statusMessage: string

Status Message

healthCheckResponse: healthCheckStatus: string

Health check status description

Sample response

{
"responseHeader" :
{
"statusCode": "200" ,
"statusMessage": "Success"
} ,
"healthCheckResponse" :
{
"healthCheckStatus": "The ATM Locator V2 API is Up and Running"
}
}

/globalpymt/atmlocator/v2/statesandprovinces/countrycode/{countrycode}/detail

/globalpymt/atmlocator/v2/statesandprovinces/countrycode/{countrycode}/detail


This method is used to return state and provinces details by country code.

REQUEST ARGUMENTS


countrycode: string | optional

3 letter ISO alphabet country code

REQUEST HTTP HEADERS


Authorization:

The value of the header is Bearer access_token

X-DFS-API-PLAN:

Name of the API plan assigned to the app during registration approval (e.g. ATMLOCATOR_V2_PROD, ATMLOCATOR_V2_Sandbox)

SAMPLE CURL REQUEST

curl -X GET \
/globalpymt/atmlocator/v2/statesandprovinces/countrycode/USA/details \
-H 'authorization: access_token ' \
-H 'cache-control: no-cache' \
-H 'x-dfs-api-plan: ATMLOCATOR_V2_PROD'

RESPONSE VALUES


stateProvinceCode: string

State or Province code

stateProvinceName: string

Name of State or Province

Sample Response

{
"stateAndProvinces" : [

{
"stateProvinceCode" : "AL",
"stateProvinceName" : "Alabama"
},

{
"stateProvinceCode" : "AK",
"stateProvinceName" : "Alaska"
},

{
"stateProvinceCode" : "AS",
"stateProvinceName" : "American Samoa"
},

{
"stateProvinceCode" : "AZ",
"stateProvinceName" : "Arizona" 
},

{
"stateProvinceCode" : "AR",
"stateProvinceName" : "Arkansas" 
},

{
"stateProvinceCode" : "CA",
"stateProvinceName" : "California"
},

{
"stateProvinceCode" : "CO",
"stateProvinceName" : "Colorado"
},

{
"stateProvinceCode" : "CT",
"stateProvinceName" : "Connecticut"
},

{
"stateProvinceCode" : "DE",
"stateProvinceName" : "Delaware"
},

{
"stateProvinceCode" : "DC",
"stateProvinceName" : "District of Columbia"
},

{
"stateProvinceCode" : "FL",
"stateProvinceName" : "Florida"
},

{
"stateProvinceCode" : "GA",
"stateProvinceName" : "Georgia"
},

{
"stateProvinceCode" : "TN",
"stateProvinceName" : "Tennessee"
},

{
"stateProvinceCode" : "TX",
"stateProvinceName" : "Texas"
},

{
"stateProvinceCode" : "UT",
"stateProvinceName" : "Utah"
},

{
"stateProvinceCode" : "VT",
"stateProvinceName" : "Vermont"
},

{
"stateProvinceCode" : "VI",
"stateProvinceName" : "Virgin Islands, U.S."
},

{
"stateProvinceCode" : "VA",
"stateProvinceName" : "Virginia"
},

{
"stateProvinceCode" : "WA",
"stateProvinceName" : "Washington"
},

{
"stateProvinceCode" : "WV",
"stateProvinceName" : "West Virginia"
},

{
"stateProvinceCode" : "WI",
"stateProvinceName" : "Wisconsin"
},

{
"stateProvinceCode" : "WY",
"stateProvinceName" : "Wyoming"
}
]
}

/globalpymt/atmlocator/v2/countries/apptype/{apptype}/details

/globalpymt/atmlocator/v2/countries/apptype/{apptype}/details


This method is used to get the countries from the app type.

REQUEST ARGUMENTS


appType: string | mandatory

3 character application type.

REQUEST HTTP HEADERS


Authorization:

The value of the header is Bearer access_token

X-DFS-API-PLAN:

Name of the API plan assigned to the app during registration approval (e.g. ATMLOCATOR_V2_PROD, ATMLOCATOR_V2_Sandbox)

SAMPLE CURL REQUEST

curl -X GET \
/globalpymt/atmlocator/v2/countries/apptype/PUL/details \
-H 'authorization: access_token ' \
-H 'cache-control: no-cache' \
-H 'x-dfs-api-plan: ATMLOCATOR_V2_PROD'

RESPONSE VALUES


countryCode: string

ISO country code

countryName: string

Country name

stateProvList: string

List of States or Provinces

countryShrtCode: string

Country short code

nativeName: string

Native country name

postalCodeVal: string

Postal code value

postalCodeInd: string

Postal code indicator

countryActInd: string

Country active indicator

cntrySbDivStatus: string

Country sub division status

Sample Response

{
"countries" : [

{
"countryCode" : "USA",
"countryName" : "UNITED STATES OF AMERICA",
"stateProvList" : "AL|Alabama,AK|Alaska,AS|American Samoa,AZ|Arizona,AR|Arkansas,CA|California,CO|Colorado,CT|Connecticut,DE|Delaware,DC|District of Columbia,FL|Florida,GA|Georgia,GU|Guam,HI|Hawaii,ID|Idaho,IL|Illinois,IN|Indiana,IA|Iowa,KS|Kansas,KY|Kentucky,LA|Louisiana,ME|Maine,MD|Maryland,MA|Massachusetts,MI|Michigan,MN|Minnesota,MS|Mississippi,MO|Missouri,MT|Montana,NE|Nebraska,NV|Nevada,NH|New Hampshire,NJ|New Jersey,NM|New Mexico,NY|New York,NC|North Carolina,ND|North Dakota,MP|Northern Mariana Islands,OH|Ohio,OK|Oklahoma,OR|Oregon,PA|Pennsylvania,PR|Puerto Rico ,RI|Rhode Island,SC|South Carolina,SD|South Dakota,TN|Tennessee,TX|Texas,UT|Utah,VT|Vermont,VI|Virgin Islands, U.S.,VA|Virginia,WA|Washington,WV|West Virginia,WI|Wisconsin,WY|Wyoming",
"countryShrtCode" : "US",
"nativeName" : "United States",
"postalCodeVal" : "^[0-9]{5}[ -]?([0-9]{4})?$",
"postalCodeInd" : "Y",
"countryActInd" : "A",
"cntrySbDivStatus" : "A",
}
]
}

/globalpymt/atmlocator/v2/atmlocations/count

/globalpymt/atmlocator/v2/atmlocations/count


This method is used to get the count of atm locations.

REQUEST ARGUMENTS


maxresults: integer | optional

Maximum number of results required to be obtained as response

longitude: double | mandatory

Longitude of the location

latitude: double | mandatory

Latitude of the location

radius: double | mandatory

Results within how many miles

appType: string | mandatory

Application type (3 characters alphabet value)

surchargeFree: Boolean | optional

ASurcharge or no Surcharge

availability: string | optional

Availability of location (1 character numeric value)

airportCode: string | optional

Airport code of location

dccFlag: string | optional

Dynamic currency conversion enabled

emvFlag: string | optional

EMV enabled

institutionName: string | optional

Valid name of the institution

locationType: string | optional

Type of location

open24: Boolean | optional

ATM Location available 24 hours

overTheCounter: Boolean | optional

Over the counter enabled

Units: string | optional

Distance Units in miles or kilometers

SAMPLE CURL REQUEST

curl -X GET \
/globalpymt/atmlocator/v2/atmlocations//count \ longitude=87.641206&latitude=41.884315&radius=10 \
-H 'authorization: access_token ' \
-H 'cache-control: no-cache' \
-H 'x-dfs-api-plan: ATMLOCATOR_V2_PROD'

Sample Response

4023

Errors


Header Level Error Codes

Error Message Error Description HTTP Status Code
Data not found for request. No data found for the request. 200
Valid app type required (<3 characters alphabet values> allowed). 3 characters alphabet values allowed. 400
Valid country code required (<3 characters alphabet values> allowed). 3 characters alphabet values allowed. 400
Latitude is a required field. -90 to 90 decimal value allowed. 400
Valid Latitude required (-90 to 90 decimal value allowed). -90 to 90 decimal value allowed. 400
Longitude is a required field. -180 to 180 decimal value allowed. 400
Valid longitude required (-180 to 180 decimal value allowed). -180 to 180 decimal value allowed. 400
App type is a required field. 3 characters alphabet values allowed. 400
Valid app type required (<3 characters alphabet values> allowed). 3 characters alphabet values allowed. 400
Radius is a required field. 1 to 30 numeric value allowed. 400
Valid radius required (1 to 30 allowed). 1 to 30 numeric value allowed. 400
Valid unit type required ('mi' and 'km' are allowed). 'mi' and 'km' are allowed. 400
Valid max results required (1 to 100 allowed). 1 to 100 numeric value allowed. 400
Valid airport code required (<3 characters alphabet values> allowed). 1 to 100 numeric value allowed. 400
Valid institution name required (special characters not allowed). Special characters not allowed. 400
Invalid location type indicator input (<2 characters numeric value>). 2 characters numeric value allowed. 400
There has been an error processing your request, please try again. Internal server error. 500