The OneCard API is a set of web services allowing third party software developers to integrate their applications with the Heartland Campus Solutions OneCard system.

• OneCard API uses HTTPS protocol.
• OneCard API is a RESTful web API service.
• All OneCard API request calls must use only the POST method.

The developer can select the response to be serialized in JSON format by setting Content-Type to JSON. To override the Content-Type result, set the HTTP Accept Header to application/JSON.

The developer can select a preferred language for the response by setting the Accept-Language request HTTP header. The system defaults to English if the selected language is not supported.

---

Role-based security with two roles:

• Student – used for student self-serve applications, authenticated with account number and password or other valid system credentials.
• Operator – used for operator services, authenticated with ID and password.

Each web service description states Permitted Roles: Student, Operator. If your role is not listed, calling the endpoint returns Response Status: Access Denied!

Authentication Required: Yes/No is shown in each service description.

---

Before real development starts, obtain from Heartland Campus Solutions:

1. Sign a Non-disclosure agreement (NDA).
2. Send your company name and contacts.
3. Provide a list of applications with application name and short description.

Heartland Campus Solutions will provide:

1. Developer key (DevKey) – sent in each web service request header (DevKey: <value>). Never changes. Must be hardcoded.
2. Application OriginID – numeric value per application. Never changes. Must be hardcoded.
3. API URL – different for each OneCard installation. Must be configurable in your application.
4. Terminal ID and Terminal Type – bound to terminal definitions. May change per setup. Must be configurable.
5. Operator ID and Operator password – for Operator role testing. Must be configurable.
6. Account numbers and passwords – for testing.

---

All services with Authentication Required: Yes require a valid SessionID.

• For Operator role: call Operator Login. For Student role: call Account Login.
• Close sessions by calling Operator Logout / Account Logout.
• Default session timeout: 15 minutes. Can be customized via ExpiredInMinutes.

Session and Sessionless Services

Session-based (standard flow):

Login → Transaction1 → Transaction2 → … → Logout

Request includes SessionID.

Sessionless calls are for rare single-transaction use cases. Instead of SessionID, include authentication parameters in the request.

Operator sessionless parameters:

Student sessionless parameters:

Operator Login

• Permitted Roles: N/A
• Authentication Required: No
• URL: POST /operator/login

Request Parameters:

Result: Returns an authenticated SessionID as string.

Operator Logout

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /operator/logout

Request Parameters:

Result: Returns true/false for success or failure.

Account Login

• Permitted Roles: N/A
• Authentication Required: No
• URL: POST /account/login

Request Parameters:

Result: Returns an authenticated SessionID as string.

Account Logout

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/logout

Request Parameters:

Result: Returns true/false for success or failure.

---

App Get Config

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /app/get/config

Request Parameters:

Result: Returns application configuration settings per terminal/OriginID pair. The response includes: OriginID, TerminalID, ConfigData, SiteID, SiteName, PrivacyUrl, AccountsSettings, LoginSettings, PINSettings, FinancialParameters, ApiVersion, AccountPictureSettings, UserFriendlyCardName, WalletSettings, SalesSettings, DepositSettings, SupportedLanguages, and AccountSignatureSettings.

App Save Config

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /app/save/config

Request Parameters:

---

Groups

• Available in: OneCard API 6.9.1 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /sysconfig/groups

Manages groups (Category, Group, RateCategory, AccessControl).

Request Parameters:

Operator (System Config)

• Available in: OneCard API 6.9.1 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /sysconfig/operator

Manages operator accounts including rights and SAPs.

ActionType values: Add (1), Update (2), Delete (3)

Manager Right Numbers:

POS Operator (System Config)

• Available in: OneCard API 6.9.1 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /sysconfig/posoperator

---

Account Password Check

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/password/check

Account Password Change

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/password/change

---

PIN Check

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/pin/check

Session Create

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /account/session/create

Creates a student session without requiring the student to provide a password. Useful when an operator is managing the session on behalf of a student.

Request Parameters:

Account Create or Update

• Permitted Roles: Operator
• Authentication Required: Yes (Sessionless supported)
• URL: POST /account/create

