Store Service

The store service provides endpoints to obtain information about stores/locations for the merchant.

Endpoints

Get Store Locations Near a Point

GET store/nearbyLocations.json

Obtains information about stores/locations within a certain distance of a mobile device’s location.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • latitude (Decimal) – (required) The latitude (in degrees) around which to center the search. Example: 42.384620
  • longitude (Decimal) – (required) The longitude (in degrees) around which to center the search. Example: -71.205700
  • maxDistance (Decimal) – (required) The maximum distance (in miles) that a store/location can be from the search point (latitude, longitude). Example: 10.0
  • maxLocations (Integer) – (required) The maximum number of stores/locations to return. Example: 15
  • storeGroupCode (Integer) – (optional) Only return stores from this store group. If no code is specified all stores with latitudes and longitudes are candidates Example: 1
"result": "success"
JSON Parameters:
 
  • locations (List[Object]) – (required) A list of locations. See Location for format of the objects.

For example:

{
    "locations": [
        {
            "address": {
                "address1": "1 Main Street",
                "city": "Concord",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02459",
                "stateProvince": "MA"
            },
            "code": "211",
            "distance": "0.4327391103249619",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.380000",
            "longitude": "-71.200000",
            "name": "Concord"
        },
        {
            "address": {
                "address1": "1 Washington Street",
                "city": "Newton",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02458",
                "stateProvince": "MA"
            },
            "code": "1226",
            "distance": "2.1599191167814418",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.357230",
            "longitude": "-71.185340",
            "name": "0226 - Newton"
        },
        {
            "address": {
                "address1": "1 Bear Hill Road",
                "city": "Waltham",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02451",
                "stateProvince": "MA"
            },
            "code": "1235",
            "distance": "3.0819165707759026",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.382100",
            "longitude": "-71.266000",
            "name": "0235 - Waltham"
        }
    ]
}

Get Store Locations Near a Postal Code

GET store/nearbyLocationsForPostalCode.json

Obtains information about stores/locations within a certain distance of a point within the given postal code.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • postalCode (String) – (required) The postal code around which to center the search. Example: 02155
  • maxDistance (Decimal) – (required) The maximum distance (in miles) that a store/location can be from the search point (point within given postal code). Example: 10.0
  • maxLocations (Integer) – (required) The maximum number of stores/locations to return. Example: 15
  • storeGroupCode (Integer) – (optional) Only return stores from this store group. If no code is specified all stores with latitudes and longitudes are candidates Example: 1
"result": "success"
JSON Parameters:
 
  • locations (List[Object]) – (required) A list of locations. See Location for format of the objects.

For example:

{
    "locations": [
        {
            "address": {
                "address1": "1 Main Street",
                "city": "Concord",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02459",
                "stateProvince": "MA"
            },
            "code": "211",
            "distance": "0.4327391103249619",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.380000",
            "longitude": "-71.200000",
            "name": "Concord"
        },
        {
            "address": {
                "address1": "1 Washington Street",
                "city": "Newton",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02458",
                "stateProvince": "MA"
            },
            "code": "1226",
            "distance": "2.1599191167814418",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.357230",
            "longitude": "-71.185340",
            "name": "0226 - Newton"
        },
        {
            "address": {
                "address1": "1 Bear Hill Road",
                "city": "Waltham",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02451",
                "stateProvince": "MA"
            },
            "code": "1235",
            "distance": "3.0819165707759026",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.382100",
            "longitude": "-71.266000",
            "name": "0235 - Waltham"
        }
    ]
}

Get Store Locations in a State or Province

GET store/locationsForStateProvince.json

Obtains information about stores/locations within a specified state/province.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • maxLocations (Integer) – (required) The maximum number of stores/locations to return. Example: 15
  • stateProvince (Decimal) – (required) The two letter state/province code. Example: MA
  • country (String) – (required) The two letter country code. If not specified, it will default to US. Example: US
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • locations (List[Object]) – (required) A list of locations. See Location for format of the objects.

For example:

{
    "locations": [
        {
            "address": {
                "address1": "1 Main Street",
                "city": "Concord",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02459",
                "stateProvince": "MA"
            },
            "code": "211",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.380000",
            "longitude": "-71.200000",
            "name": "Concord"
        },
        {
            "address": {
                "address1": "1 Washington Street",
                "city": "Newton",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02458",
                "stateProvince": "MA"
            },
            "code": "1226",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.357230",
            "longitude": "-71.185340",
            "name": "0226 - Newton"
        },
        {
            "address": {
                "address1": "1 Bear Hill Road",
                "city": "Waltham",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02451",
                "stateProvince": "MA"
            },
            "code": "1235",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.382100",
            "longitude": "-71.266000",
            "name": "0235 - Waltham"
        }
    ]
}

Get Store Locations by Group

GET store/storesByStoreGroup.json

Obtains information about stores/locations within a specified store group.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeGroupCode (Integer) – (required) Paytronix-assigned code for the store group.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • locations (List[Object]) – (required) A list of locations. See Location for format of the objects.

