Commerce API

Get Available Remote Locations

Get available mobile locations

POST /api/v2/getLocations

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES	Session Token
latitude	number	YES	Current latitude position
longitude	number	YES	Current longitude position
auto_renew_session	boolean	NO	Set true if you want to automatically renew session_id token
device_id	string	Only if auto_renew_session is set to true	Device ID for renewing session_id token
pin	number(4)	Only if auto_renew_session is set to true	PIN set for Device when logging into app. See /createPIN for additional details

IMPORTANT

You must provide device_id and pin if auto_renew_session is set to true, otherwise feel free to ignore.

Success Response

{
	"response": [
		{
			"locationId": "{LOCATION-ID-NUMBER}",
			"name": "{LOCATION-NAME}",
			"type": "Normal",
			"latitude": 42.000000000,
			"longitude": -71.000000000,
			"distance": 0.0,
			"color": "#0099cc",
			"score": 20.0
		},
        // other locations, same JSON structure
    ],
	"exception": null,
	"autoRenewConfig": {
		"sessionIdChanged": true,
		"token": "{RENEWED_SESSION_ID}"
	}
}

NOTE

Not entirely sure what type, color, or score represent.

IMPORTANT

Here, autoRenewConfig is directly accessible in the JSON Response Object unlike the other responses you'll see below. Additionally, note that if sessionIdChanged is false, you'll have the same token (aka session_id) returned.

Failure Response

WA001: Device ID and PIN Missing

Make sure you have set device_id and pin. This error is triggered when auto_renew_session is true but missing parameters in the response.

{ 
    "response": null,
    "exception": "WA001: Device ID and PIN Required" 
}

Activate Remote Locations

Remotely activate a mobile location

POST /api/v2/activateLocation

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES	Session Token
latitude	number	YES	Current latitude position
longitude	number	YES	Current longitude position
location_id	number	YES	Location ID of Location attempting to be activated. See Get Available Locations for getting available locations
auto_renew_session	boolean	NO	Set true if you want to automatically renew session_id token
device_id	string	Only if auto_renew_session is set to true	Device ID for renewing session_id token
pin	number(4)	Only if auto_renew_session is set to true	PIN set for Device when logging into app. See /createPIN for additional details

Success Response

{
	"response": {
		"validityTime": null,
		"showBarCode": null,
		"showTempCode": null,
		"message": "Request Approved. Check the door.",
		"issuedCode": null,
		"responseCode": "00",
		"issueDate": null,
		"autoRenewConfig": {
            "sessionIdChanged": true,
            "token": "{session_id}"
        }
	},
	"exception": null
}

NOTE

Note the autoRenewConfig key has moved to be a key under response.

Failure Response

WA001: Device ID and PIN Missing

Make sure you have set device_id and pin. This error is triggered when auto_renew_session is true but missing parameters in the response.

{ 
    "response": null,
    "exception": "WA001: Device ID and PIN Required" 
}

98: Not Within Distance of Reader

{
	"response": {
		"validityTime": null,
		"showBarCode": null,
		"showTempCode": null,
		"message": "Denied - Not within distance of reader",
		"issuedCode": null,
		"responseCode": "98",
		"issueDate": null
	},
	"exception": null
}

TIP

Technically, you can just send the location of the reader as your current location. For security reasons, you probably should not do this.

NOTE

There does exist, at least, 1 other error code, however I haven't been able to reproduce it to document it.

Get Student Account Balances

Get Student Accounts (Meal Plan Swipes, Guest Swipes, Dining Dollars etc) with Current Balances.

POST /api/v2/getAccounts

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES	Session Token
auto_renew_session	boolean	NO	Set true if you want to automatically renew session_id token
device_id	string	Only if auto_renew_session is set to true	Device ID for renewing session_id token
pin	number(4)	Only if auto_renew_session is set to true	PIN set for Device when logging into app. See /createPIN for additional details

Success Response

{
	"response": {
		"accounts": [
			{
				"id": "T:2:{USER_ID}:{accountTender}",
				"institutionId": "{INSTITUTION_ID}",
				"paymentSystemId": "{PAYMENT_SYSTEM_ID}",
				"userId": "{USER_ID}",
				"isActive": true,
				"accountDisplayName": "{accountDisplayName}",
				"paymentSystemType": 2,
				"accountTender": "{accountTenderNumber}",
				"isAccountTenderActive": true,
				"accountType": 3, // can be 1, 2, 3 (possibly more?)
				"depositAccepted": true,
				"lastFour": null,
				"nameOnMedia": null,
				"expirationMonth": null,
				"expirationYear": null,
				"billingAddressId": null,
				"balance": 300.00
			},
            // other accounts
		],
		"planName": null,
		"autoRenewConfig": {
            "sessionIdChanged": true,
            "token": "{session_id}"
        }
	},
	"exception": null
}

INFO

The key response.accounts[i].accountType seems to be used to determine the associated strings. Thus far, 1 represents Meal Swipes, 2 is unknown, 3 represents dollars ($).

Failure Response

WA001: Device ID and PIN Missing

Make sure you have set device_id and pin. This error is triggered when auto_renew_session is true but missing parameters in the response.

{ 
    "response": null,
    "exception": "WA001: Device ID and PIN Required" 
}

Get Student Account Transactions

Retrieves Transactions

POST /api/v2/getTransactions

Request Parameters

Body Parameters	Type	Required	Description
session_id	string	YES	Session Token
maxReturnCount	number	NO	Maximum Number of Transaction Records to Return. Defaults to 75 if unconfigured.
oldestDate	string	NO	Oldest Transaction Record Date
newestDate	string	NO	Newest Transaction Record Date
accountId	string	NO	Filters Transactions By Account ID
auto_renew_session	boolean	NO	Set true if you want to automatically renew session_id token
device_id	string	Only if auto_renew_session is set to true	Device ID for renewing session_id token
pin	number(4)	Only if auto_renew_session is set to true	PIN set for Device when logging into app. See /createPIN for additional details

Success Response

{
	"response": {
		"totalCount": 0,
		"returnCapped": false,
		"transactions": [
			{
				"transactionId": "{TRANSACTION_ID}",
				"transactionSequence": 1,
				"transactionType": 1,
				"amount": 1.00,
				"resultingBalance": 100,
				"postedDate": "2024-12-11T23:54:04.000+0000",
				"actualDate": "2024-12-11T23:54:03.000+0000",
				"patronId": "{PATRON_ID}",
				"planId": "",
				"tenderId": "000000119",
				"locationId": "{LOCATION_ID}",
				"locationName": "{STORE_MERCHANT_NAME}",
				"patronFullName": "{FULL_NAME}",
				"accountType": 3,
				"accountName": "{ACCT_NAME}",
				"paymentSystemType": 2,
				"transactionKey": "{TRANSACTION_ID}.1"
			},
			...
		],
		"autoRenewConfig": {
            "sessionIdChanged": true,
            "token": "{NEW_SESSION_ID_IF_sessionIdChanged_TRUE}"
        }
	},
	"exception": null
}

TIP

Do not rely on response.totalCount as that doesn't seem to be accurate (unless the list of transaction is 0). Just get the length of response.transactions if you need the count, or specify a maxReturnCount, though that doesn't fix the issue of response.totalCount being 0.

NOTE

It seems response.transaction[*].transactionType can have the following values: 1, 3, and 4. There might be more, but so far, that's all I can verify.
1: Regular Spending Transactions
3: Deposits into Account
4: Automated Deductions from Account (i.e expired funds that are unused at end of semester etc)