Creates or updates a OneCard account. When ExistingAccount is returned as true, the account already existed and was updated.

Key Request Parameters:

Account Add Data to Authorization Fields

• Permitted Roles: Operator
• Authentication Required: Yes (Sessionless)
• Available in: OneCard API 9.1.0.11 and newer
• URL: POST /account/addauthorizationfields

Account Search

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /account/search

Request Parameters:

Account Summary

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/summary

Returns summary information for an account including balances, secondary accounts, status flags, user-defined fields, and supplemental data.

Key result fields: StandardAccountID, DisplayAccountID, DisplayAccountType, AccountFullName, IsActive, IsLostCard, IsStolenCard, IsExpired, IsNotYetValid, Notes, UserDefinedFields, SupplementalData, SecondaryAccounts, MembershipExpDate in Category/RateCategory/AccessControl.

Account Full Details

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/fulldetails

Returns complete account information. Added MembershipExpDate to Groups in v9.4.0.3. The response includes PIN, Category, RateCategory, AccessControl, and other detailed fields.

Account Status

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/status

Request Parameters:

Account Financial Transactions

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/transactions

Account Financial Transactions Failed

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/transactions/failed

Account Deposit Balances

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/depositbalances

Account Balances

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/balances

Request Parameters:

Account Meal Plan History

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/mealplanhistory

Request Parameters include UseMasterAccount (added in v9.6.0.16). Additional result parameters in v9.6.0.16: MasterAccountNumber, MasterAccountFullName.

Account Update Professional Data

• Permitted Roles: Operator
• Authentication Required: Yes (Sessionless)
• URL: POST /account/updateprofessionaldata

Remove From Mobile Swipes

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/removefrommobileswipes

Account Add Groups

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /account/addgroups

Request Parameters:

Result: Returns true/false plus TaskID for block mode operations.

Account Add Groups (V2)

• Available in: OneCard API 9.4.0.4 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /account/addgroups/v2

Account Remove Groups

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /account/removegroups

Supports filtering by AccountFilterOption:

• 1 – Single Account
• 2 – Include Account List
• 4 – Account Range
• 5 – Account Expiration Date
• 6 – Account Group
• 9 – All Accounts

Request Parameters:

---

Account Photo Get

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /account/photo/get

Request Parameters:

---

Meal Plan Sell

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /mealplan/sell

Request Parameters:

Meal Plan Remove

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /mealplan/remove

Request Parameters:

Meal Plan Group Sell

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /mealplangroup/sell

Parameters are similar to Meal Plan Sell but uses ProductNumberID as a group ID.

Adjust Cancel Box Lunch

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /mealplan/adjustments/cancelboxlunch

Adjust Generic Meal Plan

• Available in: OneCard API 9.3.5 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /mealplan/adjustments/genericmeals

Adjust Flexible Weekly

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /mealplan/adjustments/flexibleweekly

Swap Block Plan

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /mealplan/adjustments/swapblockplan

---

All financial transactions support both session-based and sessionless modes.

Transaction deduplication: To avoid duplicate transactions, call Transaction PreInit first to get a unique OneCardTransID, then include this in all subsequent transaction calls.

Async vs Sync:

• IsAsync=false (default): blocks and waits for result.
• IsAsync=true: returns immediately with OneCardTransID; call Get Transaction Result to retrieve the outcome.

Buffered vs Live:

• Live transactions: failed transactions are rejected.
• Buffered transactions: failed transactions are passed but posted to the exception log (e.g., insufficient funds still get processed, driving balance negative). Status in result = 24.

CardEntry values:

TransactionInitiator values:

Transaction PreInit

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /transactions/preinit

Call this before the actual transaction to obtain a unique OneCardTransID. Pass this ID in the subsequent transaction call to prevent duplicates.

Transaction PreInit Cancel

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /transactions/preinit/cancel

Cancels a pre-initialized transaction. Parameters include SessionID, GenerateReceipt, and AdditionalData.

Bank Card Simulate Transaction

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /transactions/bankcard/simulate

Simulates a bank card (credit card) transaction for deposit.

Request Parameters:

Result includes: MaskedCardNumber, CreditGL_REC_ID

