Appearance
SOA Barcode
GET Mobile can generate the patron barcode on-device when the institution exposes soa.general.key. The barcode is a 22-character rotating value derived from the patron's CBORD patron key and the current Unix time. The same value can be produced server-side via retrievePatronBarcodePayload, but offline generation is faster and works without a session.
Output format
plaintext
CCCCCCCCCC 1 PPPPPPPPPP D| Segment | Length | Meaning |
|---|---|---|
C | 10 | floor(unixSeconds) left-padded with zeros |
1 | 1 | Literal separator / format marker |
P | 10 | Encrypted patron number, left-padded with zeros |
D | 1 | Luhn check digit |
Total: 22 characters, all digits.
Inputs
| Input | Source |
|---|---|
Patron key (numeric, patronKey) | User setting CashlessKey — user.retrieveSetting { "settingName": "CashlessKey" } |
Encoding key (keyHex) | Institution setting soa.general.key |
| Timestamp | Date.now() (milliseconds) |
The encoding key is a hex string such as A1B2C3D4E5F601020910 (advertised in the setting description).
The patron key is not the displayed ID
The barcode screen also shows ID: <value> under the patron's name. That value comes from a different call — commerce.retrieveCashlessPatronMobileDisplayMediaValue — and is gated on get.feature.mobile_patron_cashless_display_media_type being non-empty.
| Source | What it is | |
|---|---|---|
ID: label | commerce.retrieveCashlessPatronMobileDisplayMediaValue | The institution's identifier — verified to be the university student ID |
| Barcode input | user.retrieveSetting { "settingName": "CashlessKey" } | The CBORD-assigned patron key (numeric, ≤ 32 bits) |
Nothing in the client copies one into the other, and they are different numbers with no required relationship — the student ID on screen is not the barcode key. Use CashlessKey for barcode generation; do not substitute the display value just because it is the number on screen.
There is a hard constraint that helps identify the right value: the key must fit in 32 bits. patronKeyToByteArray takes the low 4 bytes of the key's 8-byte little-endian form, while the Luhn digit is computed over the key's full decimal string. A key larger than 4 294 967 295 (more than 10 digits) would decode inconsistently, so anything like a 16-digit card number cannot be the patron key.
Algorithm
1. Decode constants
plaintext
GARBLE_B64 = "NTBGQ0RGM0ZFNDIyQTBBNDY5RkU="
GARBLE_HEX = base64_decode(GARBLE_B64) = "50FCDF3FE422A0A469FE"
garbleBytes = hex_to_bytes(GARBLE_HEX) // 10 bytes
keyBytes = hex_to_bytes(keyHex)
xorKey = XOR(garbleBytes, keyBytes) // 10 bytes; key is repeated/truncated to garble lengthXOR(a, b) iterates over a and uses b[i % b.length].
2. Counter
plaintext
counter = floor(timestampMs / 1000)3. TOTP
plaintext
msg = big_endian_8_bytes(counter)
mac = HMAC_SHA256(key = xorKey, msg)
offset = mac[19] & 0x0F
code = ((mac[offset] & 0x7F) << 24) |
((mac[offset+1] & 0xFF) << 16) |
((mac[offset+2] & 0xFF) << 8) |
((mac[offset+3] & 0xFF))
totp = (code mod 1_000_000_000) as decimal, left-padded to 9 digitsNOTE
The app builds the message by taking the 8-byte little-endian representation of the counter and reversing it, which is exactly big-endian. The truncation is standard RFC 4226 dynamic truncation with a 9-digit modulus.
4. Encrypt the patron number
plaintext
patronBytes = first 4 bytes of little_endian_8_bytes(patronNumber)
totpBytes = little_endian_8_bytes(totp)
encBytes = XOR(patronBytes, totpBytes) // 4 bytes
encPatron = little_endian_to_int(encBytes)Only the low 4 bytes of the patron number are encrypted, so the effective patron range is 0 … 2^32-1.
5. Luhn digit
plaintext
sum = 0
double = true
for digit in reverse(patronNumber):
d = int(digit)
if double:
d *= 2
if d > 9:
d = d % 10 + 1
sum += d
double = not double
digit = (10 - sum % 10) % 10
if digit == 0: digit = 06. Assemble
plaintext
barcode = zero_pad(counter, 10) + "1" + zero_pad(encPatron, 10) + str(digit)Reference implementation (JavaScript)
js
const GARBLE = Uint8Array.from(
atob("NTBGQ0RGM0ZFNDIyQTBBNDY5RkU="),
(c) => c.charCodeAt(0)
); // ASCII hex
function hexToBytes(hex) {
const out = new Uint8Array(hex.length / 2);
for (let i = 0; i < hex.length; i += 2) {
out[i / 2] = parseInt(hex.slice(i, i + 2), 16);
}
return out;
}
function xor(a, b) {
const out = new Uint8Array(a.length);
for (let i = 0; i < a.length; i++) out[i] = a[i] ^ b[i % b.length];
return out;
}
function bytesToIntLE(bytes) {
let n = 0n;
for (let i = 0; i < bytes.length; i++) {
n += BigInt(bytes[i] & 0xff) << BigInt(8 * i);
}
return n;
}
function intToBytesLE(n, length = 8) {
const out = new Uint8Array(length);
for (let i = 0; i < length; i++) {
out[i] = Number((n >> BigInt(8 * i)) & 0xffn);
}
return out;
}
function intToBytesBE(n, length = 8) {
return intToBytesLE(n, length).reverse();
}
function luhnDigit(patronKey) {
let sum = 0;
let dbl = true;
for (let i = patronKey.length - 1; i >= 0; i--) {
let d = Number(patronKey[i]);
if (dbl) {
d *= 2;
if (d > 9) d = (d % 10) + 1;
}
sum += d;
dbl = !dbl;
}
const digit = (10 - (sum % 10)) % 10;
return digit === 0 ? 0 : digit;
}
async function generateBarcode(patronKey, keyHex, timestampMs = Date.now()) {
const xorKey = xor(hexToBytes(atob("NTBGQ0RGM0ZFNDIyQTBBNDY5RkU=")), hexToBytes(keyHex));
const counter = BigInt(Math.floor(timestampMs / 1000));
const msg = intToBytesBE(counter);
const key = await crypto.subtle.importKey(
"raw", xorKey, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
);
const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, msg));
const offset = mac[mac.length - 1] & 0x0f;
const code =
((mac[offset] & 0x7f) << 24) |
((mac[offset + 1] & 0xff) << 16) |
((mac[offset + 2] & 0xff) << 8) |
(mac[offset + 3] & 0xff);
const totp = BigInt(code % 1_000_000_000);
const patronBytes = intToBytesLE(BigInt(patronKey), 8).slice(0, 4);
const encBytes = xor(patronBytes, intToBytesLE(totp, 8));
const encPatron = bytesToIntLE(encBytes);
const digit = luhnDigit(String(patronKey));
return (
String(counter).padStart(10, "0") +
"1" +
String(encPatron).padStart(10, "0") +
String(digit)
);
}Reference implementation (Python)
python
import base64, hashlib, hmac, time
GARBLE = base64.b64decode("NTBGQ0RGM0ZFNDIyQTBBNDY5RkU=") # ASCII hex
GARBLE_BYTES = bytes.fromhex(GARBLE.decode())
def xor(a: bytes, b: bytes) -> bytes:
return bytes(x ^ b[i % len(b)] for i, x in enumerate(a))
def luhn_digit(patron_key: str) -> int:
total, dbl = 0, True
for ch in reversed(patron_key):
d = int(ch)
if dbl:
d *= 2
if d > 9:
d = d % 10 + 1
total += d
dbl = not dbl
digit = (10 - total % 10) % 10
return 0 if digit == 0 else digit
def generate_barcode(patron_key: str, key_hex: str, timestamp_ms: int | None = None) -> str:
timestamp_ms = timestamp_ms if timestamp_ms is not None else int(time.time() * 1000)
xor_key = xor(GARBLE_BYTES, bytes.fromhex(key_hex))
counter = timestamp_ms // 1000
mac = hmac.new(xor_key, counter.to_bytes(8, "big"), hashlib.sha256).digest()
offset = mac[-1] & 0x0F
code = (
((mac[offset] & 0x7F) << 24)
| ((mac[offset + 1] & 0xFF) << 16)
| ((mac[offset + 2] & 0xFF) << 8)
| (mac[offset + 3] & 0xFF)
)
totp = code % 1_000_000_000
patron_bytes = int(patron_key).to_bytes(8, "little")[:4]
totp_bytes = totp.to_bytes(8, "little")
enc = xor(patron_bytes, totp_bytes)
enc_patron = int.from_bytes(enc, "little")
return f"{counter:010d}1{enc_patron:010d}{luhn_digit(patron_key)}"Decoding a barcode
The app can also reverse a barcode it generated, given the key:
text
counter = int(barcode[0:10])
encPatron = int(barcode[11:21])
xorKey = XOR(garbleBytes, keyBytes)
totp = TOTP(xorKey, counter)
patron = intLE( XOR(intLE4(encPatron), intLE8(totp)) )The Luhn digit is not verified on decode.
WARNING
Decoding is a total inversion, not a one-way transform. Given a single barcode and the institution key, you recover the patron key — and can then mint a fresh, valid barcode for any timestamp. The 22-digit string is time-boxed; the ability to generate one is not. See Security Notes.
Generation cadence
- The barcode changes once per second because the counter is Unix seconds.
- The app refreshes the displayed barcode every 5000 ms.
- A barcode is valid as long as the POS accepts the counter window; the app does not track expiry itself.
Fallbacks
| Condition | Behavior |
|---|---|
soa.general.key present + offline generation enabled | Generate locally |
| Offline generation disabled + online | retrievePatronBarcodePayload |
| No key at all | Return the patron key unchanged as the barcode (last-resort fallback) |
NOTE
encodePin returns its input verbatim when soa.general.key is absent. That is only useful at institutions that scan the patron key directly.
Barcode display settings
| Setting | Effect |
|---|---|
get.feature.enable_offline_barcode_generation | Allow local generation |
get.feature.mobile_patron_cashless_display_media_type | Whether the ID: label is shown (non-empty = shown) and which value it shows |
get.feature.enable_get_my_card | Show the "my card" screen |