Appearance
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:
| Value | How to get it |
|---|---|
| OmniID JWT | POST /json/authentication retrieveExternalAuthenticationToken with externalSystem: "OmniID" |
| Authorization blob | POST /json/authentication retrieveAuthorizationBlob with the device model and OS version |
| Institution id | From 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/activePassesHeaders
| Header | Value |
|---|---|
Authorization | Bearer {OMNIID_JWT} |
institutionId | {INSTITUTION_UUID} |
Content-Type | application/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}"
}passesholds opaque pass/bundle data per device type.credStatusholds the credential status enum per device type.referenceIdentifieridentifies the credential and is required for unlink.
Device-type keys:
| Key | Platform | Meaning |
|---|---|---|
iPhone | iOS | Apple Wallet pass on the phone |
iWatch | iOS | Apple Wallet pass on the paired watch |
android_hid | Android | HID SEOS credential |
android_nxp | Android | Google Wallet / NXP credential |
android_hid_wallet | Android | HID 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.
Unlink a Credential
Revokes and removes a mobile credential.
plaintext
POST {partner_services_url}/partner/v1/managePass/referenceIdentifier/{referenceIdentifier}/action/getUnlinkHeaders
| Header | Value |
|---|---|
Authorization | Bearer {OMNIID_JWT} |
X-API-Key | {get.mobile_credentials.unlink_key} |
Content-Type | application/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
| Header | Value |
|---|---|
Authorization | Bearer {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:
| Value | Name | Meaning |
|---|---|---|
0 | DISABLED | No credential / not available for this device |
1 | AVAILABLE | Credential can be provisioned |
3 | CREATED | Credential created, not yet provisioned |
5 | REVOKED | Credential revoked |
20 | PROVISIONED | Credential active in the wallet |
26 | PROCESSING | Provisioning in progress |
Setup status (Android credential bundle) values:
| Value | Name |
|---|---|
-3 | DELETE_CONFIRMED |
-1 | NOT_SETUP |
0 | PROVISIONED_INACTIVE |
2 | LOCATION_PERMISSION_REQUIRED |
20 | PROVISIONED_ACTIVE |
26 | PROVISIONED_PROCESSING |
Template/issuer status values (used by the native pass state machine):
| Value | Name |
|---|---|
0 | Disabled |
1 | Available |
4 | SuspendRequested |
5 | Suspended |
6 | UnlinkRequested |
7 | DisableRequested |
8 | ResumeRequested |
20 | StatusActive |
Issuers
| Issuer | Platform | Icon |
|---|---|---|
APPLE | iOS | Add_to_Apple_Wallet_rgb_US-UK.svg |
HID | Android | mobile_credential_btn.png |
HID_WALLET | Android | mobile_credential_google_pay.png |
ALLEGION (Google) | Android | mobile_credential_google_pay.png |
Native Bridge
The web app talks to native code through window.NativeInterface. The methods relevant to credentials:
| Method | Purpose |
|---|---|
getSessionId | Current session id |
getInstitutionId | Current institution id |
getUserInfo | User object |
getAcceptedUserPhoto | Approved ID photo |
getAppleWalletInfo | Pass/credential state for Apple Wallet |
addToAppleWallet | Start Apple Wallet provisioning |
getPatronBarcode | Native-generated barcode |
addUSAePayCreditCard | Native card entry for USAePay |
ordersApplePay / depositsApplePay | Apple Pay payment sheets |
updateNativeWithRoute | Sync current route to native shell |
Apple Wallet native objects
The iOS binary defines:
GETPartnerServices,GETPartnerManagerGETParterServicesPassesBundle(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.