Adjust Balance Process

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /transactions/onecard/adjustbalance/process

Adjusts a OneCard account balance.

Key Request Parameters:

Refund Balance Process

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /transactions/onecard/refundbalance/process

Refunds to a OneCard balance. The balance must be set as refundable in the Tools program.

Key Request Parameters:

Access Process

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• Description: Performs entry or exit (access) transaction.
• URL: POST /transactions/onecard/access/process

Key Request Parameters:

Log Access Transaction

• Available in: OneCard API 8.1 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /transactions/log/access

Logs access transactions processed by a third-party access system into the OneCard database.

Key Request Parameters:

Deposit Process

• Permitted Roles: Operator
• Authentication Required: Yes (Sessionless supported)
• URL: POST /transactions/onecard/deposit/process
• Description: Performs deposit to OneCard balance. The terminal must allow transaction type 3 (Prepayment Admin).

Key Request Parameters:

Transaction Process

• Permitted Roles: Operator
• Authentication Required: Yes (Sessionless)
• URL: POST /transactions/onecard/onecardtrans/process

Low-level transaction processing endpoint with full access to the underlying OneCard transaction engine. Accepts a Request object with detailed transaction parameters.

Inquiry Process

• Permitted Roles: Student, Operator
• Authentication Required: Yes (Sessionless)
• Description: Performs inquiry for specific OneCard data (financial balance, special field, meal plan balance, balance lock/unlock).
• URL: POST /transactions/onecard/inquiry/process

TranType values:

Key Request Parameters:

Vend Money Process

• Permitted Roles: Student, Operator
• Authentication Required: Yes (Sessionless)
• Description: Performs payment from OneCard balance. The balance to draw from is defined by the given Bill Type.
• URL: POST /transactions/onecard/vendmoney/process

TranType values:

Key Request Parameters:

Reverse Process

• Permitted Roles: Operator
• Authentication Required: Yes
• Description: Performs Vend Money Reverse.
• URL: POST /transactions/onecard/reverse/process

To identify the initial transaction, use either:

• AccountID + AccountType + TranDateTimeForReversal + TerminalForReversal
• OR ReferenceTransactionGUID (the OneCardTransGUID from VendMoney result)

Vend Meal Plan Process

• Permitted Roles: Student, Operator
• Authentication Required: Yes (Sessionless)
• Description: Performs meal plan transaction.
• URL: POST /transactions/onecard/vendmealplan/process
• TranType: "17" (VendMealPlanInFull)

Two modes:

1. Board Plan mode (Amount=0): Looks for valid meal plans; reduces meal count. No funds taken.
2. Meal Money mode (Amount>0): Looks for meal money plans (Meal Equivalence or Meal Allowance). Falls back to account balance if insufficient.

Key Request Parameters:

Get Transaction Result

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /transactions/get

Retrieves the result of an async transaction by OneCardTransID. Returns result only for the corresponding transaction type.

Request Parameters:

The result can contain: BankCardResult, VendMoneyResult, VendMealPlanResult, InquiryResult, DepositResult, VendAccessResult, BankCardSimulationTransactionResult, OneCardTransResult, ReceiptResult, AccessTranReqResult, RefundBalanceResult, AdjustBalanceResult, CheckOutAllResult, VendMoneyResultV2.

---

MyPay Get Pending Swipes By Terminal

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /mypay/pendingswipes

---

Message Send

• Permitted Roles: Student, Operator
• Authentication Required: Yes
• URL: POST /message/send

Sends a message using a specified Protocol.

System Test

• Permitted Roles: N/A
• Authentication Required: No
• URL: POST /system/test

Returns server status to verify the API is reachable.

---

Get a List with All Valid OneCard Policies

• Permitted Roles: Student
• Authentication Required: Yes
• URL: POST /onecardpolicy/getcurrentpolicies

Accept/Acknowledge the OneCard Policy

• Permitted Roles: Student
• Authentication Required: Yes
• URL: POST /onecardpolicy/acceptpolicy

---

Get GL End of Day

• Available in: OneCard API 8.8.0.10 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /reports/gleod

Returns GL End of Day data with taxes.

