Region Event Service

The region event service provides endpoints which handle boundary crossing events for a devices monitored regions.

Endpoints

Get Region Definitions

GET regionevent/regionDefinitions.json

region_event_post must be included in the scope for the initial access token negotiated in the oauth/requestGuestToken request. regionevent/regionDefinitions.json obtains a list of regions based on the latitude and longitude of the favorite store of the card number queried, or enrollment store if no favorite store is set. The user’s device should attempt to monitor the locations returned. Additionally, this method provides a special OAuth token that should be used to authenticate Post Region Event calls. This token does not expire.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) The card of the user.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • regionEventAccessToken (String) – (required) A token used for authenticating with Post Region Event endpoint.
  • geoRegions (List[Object]) – (required) See RegionDefinition for format of the objects.

Example GET request to GET regionevent/regionDefintions.json:

https://api.staging.paytronix.com:1283/rest/24.25/regionevent/regionDefintions.json?access_token=CjyxRJwTbA26_gUP__O6jUk1pbErFrxgQ90UYMcL01&printedCardNumber=60000300000095362&authentication=oauth&merchantId=30

Example Response

{
    "result": "success",
    "regionEventAccessToken": "CSDKs2839dfj_dfsd_fweiw9f823jSADlks9d832sa",
    "geoRegions": [
        {
            "coordinates": {
                "latitude":"44.419069",
                "longitude":"-72.015510"
            },
            "regionType":"storeCode",
            "radius":500,
            "storeCode":"abc3"
        },
        {
            "coordinates": {
                "latitude":"42.344748",
                "longitude":"-71.205246"
            },
            "regionType":"storeCode",
            "radius":500,
            "storeCode":"2"
        }
    ]
}

Post Region Event

POST regionevent/regionEvent.json

Endpoint to call when a user crosses a monitored region boundary. When authenticating with oauth, the client should pass the token recieved from the last call to Get Region Definitions.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) The card of the user.
  • coordinates (Object) – (optional) The current location of the user.
  • regionEventType (String) – (required) Possible values: ENTER or EXIT indicating whether a user has entered or left a region.
  • region (Object) – (required) The identifier of the subject region. See RegionIdentity
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • message (String) – (optional) The message to be displayed to the user. If this field is not included in the response, a message should not be displayed

Example Request Body

{
    "merchantId": 30,
    "access_token": "CSDKs2839dfj_dfsd_fweiw9f823jSADlks9d832sa",
    "printedCardNumber": "60000300000095362",
    "coordinates": {
        "latitude":"43.3942918",
        "longitude":"-67.0680837"
    },
    "regionEventType": "ENTER",
    "region": {
        "regionType":"storeCode",
        "storeCode":"1"
    }
}

Example Response with a message

{
    "result": "success",
    "message": "Need a pick-me-up? Check out JK Cafe's delicious pastries!"
}

And without a message it is simply

{
    "result": "success"
}

Reply Objects

RegionDefinition
JSON Parameters:
 
  • regionType (String) – (required) storeCode
  • storeCode (String) – (required) The unique code of the store at this region.
  • coordinates (Object) – (required) The coordinates the region is centered at. See Coordinates
  • radius (Integer) – (required) The radius of this region measured in meters.
Coordinates
JSON Parameters:
 
  • latitude (Decimal) – (required) The latitude of a coordinate pair.
  • longitude (Decimal) – (required) The latitude of a coordinate pair.
RegionIdentity
JSON Parameters:
 
  • regionType (String) – (required) storeCode
  • storeCode (String) – (required) The unique code of the store at this region.

Error Codes

Typically there is little user recourse for errors returned by the Region Event Service and most calls will happen in the background to the user, so it is not useful to display an error to the user. That said, the errorMessage field should be suitable for displaying to an end user and the errorCode is suitable for mapping your own error message to display.

Code Message
regionevent.server_error Unable to process this region event request
regionevent.auth_error Integration not authorized for merchant
regionevent.unknown_region Did not recognize designated region
regionevent.no_time_zone Unable to determine time zone
regionevent.not_configured This feature has not been fully configured
regionevent.server_error Unable to process region defintions request
regionevent.not_configured This feature has not been fully configured
regionevent.no_guest_neighborhood Unable to determine guest neighborhood