For example:

{
    "locations": [
        {
            "address": {
                "address1": "1 Main Street",
                "city": "Concord",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02459",
                "stateProvince": "MA"
            },
            "code": "211",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.380000",
            "longitude": "-71.200000",
            "name": "Concord"
        },
        {
            "address": {
                "address1": "1 Washington Street",
                "city": "Newton",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02458",
                "stateProvince": "MA"
            },
            "code": "1226",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.357230",
            "longitude": "-71.185340",
            "name": "0226 - Newton"
        },
        {
            "address": {
                "address1": "1 Bear Hill Road",
                "city": "Waltham",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02451",
                "stateProvince": "MA"
            },
            "code": "1235",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.382100",
            "longitude": "-71.266000",
            "name": "0235 - Waltham"
        }
    ]
}

Get Store Details

GET store/store.json

Obtains information about a single store/location for the specified merchant.

The store is identified by either a Paytronix-assigned code like:

"storeIdentity": { "code": "123456" }

or a customer-assigned externalStoreNumber like:

"storeIdentity": { "externalStoreNumber": "ABC789" }

For a GET REST call you format the request like: https://.../store.json?merchantId=123&storeIdentity.code=123ABC or https://.../store.json?merchantId=123&storeIdentity.externalStoreNumber=123ABC

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeIdentity (Object) – (required) an object that identifies the store. See description above.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • location (Object) – (required) A single location. See Location for format of the object.

For example:

{
    "location":
        {
            "address": {
                "address1": "1 Main Street",
                "city": "Concord",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02459",
                "stateProvince": "MA"
            },
            "code": "211",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.380000",
            "longitude": "-71.200000",
            "name": "Concord"
        }
}

Get All Store Locations for a Merchant

GET store/stores.json

Obtains information about all stores/locations for the specified merchant.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • locations (List[Object]) – (required) A list of locations. See Location for format of the objects.

For example:

{
    "locations": [
        {
            "address": {
                "address1": "1 Main Street",
                "city": "Concord",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02459",
                "stateProvince": "MA"
            },
            "code": "211",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.380000",
            "longitude": "-71.200000",
            "name": "Concord"
        },
        {
            "address": {
                "address1": "1 Washington Street",
                "city": "Newton",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02458",
                "stateProvince": "MA"
            },
            "code": "1226",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.357230",
            "longitude": "-71.185340",
            "name": "0226 - Newton"
        },
        {
            "address": {
                "address1": "1 Bear Hill Road",
                "city": "Waltham",
                "country": "US",
                "phone": "6175551212",
                "postalCode": "02451",
                "stateProvince": "MA"
            },
            "code": "1235",
            "hoursOfOperation": "M-F: 9-5, Sat: 8-8, Sun: closed",
            "latitude": "42.382100",
            "longitude": "-71.266000",
            "name": "0235 - Waltham"
        }
    ]
}

Reply Objects

Location

Location details.

JSON Parameters:
 
  • name (String) – (required) Human readable label for the store/location which may change over time. Should only be used for display to a user, as the name might change from time to time.
  • code (String) – (required) Code for the store/location. This will never change for a particular location unless Paytronix is requested by the merchant to make a specific change to do so. This code can be used as inputs to other REST endpoints such as Checkin.
  • externalStoreNumber (String) – (required) A customer-assigned code/number for the store/location.
  • address ([Object]) – (required) The address of the store/location. See Address for format of the objects.
  • hoursOfOperation (String) – (required) A comma-separated list of days/times that the store/location is open. Example: M-F: 9-5, Sat: 8-8, Sun: closed
  • latitude (Decimal) – (required) The latitude (in degrees) of the store/location. Example: 42.384620
  • longitude (Decimal) – (required) The longitude (in degrees) of the store/location. Example: -71.205700
  • distance (Decimal) – (required) If the latitude & longitude of the device were provided as arguments to the endpoint, then the distance (in miles) from the device to the store/location will be returned. Example: 0.4327391103249619
Address

Address details.

JSON Parameters:
 
  • address1 (String) – (required) The first line of the address. Example: 123 Main St
  • address2 (String) – (required) The second line of the address. Example: Apt 456
  • city (String) – (required) The city of the address. Example: Boston
  • stateProvince (String) – (required) The two letter state/province code of the address. Example: MA
  • postalCode (String) – (required) The US ZIP Code or Canadian Province Code of the address. Example: 02111
  • country (String) – (required) The two letter country code of the address. Example: US
  • phone (String) – (required) The phone number of the address. Example: 6175551212

Error Codes

The following are the possible codes and messages that can be returned by the Store Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
store.store_not_found Store not found
store.store_closed Store closed
store.invalid_store_group_code Invalid store group code
store.store_group_not_found Store group not found
store.invalid_merchant_id Invalid merchant ID
store.invalid_country Invalid country code
store.invalid_state_province Invalid state/province code
store.server_error Internal server error