Get Updated Accounts

• Available in: OneCard API 8.9.0.9 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /reports/updatedaccounts

Returns selected properties for accounts changed during a selected period.

Get All People

• Available in: OneCard API 9.3.0.6 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /reports/allpeople

Returns selected properties for all accounts. Supports paging and two filtering parameters: SkipExpired and Category.

Get GL Transactions

• Available in: OneCard API 9.6.0.2 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /reports/gltransactions

---

Get Block Mode Task Result

• Available in: OneCard API 8.10.0.2 and newer
• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /blockmode/task/get/result

Returns the result/status of a block mode task (used with Account Add Groups and Account Remove Groups for batch operations).

---

The POS Plugin (POS API Core) provides a set of endpoints for POS operators. A POS operator must open a shift before processing sales.

All POS Plugin endpoints use the base path: POST /posapi/location/{poslocation}/...

Miscellaneous POS Services

POS Plugin Test

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/test

POS Location Test

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/locationtest

Department Services

Get Departments

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/departments/getall

Get Department Picture

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/departments/getpicture

Returns binary PNG file (image/png).

General Item Services

Get Items

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/items/getall

Get Picture

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/items/getpicture

ImageSize values:

Result: Returns PNG as base64 in Base64Result.

Get Modifiers

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/items/getitemmodifiers

Returns list of modifiers of type "Modifier" for an item.

Get Side Dishes

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/items/getitemsidedishes

Get Instructions

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/items/getiteminstructions

Get Modifiers of All Types

• Permitted Roles: Operator
• Authentication Required: Yes
• URL: POST /posapi/location/{poslocation}/items/getitemmsi

Returns Modifiers, Side Dishes, and Instructions for an item in one call.

Standard Item Services

Standard Items are defined in WebPAdmin → Products → Item Maintenance.

Get Items (Standard)

• URL: POST /posapi/location/{poslocation}/items/standard/getall

Request Parameters:

Get Item (Standard)

• URL: POST /posapi/location/{poslocation}/items/standard/getitem

Returns detailed size pricing, tax flags, and modifier availability for a single Standard item.

Special Item Services

Special Items include Events, Services, Variables, and Series items.

Get Items (Special)

• URL: POST /posapi/location/{poslocation}/items/special/getall

SpecialType values: C=Series, E=Event, S=Service, V=Variable

Get Item (Special)

• URL: POST /posapi/location/{poslocation}/items/special/getitem

Group Item Services

Get Items (Group)

• URL: POST /posapi/location/{poslocation}/items/group/getall

Get Items in Group

• URL: POST /posapi/location/{poslocation}/items/group/getitemsingroup

Modifier Services

Get All Modifiers

• URL: POST /posapi/location/{poslocation}/modifiers/getallmodifiers

Get All Side Dish Modifiers

• URL: POST /posapi/location/{poslocation}/modifiers/getallsidedishes

Get All Instruction Modifiers

• URL: POST /posapi/location/{poslocation}/modifiers/getallinstructions

PAdmin Definitions and Configuration Services

Get POS Definitions and Tax Rates

• URL: POST /posapi/location/{poslocation}/config/getdata

POSDefinitions bit field:

If not set, all definitions are returned by default.

Result includes: Departments, Items, Modifiers, ItemModifiers, POSTaxConfiguration (Tax1RatePercentage, Tax2RatePercentage, Tax3RatePercentage).

POS Operator Shift Services

A POS operator must open a shift before processing sales.

Start Shift

• URL: POST /posapi/location/{poslocation}/shifts/startshift

Request Parameters:

End Shift

• URL: POST /posapi/location/{poslocation}/shifts/endshift

Closes the shift and returns the End of Shift report.

Request Parameters:

Result: Returns EndOfShiftReport as string.

Get End of Shift Report

• URL: POST /posapi/location/{poslocation}/shifts/getendofshiftreport

Request Parameters:

POS Services

Calculate Totals

• URL: POST /posapi/location/{poslocation}/pos/calculatetotals

Calculates subtotal, tax amounts, and total for a list of items before processing a sale.

Process Sale

