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:

Query 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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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"
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        }
    ]
}

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:

Query 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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        }
    ]
}

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:

Query 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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        }
    ]
}

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:

Query 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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        }
    ]
}

Get Store Details

GET store/store.json

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

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:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeIdentity (Object) – (required) An object that identifies the store. See StoreIdentity
"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",
            "metadata": [{"hasRedBox": true}]
        }
}

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:

Query 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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        },
        {
            "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",
            "metadata": [{"hasRedBox": true}]
        }
    ]
}

Create a Store

POST store/createStore.json

Create a new store.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • billingContactInfo (String) – (required) Contact information for a contact that can help the Px billing department set up ACH information. Can be a phone number, email, etc.
  • input (CreateStoreAttributes) – (required) See CreateStoreAttributes

Example of request:

{
     "authentication": "b2b",
     "client_id": "...",
     "client_secret": "...",
     "merchantId": 123,
     "input": {
         "name": "1234 - Newton",
         "storeCode": "001"
         "hoursOfOperation": "M-F: 8-4, Sat-Sun: closed",
         "latitude": 42.382100,
         "longitude": -71.266000,
         "metadata": {"hasRedBox":false},
         "address1": "2 Bear Hill Road",
         "city": "Waltham",
         "stateProvince": "MA",
         "postalCode": "02459",
         "timeZone": "Eastern Time",
         "phone": "6175551212",
         "fax": "8888888888",
         "platformEnumId": 10,
         "externalStoreNumber": "...",
         "odStoreId": "...",
         "billingContactInfo": "[email protected]"
    }
}
"result": "success"

Example:

{ "result": "success" }
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Edit a Store

POST store/editStore.json

Edit information of a specific store.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeIdentity (StoreIdentity) – (required) An object that identifies the store. See StoreIdentity
  • input (EditableStoreAttributes) – (required) See EditableStoreAttributes

Example of request:

{
     "authentication": "b2b",
     "client_id": "...",
     "client_secret": "...",
     "merchantId": 123,
     "storeIdentity": {
         "code": "123456"
     },
     "input": {
         "name": "1234 - Newton",
         "hoursOfOperation": ["M-F: 8-4, Sat-Sun: closed"],
         "latitude": [42.382100],
         "longitude": [-71.266000],
         "metadata": [{"hasRedBox":false}],
         "address1": "2 Bear Hill Road",
         "city": "Waltham",
         "stateProvince": ["MA"],
         "postalCode": "02459",
         "timeZone": "Eastern Time",
         "phone": ["6175551212"],
         "fax": ["8888888888"]
    }
}
"result": "success"

Example:

{ "result": "success" }
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Update Store Metadata

POST store/updateMetadata.json

Update the metadata information for a specific store.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeIdentity (StoreIdentity) – (required) An object that identifies the store. See StoreIdentity
  • metadata (EditableStoreAttributes) – (required) See EditableStoreAttributes. The EditableStoreAttributes object in this call should only have a value in the metadata field. Any other field that is filled out for this object will be ignored by the endpoint. metadata should be a list containing one JSON object.

Example of request:

{
     "authentication": "b2b",
     "client_id": "...",
     "client_secret": "...",
     "merchantId": 123,
     "storeIdentity": {
         "code": "123456"
     },
     "metadata": {
         "metadata": [
             {
                 "hasRedBox":false,
                 "fuelPrices": {
                     "regular": 3.00,
                     "premium": 3.50
                 }

             }
         ],
    }
}
"result": "success"

Example:

{ "result": "success" }
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

The

Response Objects

CreateStoreAttributes
JSON Parameters:
 
  • name (String) – (required) Human readable label of the store/location.
  • storeCode (String) – (required) Unique store identifier for the merchant.
  • hoursOfOperation (String) – (optional) A comma-separated list of days/times that the store/location is open. Example: M-F: 9-5, Sat: 8-8, Sun: closed
  • latitude (BigDecimal) – (optional) The latitude (in degrees) of the store/location. Example: 42.384620
  • longitude (BigDecimal) – (optional) The longitude (in degrees) of the store/location. Example: -71.205700
  • metadata (JObject) – (optional) Additional information about the store/location, must be a valid json string. Example: {"hasRedBox": true}
  • address1 (String) – (required) The first line of the address. Example: 123 Main St
  • city (String) – (required) The city of the address. Example: Boston
  • stateProvince (String) – (optional) The two letter state/province code of the address. Example: MA
  • country (String) – (required) Allowed values are US and CA
  • postalCode (String) – (required) The US ZIP Code or Canadian Province Code of the address. Example: 02111
  • timeZone (String) – (required) The time zone name of the address. Example Eastern Time
  • phone (String) – (optional) The phone number of the address. Example: 6175551212
  • fax (String) – (optional) The fax number of the address. Example: 6175551212
  • externalStoreNumber (String) – (optional) The externalStoreNumber of the restaurant. For Toast, this must be set to the Toast store id. Example: 21801421-f145-58d8-ba8c-29e57a31929b
  • posMappingGroupCode (String) – (required) The POS Mapping group code for the default POS mapping group to which to link this store. To use the default POS mapping group, use code 0. Example: 0
  • platformEnumId (String) – (optional) The platformEnumId to which to link the store. This is an internal value and can be left blank if unknown. Example: 12
  • odStoreId (String) – (optional) The unique Online Ordering store identifier. Example: 5099803df3f4948bd2f98391
