Skip to content

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
SegmentLengthMeaning
C10floor(unixSeconds) left-padded with zeros
11Literal separator / format marker
P10Encrypted patron number, left-padded with zeros
D1Luhn check digit

Total: 22 characters, all digits.

Inputs ​

InputSource
Patron key (numeric, patronKey)User setting CashlessKey — user.retrieveSetting { "settingName": "CashlessKey" }
Encoding key (keyHex)Institution setting soa.general.key
TimestampDate.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.

SourceWhat it is
ID: labelcommerce.retrieveCashlessPatronMobileDisplayMediaValueThe institution's identifier — verified to be the university student ID
Barcode inputuser.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 length

XOR(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 digits

NOTE

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 = 0

6. 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 ​

ConditionBehavior
soa.general.key present + offline generation enabledGenerate locally
Offline generation disabled + onlineretrievePatronBarcodePayload
No key at allReturn 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 ​

SettingEffect
get.feature.enable_offline_barcode_generationAllow local generation
get.feature.mobile_patron_cashless_display_media_typeWhether the ID: label is shown (non-empty = shown) and which value it shows
get.feature.enable_get_my_cardShow the "my card" screen