• URL: POST /posapi/location/{poslocation}/pos/processsale

Processes a POS sale.

Key Request Parameters:

PaymentMode values:

---

Reference 1 – TerminalType Values

Reference 2 – AccountType Values

---

Account

Accounts store cardholder information. A single user in OneCard can have up to 5 account numbers (Standard, ISO ABA, Custom, Proximity, Smart). Standard account is always 9 digits, zero-padded left. Transaction response contains StandardAccountID and DisplayAccountID.

For swiped card transactions, send full Track2 magstripe data using AccountType=RAW. The API parses the magstripe internally.

Bill Types

Bill Types designate the General Ledgers from which funds are taken and to which transaction funds are directed. Essential for financial terminals.

Categories and Groups

Four classifications of people groupings:

• Category – status at highest level (e.g., Full-Time Student, Faculty). Only one per account.
• Rate Category – for different pricing (discounts/premiums). Used with Rate Schedules.
• Access Control Status – for granting access rights en masse.
• Group – broadest grouping. Up to 32 groups per account. Max 99,000 groups/categories in system.

Operator

Operators must be added to the system with appropriate System Access Privileges (SAPs). Effective permissions are a combination of Terminal SAPs and Operator SAPs.

Location

A physical or artificial reference point. Locations belong to a single Organization. Used by Access Rules and Meal Plans.

Terminal

Devices (computers, POS stations, vending machines) connected to the OneCard network. Terminal types include: Administrative, Third Party, Web, Mobile (used in OneCard mobile apps), POS, and more.

---

Q: What is DevKey?
A: A static value assigned to you as a developer. Never changes. Must be hardcoded in all your applications (preferably encrypted). The same for all schools.

Q: What is API URL Path?
A: Customer-specific. Each school installs the API on their own IIS server. Only HTTPS requests are accepted. The same URL is used for all your applications connecting to the same school.

Q: What are OperatorID and OperatorPassword?
A: Customer-specific. The school defines OperatorIDs and passwords in their OneCard system. May be application-specific – some schools use different credentials per application.

Q: What is OriginID?
A: Similar to DevKey, but assigned per application you develop. Never changes. Must be hardcoded. Used with DevKey to identify the developer and which application initiated the transaction.

Q: What is TerminalType?
A: A fixed value in your applications (ThirdParty terminal type). Other types are primarily for internal Heartland applications.

Q: What is TerminalID?
A: The school defines a terminal in OneCard and provides its ID. Matches the physical device running the application. Effective permissions are a combination of terminal and operator permissions.

Q: How can I handle duplicated transactions?
A: Before the real transaction, call Transaction PreInit (/transactions/preinit) to obtain a unique OneCardTransID. Include this in the actual transaction request to prevent duplication.

Q: What does the Balance parameter do in Deposit?
A: Each account can have up to 12 balances designated for specific transactions. The school will tell you which balance numbers to allow (e.g., Balance #1 for books, Balance #2 for dining).

Q: What does HoldDays do?
A: Specifies when deposited funds become available. E.g., a parent can deposit today but the funds are only available after 10 days.

Q: What is OneCardTransID?
A: A unique ID for the currently processing transaction. Used for both async and sync transactions. If you lose the response (e.g., dropped connection), use this ID with Get Transaction Result to retrieve the outcome.

Q: What is CustomerNumber?
A: Assigned to each OneCard customer (school). Can be used to prevent posting transactions to the wrong school.

Q: When would PIN be used in the Off-Campus program?
A: Depends on integration. Recommended for self-service applications with manual account number entry. Not needed for operator-verified cards or card-swipe-only applications.

Q: What are Units, UnitMode, Buffered, and IsAsync?
A: UnitMode charges by units (e.g., printed pages) rather than amount – not recommended for Off-Campus. Buffered passes failed transactions to the exception log. IsAsync=true allows non-blocking transaction submission; call GetResult to retrieve the outcome.

---

Example 1 – Operator Login (PHP)

Example 2 – Vend Money (PHP)

Example 3 – Session Expiration Check (C#)

Example 4 – Parse Deposit Result (C#)

Example 5 – Handle Duplicate Transactions (Pseudocode)

---