EditableStoreAttributes
JSON Parameters:
 
  • name (String) – (optional) Human readable label of the store/location.
  • storeCode (String) – (optional) Unique store identifier for the merchant.
  • hoursOfOperation (String) – (optional) A comma-separated list of days/times that the store/location is open, can be unset. Example: [M-F: 9-5, Sat: 8-8, Sun: closed]
  • latitude (BigDecimal) – (optional) The latitude (in degrees) of the store/location, can be unset. Example: [42.384620]
  • longitude (BigDecimal) – (optional) The longitude (in degrees) of the store/location, can be unset. Example: -71.205700
  • metadata (JObject) – (optional) Additional information about the store/location, must be a valid json string and can be unset. Example: [{"hasRedBox": true}]
  • address1 (String) – (optional) The first line of the address. Example: 123 Main St
  • city (String) – (optional) The city of the address. Example: Boston
  • country (String) – (optional) Allowed values are US and CA
  • stateProvince (String) – (optional) The two letter state/province code of the address, can be unset. Example: [MA]
  • postalCode (String) – (optional) The US ZIP Code or Canadian Province Code of the address. Example: 02111
  • timeZone (String) – (optional) The time zone name of the address. Example Eastern Time
  • phone (String) – (optional) The phone number of the address, can be unset. Example: [6175551212]
  • fax (String) – (optional) The fax number of the address, can be unset. Example: [6175551212]
StoreIdentity

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

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

a customer-assigned externalStoreNumber like:

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

a Paytronix Online Ordering assigned odStoreId like:

"storeIdentity": { "odStoreId": "odId123" }

or a yextStoreCode like:

"storeIdentity": { "yextStoreCode": "yextCode1a2b3c" }

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) – (optional) A customer-assigned code/number for the store/location.
  • address ([Object]) – (required) The address of the store/location. See AddressStoreService for format of the objects.
  • hoursOfOperation (String) – (optional) A comma-separated list of days/times that the store/location is open. Example: M-F: 9-5, Sat: 8-8, Sun: closed
  • metadata (JValue) – (required) A json-blob that consists of additional information about the store/location. Example: [{"hasRedBox": true}]
  • latitude (Decimal) – (optional) The latitude (in degrees) of the store/location. Example: 42.384620
  • longitude (Decimal) – (optional) The longitude (in degrees) of the store/location. Example: -71.205700
  • distance (Decimal) – (optional) 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
  • isPayByMobileActive (Boolean) – (required) Whether or not this location supports mobile payments.
AddressStoreService

Address details.

JSON Parameters:
 
  • address1 (String) – (optional) The first line of the address. Example: 123 Main St
  • address2 (String) – (optional) The second line of the address. Example: Apt 456
  • city (String) – (optional) The city of the address. Example: Boston
  • stateProvince (String) – (optional) The two letter state/province code of the address. Example: MA
  • postalCode (String) – (optional) The US ZIP Code or Canadian Province Code of the address. Example: 02111
  • country (String) – (optional) The two letter country code of the address. Example: US
  • phone (String) – (optional) 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
store.non_unique_store_name Store name must be unique
store.invalid_scale Invalid latitude/longitude scale
store.invalid_input Invalid input
store.invalid_json Invalid json
store.invalid_state_country_combination Invalid state country combination
store.input_too_short Value length too short
store.input_too_long Value length too long
store.out_of_range Invalid latitude/longitude range
store.unable_insert_store Unable to insert store.
store.unable_to_find_pos_mapping_group Unable to find POS mapping group.
store.unable_to_send_billing_email Unable to send billing email.
store.no_billing_recipient Billing email recipient not configured.