Stores API Method

The Store API is a REST API that partners use to obtain a list of stores where the specific cash-in services are available. The results can then be displayed to the users on the partner’s mobile app or website. The API uses different endpoints to produce a list of stores by:

Zip code
Longitude and latitude

Find Stores By Zip code

The search process uses the following values.

Zip code
Program number (part of header)
Page number
Records count per page
Service type

Following are the endpoints that the Stores API uses to search for a list of retail stores.

Structure of API Calls:

GET /v1/stores/zip_code/{zipcode}/service_type/{service_type}

GET /v1/stores/zip_code/{zipcode}/service_type/{service_type}/page/{page}

GET /v1/stores/zip_code/{zipcode}/service_type/{service_type}/page/{page}/count/{count}

GET /v1/stores/zip_code/{zipcode}/service_type/{service_type}/page/{page}/count/{count}/partner_ref/{partner_transaction_reference}

Sample Request - Header

URL: ~/v1//stores/zip_code/00544/service_type/3

Header

{
x-gdn-timestamp:2020-06-18T06:07:44Z
x-gdn-encryptiontype:1
x-gdn-messageid:2020052500823
x-gdn-channeltype:1
x-gdn-devicetype:2
x-gdn-ipaddress:192.168.1.1
x-gdn-programnumber:Catalina-BC 
x-gdn-latitude:-25.78
x-gdn-longitude:288.11 
x-gdn-signature:ADE0FBA53088B498F55953C608A3DB55CCEA6C92CDC92285F84F38B025C922D9
}

Request Parameters

Parameter	Data Type	Required?	Description
zip_code	string	Yes	The zip code to search.
Page	int	No	The page number (default=1).
Count	int	No	Number of records per page (default = 50).
service_type	int	Yes	Each service occupies one binary flag. Values include: 1 = IsCashReload, 2 = IsCheckLoading 4 = IsPINDebitReload 8 = IsPayPalCash 16 = IsOnlineAccountLoad 32 = IsBarCodeReload 64 = IsCreditCardBillPay 128 = IsCheckingAccountDeposit 256 = IsDisbursements NOTE: we need to pass IsCashReload, IsCheckLoading, IsPayPalCash and then we need to send the flag "1011", then sum 1+2+8 = 11, pass 11 as parameter
partner_transaction_ref	string	No	The unique, partner-generated transaction reference.

Sample Request (Header)

{
x-gdn-timestamp:2020-06-18T06:07:44Z 
x-gdn-encryptiontype:1
x-gdn-messageid:2020052500823 
x-gdn-channeltype:1
x-gdn-devicetype:2
x-gdn-ipaddress:192.168.1.1
x-gdn-programnumber:Catalina-BC x-gdn-latitude:-25.78
x-gdn-longitude:288.11 
x-gdn-signature:ADE0FBA53088B498F55953C608A3DB55CCEA6C92CDC92285F84F38B025C922D9
}

Sample Response 1

<get_store_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>0</gd_response_code>
<gd_response_date>2020-06-18T07:23:52.2543346Z</gd_response_date>
<gd_response_message>Success</gd_response_message>
<gd_transaction_reference>610db3bf-a3ee-440c-ae4c-7fb94546a218</gd_transaction_reference>
<partner_transaction_reference></partner_transaction_reference>
<count>50</count>
<page>1</page>
<store_list>
<store>
<address>305 Main St</address>
<city>Holbrook</city>
<latitude>40.81199000</latitude>
<longitude>-73.08004500</longitude>
<phone>6319817328</phone>
<retailer_key>2433</retailer_key>
<retailer_name>CVS</retailer_name>
<state>NY</state>
<store_id>CVS1192</store_id>
<zip_code>11741</zip_code>
</store>
<store>
<address>328 UNION AVE.</address>
<city>HOLBROOK</city>
<latitude>40.81194185</latitude>
<longitude>-73.08072880</longitude>
<phone>6315888229</phone>
<retailer_key>10744</retailer_key>
<retailer_name>Waldbaums</retailer_name>
<state>NY</state>
<store_id>Waldbaums3542</store_id>
<zip_code>11741</zip_code>
</store>
<store>
<address>397 Sunrise Hwy W</address>
<city>Patchogue</city>
<latitude>40.76305300</latitude>
<longitude>-73.01686200</longitude>
<phone>6316541300</phone>
<retailer_key>2460</retailer_key>
<retailer_name>Rite Aid</retailer_name>
<state>NY</state>
<store_id>Rite Aid10657</store_id>
<zip_code>11772</zip_code>
</store>
</store_list>
<total_count>392</total_count>
</get_store_response>

Sample Response 2

{
   "store_list": [
      {
	 "store_id": "string",
	 "retailer_key": "string",
	 "retailer_name": "string",
	 "address": "string",
	 "phone": "string",
	 "city": "string",
	 "state": "string",
	 "zip_code": "string",
	 "latitude": "string",
	 "longitude": "string"
      }
  ],
  "total_count": 0,
  "page": 0,
  "count": 0,
  "partner_transaction_reference": "string",
  "gd_transaction_reference": "string",
  "gd_response_code": 0,
  "gd_response_message": "string",
  "gd_response_date": "2022-04-29T14:23:15.608Z"
}

Response Field Definitions

Parameter	Type	Description
total_count	int	The total number of stores returned from the search.
page	int	The total page count (default = 1).
count	int	records count per page, default value '50'
store_list	list	store entity list. The order of the list is closest to longest away from search coordinate. And it is 25 mile radius from search point.
store:retailer_name	string	The retailer’s name.
store:address	string	The store address.
store:phone	string	The store phone number
store:latitude	decimal	The store’s latitude.
store:longitude	decimal	The store’s longitude.
store:store_id	string	The store’s name and ID.
store:city	string	The city in which the store is located.
store:zip_code	string	The store’s store zip code.
store:state	string	The state in which the store resides.
store:retailer_key	string	The store’s retailer key.
partner_transaction_reference	string	The unique TransactionReference that the partner optionally provides.
gd_transaction_reference	string	The unique transaction reference that Green Dot generated.
gd_response_code	Int	Refer to Response Codes.
gd_response_message	string	Custom text describing the success or failure of the API.
gd_response_date	DateTime	Response date time in UTC.

Find Stores By Longitude and Latitude

The search process uses the following values:

Program number (part of header)
Center point location
Page number
Records count per page
Services type

API Call Structures:

GET /v1/stores/latitude/{latitude}/longitude/{longitude}/service_type/{service_type}

GET /v1/stores/latitude/{latitude}/longitude/{longitude}/service_type/{service_type}/page/{page}

GET /v1/stores/latitude/{latitude}/longitude/{longitude}/service_type/{service_type}/page/{page}/count/{count?}

GET /v1/stores/latitude/{latitude}/longitude/{longitude}/service_type/{service_type}/page/{page}/count/{count?}/partner_ref/{partner_transaction_reference?}