Skip to content

Mobile Credentials ​

Mobile credentials let a phone act as a campus card in Apple Wallet (iOS) or Google Wallet / HID (Android). They use a different host from the JSON services:

plaintext
{partner_services_url}

See the environment table for the partner host per region (api.partnerpayments.cbord.com, api.payments.demo.cbord.com, etc.).

Prerequisites ​

Three values must be obtained before calling the partner API:

ValueHow to get it
OmniID JWTPOST /json/authentication retrieveExternalAuthenticationToken with externalSystem: "OmniID"
Authorization blobPOST /json/authentication retrieveAuthorizationBlob with the device model and OS version
Institution idFrom the institution record / login

The app caches the JWT and blob in device storage under jwt_token and auth_blob and re-fetches them when their TTL expires.

json
// retrieveExternalAuthenticationToken
{
    "method": "retrieveExternalAuthenticationToken",
    "params": {
        "tokenType": null,
        "externalSystem": "OmniID",
        "claimSet": null,
        "sessionId": "{SESSION_ID}",
        "institutionId": "{INSTITUTION_UUID}"
    }
}
json
// retrieveAuthorizationBlob
{
    "method": "retrieveAuthorizationBlob",
    "params": {
        "deviceModel": "iPhone15,2",
        "deviceOSVersion": "18.1",
        "sessionId": "{SESSION_ID}",
        "institutionId": "{INSTITUTION_UUID}"
    }
}

Active Passes ​

Returns the current provisioning state of every wallet credential for this user/device.

plaintext
POST {partner_services_url}/partner/v1/activePasses

Headers ​

HeaderValue
AuthorizationBearer {OMNIID_JWT}
institutionId{INSTITUTION_UUID}
Content-Typeapplication/json

Body ​

json
{
    "authorizationBlob": "{AUTHORIZATION_BLOB}"
}

Response ​

json
{
    "passes": {
        "iPhone": "{PASS_DATA}",
        "iWatch": "{PASS_DATA}",
        "android_hid": "{PASS_DATA}",
        "android_nxp": "{PASS_DATA}",
        "android_hid_wallet": "{PASS_DATA}"
    },
    "credStatus": {
        "iPhone": 1,
        "iWatch": 0,
        "android_hid": 0,
        "android_nxp": 0,
        "android_hid_wallet": 0
    },
    "referenceIdentifier": "{REFERENCE_ID}"
}
  • passes holds opaque pass/bundle data per device type.
  • credStatus holds the credential status enum per device type.
  • referenceIdentifier identifies the credential and is required for unlink.

Device-type keys:

KeyPlatformMeaning
iPhoneiOSApple Wallet pass on the phone
iWatchiOSApple Wallet pass on the paired watch
android_hidAndroidHID SEOS credential
android_nxpAndroidGoogle Wallet / NXP credential
android_hid_walletAndroidHID credential delivered through Wallet

NOTE

Apple Wallet provisioning itself is performed by the native app through PKAddPaymentPassViewController. The web layer only reads credStatus/passes and tells native code to start the flow via the addToAppleWallet bridge method. Android uses this API plus the native credential bundle.

Revokes and removes a mobile credential.

plaintext
POST {partner_services_url}/partner/v1/managePass/referenceIdentifier/{referenceIdentifier}/action/getUnlink

Headers ​

HeaderValue
AuthorizationBearer {OMNIID_JWT}
X-API-Key{get.mobile_credentials.unlink_key}
Content-Typeapplication/json

Body ​

json
{}

Response ​

json
{
    "responseHeader": {
        "statusCode": 200,
        "statusMessage": "OK"
    }
}

IMPORTANT

Unlink is gated by the get.mobile_credentials.enable_unlink setting. The X-API-Key comes from get.mobile_credentials.unlink_key, which is an institution-level secret served by the configuration service.

Register a Device for Push Provisioning ​

Registers the device's push token(s) so the wallet provider can push updated passes.

plaintext
POST {partner_services_url}/cashless/registered-devices/{institutionId}

Headers ​

HeaderValue
AuthorizationBearer {OMNIID_JWT}
X-API-Key{get.mobile_credentials.unlink_key}

Body ​

json
{
    "authorizationBlob": "{AUTHORIZATION_BLOB}",
    "devices": [
        {
            "deviceType": "iOS",
            "deviceToken": "{APNS_TOKEN}",
            "notificationType": 8
        }
    ]
}

devices is built from the user's stored notification registrations (the same tokens saved by saveNotification).

Credential Status ​

credStatus values:

ValueNameMeaning
0DISABLEDNo credential / not available for this device
1AVAILABLECredential can be provisioned
3CREATEDCredential created, not yet provisioned
5REVOKEDCredential revoked
20PROVISIONEDCredential active in the wallet
26PROCESSINGProvisioning in progress

Setup status (Android credential bundle) values:

ValueName
-3DELETE_CONFIRMED
-1NOT_SETUP
0PROVISIONED_INACTIVE
2LOCATION_PERMISSION_REQUIRED
20PROVISIONED_ACTIVE
26PROVISIONED_PROCESSING

Template/issuer status values (used by the native pass state machine):

ValueName
0Disabled
1Available
4SuspendRequested
5Suspended
6UnlinkRequested
7DisableRequested
8ResumeRequested
20StatusActive

Issuers ​

IssuerPlatformIcon
APPLEiOSAdd_to_Apple_Wallet_rgb_US-UK.svg
HIDAndroidmobile_credential_btn.png
HID_WALLETAndroidmobile_credential_google_pay.png
ALLEGION (Google)Androidmobile_credential_google_pay.png

Native Bridge ​

The web app talks to native code through window.NativeInterface. The methods relevant to credentials:

MethodPurpose
getSessionIdCurrent session id
getInstitutionIdCurrent institution id
getUserInfoUser object
getAcceptedUserPhotoApproved ID photo
getAppleWalletInfoPass/credential state for Apple Wallet
addToAppleWalletStart Apple Wallet provisioning
getPatronBarcodeNative-generated barcode
addUSAePayCreditCardNative card entry for USAePay
ordersApplePay / depositsApplePayApple Pay payment sheets
updateNativeWithRouteSync current route to native shell

Apple Wallet native objects ​

The iOS binary defines:

  • GETPartnerServices, GETPartnerManager
  • GETParterServicesPassesBundle (passes), GETPartnerServicesCredStatus (credStatus), GETPartnerServicesHeaderResponse (responseHeader)
  • GETPartnerServicesProvisioningBundle, WalletProvisioningBundle (provisioningBundle, provisioningBundleIdentifier, referenceIdentifier)
  • activePassesFor:withCallback:, prepareProvisioningFor:withCallback:, appleWalletNetworkCallsWithSessionId:completion:
  • isIphoneInWallet, isWatchInWallet, canAddPass, notifyAppleWallet

If you are reimplementing the flow outside the app you must reproduce PKAddPaymentPassViewController certificate/nonce handling yourself; the partner activePasses endpoint alone is not enough to add a card to Apple Wallet.