Skip to content

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: retrieveAccounts

Parameters ​

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:

ValueNameMeaning
1MEALSMeal-plan swipes / meal points
2CHARGECharge account (must be paid)
3DECLINING_BALANCEPrepaid declining balance
4APPLEPAYApple 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:

ScreenFilter
Accounts tile / account listpaymentSystemType ∈ {OPCS, CSGOLD} and accountTender ∈ get.feature.display_tenders
Deposit "to" pickerpaymentSystemType ∈ {OPCS, MONETRA} (default) and accountTender ∈ get.feature.deposit_tenders
Meal donation pickeraccountTender ∈ 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 ​

FieldTypeNotes
idstringAccount id used everywhere else.
accountDisplayNamestringName to show.
accountTypenumberSee enum above.
accountTenderstringTender name/id used by the tender filters and by meal donations.
balancenumberCurrent balance. Meal accounts show a count, not currency.
paymentSystemTypenumberProcessor backing the account.
depositAcceptedbooleanWhether the account can receive deposits (used by deposit destination filters).
isFavoritebooleanOptional; the account screens do not read it (merchant favorites use their own field).
planNamestringPresent 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: deactivateAccount
json
{
    "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: retrieveCashlessPatronMobileDisplayMediaValue
json
{
    "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: retrieveTransactionHistory

Transactions within a date range ​

plaintext
POST /json/commerce
method: retrieveTransactionHistoryWithinDateRange

Both take the same parameters. paymentSystemType is always sent as 0 by the app.

FieldTypeRequiredDescription
paymentSystemTypenumberYES0 in the app.
queryCriteriaobjectYESQuery object, see below.
sessionIdstringYESUser session (injected).

queryCriteria:

FieldTypeDescription
accountIdstring | nullAccount to filter on; null means all accounts.
newestDatestringUpper bound (ISO date).
oldestDatestringLower bound (ISO date).
maxReturnMostRecentnumberPage 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:

PresetoldestDate
past_six_month (default)now − 6 months
past_monthnow − 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
FieldTypeRequiredDescription
fromAccountIdstringYESFunding account (credit card / Apple Pay).
toAccountIdstringYESDestination account.
amountnumberYESDeposit 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
FieldTypeRequiredDescription
fromAccountIdstringYESFunding account.
toAccountIdstringYESDestination account.
fromAccountCvvstring | nullNOCVV for credit-card funding.
amountnumberYESAmount.
cashlessTerminalLocationnullNOAlways 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
FieldTypeRequiredDescription
userIdstringYESRecipient user id.
fromAccountIdstringYESCaller's funding account.
fromAccountCvvnullNOAlways null in the app.
toAccountIdstringYESRecipient account.
amountnumberYESAmount.
cashlessTerminalLocationnullNOAlways null.

NOTE

This call is flagged useInstitutionId = false, so only sessionId is injected.

Retrieve Accounts for a User ​

plaintext
POST /json/commerce
method: retrieveAccountsByUser
json
{
    "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: retrieveDepositAccountsByUser

Same shape as above; returns only accounts that can receive deposits.

plaintext
POST /json/commerce
method: donate
FieldTypeRequiredDescription
accountIdstringYESMeal account to donate from.
amountToDonatenumberYESNumber 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
FieldTypeRequiredDescription
accountInfoobjectYESCard / 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}"
    }
}
FieldNotes
mediaValueThe raw card number. This is what the server receives — the client does not tokenise on the MONETRA path.
mediaSecurityCodeCVV.
mediaEntryMethod1 for manual/keyed entry.
paymentSystemTypeSent as null; the server decides from the tender. The app's constant is MONETRA = 3, USAEPAY = 4.
expirationMonth / expirationYearStrings, exactly as typed into the two fields.
externalAccountToken / externalTransactionTokenPopulated 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
FieldTypeRequiredDescription
userIdstringYESCurrent user id.
paymentTypenumberYES1 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
TargetShown when
change_meal_planget.feature.enable_change_meal_plan = "1" (and the user is not a guest)
purchase_meal_planget.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
FieldTypeRequiredDescription
sessionIdstringYESExplicit session id.
paymentSystemIdstringYESPayment system id, or "".
userIdstringYESUser 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).