Appearance
Commerce
Service path: /json/commerce
Commerce covers accounts (meal plans, charge accounts, declining balance, Apple Pay), deposits, transaction history, and donations.
Get Accounts
Returns every cashless account the user can see, including balances.
plaintext
POST /json/commerce
method: retrieveAccountsParameters
No business parameters; the session identifies the user.
json
{
"method": "retrieveAccounts",
"params": {
"sessionId": "{SESSION_ID}",
"institutionId": "{INSTITUTION_UUID}"
}
}Success Response
json
{
"response": {
"accounts": [
{
"id": "{ACCOUNT_ID}",
"accountDisplayName": "Meal Plan",
"accountType": 1,
"balance": 250.0,
"paymentSystemType": 1,
"isFavorite": false
}
]
},
"exception": null
}accountType:
| Value | Name | Meaning |
|---|---|---|
1 | MEALS | Meal-plan swipes / meal points |
2 | CHARGE | Charge account (must be paid) |
3 | DECLINING_BALANCE | Prepaid declining balance |
4 | APPLEPAY | Apple Pay funding source |
paymentSystemType (OPCS = 1, CSGOLD = 2, MONETRA = 3, USAEPAY = 4) tells you which processor backs the account. MONETRA and USAEPAY are credit-card systems; OPCS and CSGOLD are campus card systems.
What the app shows
retrieveAccounts returns everything the user can see, but the app filters it per screen:
| Screen | Filter |
|---|---|
| Accounts tile / account list | paymentSystemType ∈ {OPCS, CSGOLD} and accountTender ∈ get.feature.display_tenders |
| Deposit "to" picker | paymentSystemType ∈ {OPCS, MONETRA} (default) and accountTender ∈ get.feature.deposit_tenders |
| Meal donation picker | accountTender ∈ get.meal_donation.tenders |
get.feature.display_tenders / get.feature.deposit_tenders are comma-separated tender ids or JSON arrays; the app splits them with the same tolerant helper it uses for other list settings. Accounts whose accountTender is not in the list are silently hidden.
Account object
| Field | Type | Notes |
|---|---|---|
id | string | Account id used everywhere else. |
accountDisplayName | string | Name to show. |
accountType | number | See enum above. |
accountTender | string | Tender name/id used by the tender filters and by meal donations. |
balance | number | Current balance. Meal accounts show a count, not currency. |
paymentSystemType | number | Processor backing the account. |
depositAccepted | boolean | Whether the account can receive deposits (used by deposit destination filters). |
isFavorite | boolean | Optional; the account screens do not read it (merchant favorites use their own field). |
planName | string | Present on the retrieveAccounts response, not per account. |
NOTE
retrieveAccounts also returns a top-level planName describing the user's meal plan; the app caches it and shows it above the account list. It is not part of any account.
Deactivate an Account
Hides an account from the wallet view. The app spreads the full account object into the params.
plaintext
POST /json/commerce
method: deactivateAccountjson
{
"method": "deactivateAccount",
"params": {
"id": "{ACCOUNT_ID}",
"accountDisplayName": "Meal Plan",
"accountType": 1,
"balance": 250.0,
"paymentSystemType": 1,
"sessionId": "{SESSION_ID}"
}
}Get the Displayed Patron ID
Returns the value the app prints as
ID: ...on the barcode / access screens.
plaintext
POST /json/commerce
method: retrieveCashlessPatronMobileDisplayMediaValuejson
{
"method": "retrieveCashlessPatronMobileDisplayMediaValue",
"params": { "sessionId": "{SESSION_ID}" }
}No parameters beyond the session. Response is a string.
The value is rendered as ID: <value> under the patron's name, and only when get.feature.mobile_patron_cashless_display_media_type is non-empty. It is the institution-configured display value — typically their own identifier (student/staff number), which is why it is labelled "display media value".
IMPORTANT
This is not the value used to generate the barcode. Barcode generation reads the user setting CashlessKey (user.retrieveSetting { "settingName": "CashlessKey" }), which is the CBORD-assigned patron key. The two are fetched from different endpoints and are different identifiers: the display value is the institution's own label (verified: a university student ID), which has no required relationship to the patron key. See SOA Barcode.
Transaction History
Recent / paged transactions
plaintext
POST /json/commerce
method: retrieveTransactionHistoryTransactions within a date range
plaintext
POST /json/commerce
method: retrieveTransactionHistoryWithinDateRangeBoth take the same parameters. paymentSystemType is always sent as 0 by the app.
| Field | Type | Required | Description |
|---|---|---|---|
paymentSystemType | number | YES | 0 in the app. |
queryCriteria | object | YES | Query object, see below. |
sessionId | string | YES | User session (injected). |
queryCriteria:
| Field | Type | Description |
|---|---|---|
accountId | string | null | Account to filter on; null means all accounts. |
newestDate | string | Upper bound (ISO date). |
oldestDate | string | Lower bound (ISO date). |
maxReturnMostRecent | number | Page size. The app uses 20, or 0 for unlimited. |
The account picker uses the literal sentinel all_accounts; the app converts it to accountId: null before sending. The date picker offers two presets:
| Preset | oldestDate |
|---|---|
past_six_month (default) | now − 6 months |
past_month | now − 1 month |
The dashboard's "recent activity" strip calls with maxReturnMostRecent: 0 (unlimited); the full transaction screen starts at 20 and pages.
json
{
"method": "retrieveTransactionHistoryWithinDateRange",
"params": {
"paymentSystemType": 0,
"queryCriteria": {
"accountId": "{ACCOUNT_ID}",
"newestDate": "2026-11-19T00:00:00.000Z",
"oldestDate": "2026-05-19T00:00:00.000Z",
"maxReturnMostRecent": 20
},
"sessionId": "{SESSION_ID}"
}
}Response:
json
{
"response": {
"transactions": [
{
"actualDate": "2026-11-18T12:34:56",
"description": "Dining Hall",
"amount": -12.5,
"balance": 237.5,
"accountId": "{ACCOUNT_ID}",
"paymentSystemType": 1,
"tenderId": "{TENDER_ID}"
}
],
"totalCount": 1
},
"exception": null
}TIP
The app paginates by repeatedly calling with newestDate set to the earliest date it has already shown and maxReturnMostRecent: 20. totalCount in the first response is used to decide whether more pages exist.
The app also filters transactions by the institution's get.feature.display_tenders setting: transactions whose paymentSystemType is MONETRA / USAEPAY, or whose tenderId is in the allowed list, are shown.
Calculate a Deposit Fee
Returns any fee that would be charged for a deposit before it is made.
plaintext
POST /json/commerce
method: calculateDepositFee| Field | Type | Required | Description |
|---|---|---|---|
fromAccountId | string | YES | Funding account (credit card / Apple Pay). |
toAccountId | string | YES | Destination account. |
amount | number | YES | Deposit amount. |
json
{
"method": "calculateDepositFee",
"params": {
"fromAccountId": "{FROM_ACCOUNT_ID}",
"toAccountId": "{TO_ACCOUNT_ID}",
"amount": 25,
"sessionId": "{SESSION_ID}"
}
}Deposit Funds
plaintext
POST /json/commerce
method: deposit| Field | Type | Required | Description |
|---|---|---|---|
fromAccountId | string | YES | Funding account. |
toAccountId | string | YES | Destination account. |
fromAccountCvv | string | null | NO | CVV for credit-card funding. |
amount | number | YES | Amount. |
cashlessTerminalLocation | null | NO | Always null in the app. |
json
{
"method": "deposit",
"params": {
"fromAccountId": "{CREDIT_ACCOUNT_ID}",
"toAccountId": "{DEST_ACCOUNT_ID}",
"fromAccountCvv": "123",
"amount": 25,
"cashlessTerminalLocation": null,
"sessionId": "{SESSION_ID}"
}
}Typical failures: InsufficientFundsException, MediaLostException, PaymentSystemGatewayException, TransactionCountExceededException.
Deposit to Another User
Deposits into another patron's account, funding from any of the caller's accounts.
plaintext
POST /json/commerce
method: depositForUserFromAnyAccount| Field | Type | Required | Description |
|---|---|---|---|
userId | string | YES | Recipient user id. |
fromAccountId | string | YES | Caller's funding account. |
fromAccountCvv | null | NO | Always null in the app. |
toAccountId | string | YES | Recipient account. |
amount | number | YES | Amount. |
cashlessTerminalLocation | null | NO | Always null. |
NOTE
This call is flagged useInstitutionId = false, so only sessionId is injected.
Retrieve Accounts for a User
plaintext
POST /json/commerce
method: retrieveAccountsByUserjson
{
"method": "retrieveAccountsByUser",
"params": { "userId": "{USER_ID}", "sessionId": "{SESSION_ID}" }
}Response is { accounts: [...] } (the app unwraps response.accounts).
Retrieve Deposit Accounts for a User
plaintext
POST /json/commerce
method: retrieveDepositAccountsByUserSame shape as above; returns only accounts that can receive deposits.
Donate Meal Swipes
plaintext
POST /json/commerce
method: donate| Field | Type | Required | Description |
|---|---|---|---|
accountId | string | YES | Meal account to donate from. |
amountToDonate | number | YES | Number of meals or dollar amount, depending on institution config. |
json
{
"method": "donate",
"params": {
"accountId": "{MEAL_ACCOUNT_ID}",
"amountToDonate": 1,
"sessionId": "{SESSION_ID}"
}
}Create a Credit Card Account
Stores a new credit-card payment method.
plaintext
POST /json/commerce
method: createAccount| Field | Type | Required | Description |
|---|---|---|---|
accountInfo | object | YES | Card / billing details. |
The object the app builds (MediaService.createAccount):
json
{
"method": "createAccount",
"params": {
"accountInfo": {
"accountDisplayName": "Visa ending 4242",
"nameOnMedia": "ADA LOVELACE",
"paymentSystemType": null,
"accountTender": "Visa",
"mediaValue": "4242424242424242",
"mediaEntryMethod": 1,
"mediaSecurityCode": "123",
"expirationMonth": "12",
"expirationYear": "2030",
"usePatronEmail": false,
"billingAddress": { },
"externalAccountToken": null,
"externalTransactionToken": null
},
"sessionId": "{SESSION_ID}"
}
}| Field | Notes |
|---|---|
mediaValue | The raw card number. This is what the server receives — the client does not tokenise on the MONETRA path. |
mediaSecurityCode | CVV. |
mediaEntryMethod | 1 for manual/keyed entry. |
paymentSystemType | Sent as null; the server decides from the tender. The app's constant is MONETRA = 3, USAEPAY = 4. |
expirationMonth / expirationYear | Strings, exactly as typed into the two fields. |
externalAccountToken / externalTransactionToken | Populated only on the USAePay native-tokenisation path; otherwise null. |
WARNING
Card detection is client-side only: the app tests the PAN prefix (4 → Visa, MasterCard pattern → MasterCard) and runs no Luhn check. See Security Notes #9.
Automatic Deposit Accounts
Lists the accounts eligible to fund an automatic deposit for a given payment type.
plaintext
POST /json/commerce
method: retrieveAutoDepositAccountList| Field | Type | Required | Description |
|---|---|---|---|
userId | string | YES | Current user id. |
paymentType | number | YES | 1 credit, 2 bill-me. |
json
{
"method": "retrieveAutoDepositAccountList",
"params": {
"userId": "{USER_ID}",
"paymentType": 1,
"sessionId": "{SESSION_ID}"
}
}The app calls this once for each value in the institution setting get.deposit.auto_deposit_payment_types and merges the results into the payment-method picker. The response is the eligible account list (account objects use the same field names as retrieveAccounts).
NOTE
This method is flagged useSessionId = true but not useInstitutionId.
Meal Plan Change / Purchase
Not an API call. The app opens a CBORD-hosted web page in the in-app browser with the current session token.
plaintext
GET {sites_url}/{institutionShortName}/full/link_in.php
?session_token={AUTH_TOKEN}
&target=change_meal_plan
&sa=1| Target | Shown when |
|---|---|
change_meal_plan | get.feature.enable_change_meal_plan = "1" (and the user is not a guest) |
purchase_meal_plan | get.feature.enable_purchase_meal_plan = "1" |
The session token is the value from getAuthenticationToken (see Authentication). The page is opened with _blank and browser chrome disabled; it handles the actual plan change or purchase server-side and returns to the app.
NOTE
Both settings are under get.feature, not get.meal_plan. The get.meal_plan category exists in the app's setting enum but no additional keys are read from it.
Retrieve Accepted Credit Payment Methods
Returns the credit card brands/types the institution accepts for a payment system.
plaintext
POST /json/commerce
method: retrieveCreditPaymentMethodsByPaymentSystem| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | YES | Explicit session id. |
paymentSystemId | string | YES | Payment system id, or "". |
userId | string | YES | User id. |
json
{
"method": "retrieveCreditPaymentMethodsByPaymentSystem",
"params": {
"sessionId": "{SESSION_ID}",
"paymentSystemId": "",
"userId": "{USER_ID}"
}
}Response:
json
{
"response": {
"creditPaymentMethods": [
{ "cardType": 3, "name": "Visa" }
]
},
"exception": null
}Card type enum: AmericanExpress = 0, Discover = 1, MasterCard = 2, Visa = 3, Diners = 4, Dindes = 5 (the typo is in the app).