Stores
This API is to look for the enabled retailer’s store information by zipcode or location for the customers of POB partner. Green Dot has implemented it, the POB partners just call it if they need to return store list back to customers.
Authentication
Header Information
- The services will be hosted in an environment which is IP restricted. Only the authorized partners will have access to these services
- The payload will be encrypted in the SSL environment
- A secret keywill be shared between GD and the partner. Please contact Green Dot development team for the secret key
| Field | Required? | Description |
|---|---|---|
| x-gd-timestamp | Yes | Timestamp in http header is using the pattern [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss][time zone] that preserves time zone information and complies with ISO 8601.The time zone component is an offset from UTC (for example, +01:00, -07:00). The time zone component uses ‘Z’ (which stands for zero offset) to represent UTC.Timestamp string without time zone component is assumed to be UTC. Examples of the timestamp string are 202005-22T03:07:53Z |
| x-gd-signature | Yes | signature of the message (see the signature calculationbelow) |
| x-gd-encryptiontype | Yes | 0-none, 1-Digital Signature |
| x-gd-requestid | Yes | unique id of the request |
| x-gd-channeltype | Yes | 1-mobile, 2–web, 0-other |
| x-gd-deviceid | No | device id of the client making the API call (for future use) |
| x-gd-devicetype | Yes | 0-other, 1-mobile, 2-desktop |
| x-gd-ipaddress | Yes | IP Address of the client making the API call |
| x-gd-programcode | Yes | Programcode assigned by Green Dot |
GD will issue the Partner a secret key that will be used for the signature calculation
Signature calculation
Sort the headers (except the Signature header). Remove extra spaces around the fields.
- sort the fields by alphabetical and concatenate the headers using a delimiter &
- ASCII encode secret key
- UTF8 encode concatenated header string
- Hash it using SHA-256 (use the key as secret key). Secret key is shared between GD and Partner
The following is the code snippet in C# to generate signature:
//sortvardict=requestHeaderDictionary.OrderBy(t=>t.Key).ToList();//concatenatevarpairs=dict.Where(p=>(p.Key!=“x-gd-signature”)&&(!string.IsNullOrWhiteSpace(p.Value))).Select(x=>string.Format("{0}{1}{2}",x.Key,":",x.Value));varconcatnatedString=string.Join("&",pairs).ToLower();varencoding=newASCIIEncoding();byte[]secretKeyBytes=encoding.GetBytes(secret);byte[]signature=Encoding.UTF8.GetBytes(concatnatedString);using(varhmac=newHMACSHA256(secretKeyBytes)){byte[]signatureBytes=hmac.ComputeHash(signature);returnstring.Concat(signatureBytes.Select(b=>b.ToString("X2")).ToArray());}Eg:input:Header:{"x-gd-timestamp":"2020-05-22T03:07:53Z","x-gd-encryptiontype":"1","x-gd-requestid":"61aa6e58-b442-4839-8432-948af2fad3c5","x-gd-channeltype":"1","x-gd-devicetype":"2","x-gd-ipaddress":"192.168.1.1","x-gd-programcode":"OneUnited"，x-gd-signature:183A5D41B676865305EC8F807F4BCEDCB03B7F13BC0EAFCB9B24ED7A8BB67BAC}
Sorted/Concatenated data:
Before doing the concatenation/hashing, make sure all the characters are converted to lower case and the strings are trimmed (left/right) for the extra white spaces. Do not include headers that have null/empty values.
“x-gd-channeltype:1&x-gd-devicetype:2&x-gd-encryptiontype:1&x-gd-ipaddress:192.168.1.1&x-gd-programcode:oneunited&x-gd-requestid:61aa6e58-b442-4839-8432-948af2fad3c5&x-gd-timestamp:2020-05-22t03:07:53z”
signature using the sample secret key 'OneUnitedTestSecret':
183A5D41B676865305EC8F807F4BCEDCB03B7F13BC0EAFCB9B24ED7A8BB67BAC
Get stores by zip code
Method: GETURL:~/programs/{programCode}/stores/zipcode/{zipCode}/service-type/{serviceType}~/programs/{programCode}/stores/zipcode/{zipCode}/service-type/{serviceType}/page/{page?}~/programs/{programCode}/stores/zipcode/{zipCode}/service-type/{serviceType}/page/{page}/count/{count?}
Request
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| programCode | string | Yes | The same with header, programcode assigned by Green Dot |
| zipCode | string | Yes | Zip code to search |
| page | int | Optional | Page number,default value '1' |
| count | int | Optional | Records count per page, default value '50' |
| serviceType | int | Yes | Default value '1' for POB (IsCashReload = 1) |
Response
| Parameter | Data Type | Description |
|---|---|---|
| totalCount | int | total store count that returned by the search |
| page | int | page count, default value '1' |
| count | int | recordscount per page, default value '50' |
| storeList | list | store entity list |
| store:retailerName | string | retailer name |
| store:address | string | store address |
| store:phone | string | store phone number |
| store:latitude | decimal | store location latitude |
| store:longitude | decimal | store location longitude |
| store:id | string | store name + store number |
| store:city | string | store location city |
| store:zipCode | string | store location zip code |
| store:state | string | store location state |
| store:distance | decimal | store location distance(The value is 0.0 when search stores by zip code) |
| store:customerFee | decimal | CustomerFee for each retailer |
Get stores by latitude and longitude
Method: GET
URL:
- /programs/{programCode}/stores/latitude/{latitude}/longitude/{longitude}/service-type/{serviceType}
- /programs/{programCode}/stores/latitude/{latitude}/longitude/{longitude}/service-type/{serviceType}/page/{page?}
- /programs/{programCode}/stores/latitude/{latitude}/longitude/{longitude}/service-type/{serviceType}/page/{page}/count/{count?}
Request
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| programCode | string | Yes | The same with header, programcode assigned by Green Dot |
| latitude | decimal | Yes | input latitude |
| longitude | decimal | Yes | input longitude |
| page | int | optional | page number,default value '1' |
| count | int | optional | records count per page,default value '50' |
| serviceType | int | Yes | default value '1' for POB (IsCashReload = 1) |
Response
| Parameter | Data Type | Description |
|---|---|---|
| totalCount | int | total store count that returned by the search |
| page | int | page count, default value '1' |
| count | int | recordscount per page, default value '50' |
| storeList | list | store entity list |
| store:retailerName | string | retailer name |
| store:address | string | store address |
| store:phone | string | store phone number |
| store:latitude | decimal | store location latitude |
| store:longitude | decimal | store location longitude |
| store:id | string | store name + store number |
| store:city | string | store location city |
| store:zipCode | string | store location zip code |
| store:state | string | store location state |
| store:distance | decimal | store location distance(The value is 0.0 when search stores by zip code) |
| store:customerFee | decimal | CustomerFee for each retailer |
Common Response Fields
| Parameter | DataType | Description |
|---|---|---|
| responseDetails | List | responsedetails including errorcodeand descriptions |
| responseDetail:code | Int | Refer to Response error Codes below |
| responseDetail:subCode | Int | Refer to Response error Codes below |
| responseDetail:description | String | Refer to Response error Codes below |
Response Error Code
HttpStatus
| Http Status Code | Description |
|---|---|
| 200 | OK |
| 403 | Forbidden |
| 400 | BadRequest |
| 500 | InternalServerError |
Response Details Code
| Code | Description |
|---|---|
| 0 | Success |
| 950 | Operation Failed |
| 951 | Invalid Request |
| 952 | Rejected |
Response Details Sub Code
| SubCode | Description |
|---|---|
| 0 | Success |
| 601 | System Error |
| 602 | Missing or Invalid Parameter |
Sample
URL: ~/programs/OneUnited/stores/zipcode/91107/service-type/1
Request
Header:{x-gd-timestamp:2022-04-13T01:51:10.1374788Zx-gd-encryptiontype:1x-gd-requestid:61aa6e58-b442-4839-8432-948af2fad3c5x-gd-channeltype:1x-gd-devicetype:1x-gd-ipaddress:127.0.0.1x-gd-programcode:OneUnitedx-gd-signature:52581B4386597112751A1ACC3C28A01B70E4E2F7A381BEAB49F30B2D7ECE708F}
Response
{"responseDetails":[{"code":0,"subCode":0,"description":"Success"}],"page":1,"count":50,"totalCount":11,"storeList":[{"retailerName":"7-Eleven","id":"20269","address":"2717EColoradoBlvd","phone":"6267930102","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.14654300,"longitude":-118.09427400,"distance":0.674053246297448,"customerFee":4.9500},{"retailerName":"Vons","id":"2858","address":"2355EColoradoBlvd","phone":"0000000000","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.14762500,"longitude":-118.10210200,"distance":0.955936510607474,"customerFee":4.9500},{"retailerName":"Walgreens","id":"10764","address":"2376EColoradoBlvd","phone":"6267684040","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.14574900,"longitude":-118.10131300,"distance":1.01134131039383,"customerFee":4.9500},{"retailerName":"Ralphs","id":"37030730","address":"3601EFoothillBlvd","phone":"6263518806","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.15114900,"longitude":-118.07584600,"distance":1.05210307806477,"customerFee":4.9500},{"retailerName":"RiteAid","id":"5535","address":"3745EFoothillBlvd","phone":"6263510515","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.15120600,"longitude":-118.07264900,"distance":1.26748696662016,"customerFee":4.9500},{"retailerName":"7-Eleven","id":"39613","address":"3689EColoradoBlvd","phone":"6265684992","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.14669800,"longitude":-118.07362300,"distance":1.32781775995329,"customerFee":4.9500},{"retailerName":"7-Eleven","id":"25293","address":"1319NAltadenaDr","phone":"6267910279","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.16893300,"longitude":-118.09878300,"distance":1.36687911465109,"customerFee":4.9500},{"retailerName":"DollarTree","id":"5302","address":"181SRosemeadBlvd","phone":"6264630613","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.14320900,"longitude":-118.07375500,"distance":1.47787260954905,"customerFee":1.0000},{"retailerName":"7-Eleven","id":"20297","address":"227SRosemeadBlvd","phone":"6267934744","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.14249500,"longitude":-118.07391100,"distance":1.50681790100164,"customerFee":4.9500},{"retailerName":"CVS","id":"9688","address":"451SSierraMadreBlvd","phone":"6265648681","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.13814600,"longitude":-118.10204900,"distance":1.54396992288177,"customerFee":4.9500},{"retailerName":"CVS","id":"1778","address":"3883EFoothillBlvd","phone":"6263510589","city":"Pasadena","state":"CA","zipCode":"91107","latitude":34.15050800,"longitude":-118.06835500,"distance":1.57017700258762,"customerFee":4.9500}]}
Environments
Updated 2 months ago