PingOne Platform APIs

Digital Wallets

The Digital Wallet service controls the relationship between a user’s phone wallet app, which uses the Wallet SDK, and the customer’s PingOne application. It also offers notifications when the PingOne application communicates with the user’s Wallet SDK. Settings on the Digital Wallet configure sending push notifications from PingOne Credentials to the Wallet SDK of the user.

In the normal digital wallet pairing use case, you use Create Digital Wallet to create the Digital Wallet without the applicationInstance.id and a pairing session is created. The Digital Wallet service uses the digital_wallet_pairing notification template to send the pairing session URL (refer to appOpen.href in the response) to the user via email or text or you show a QR code (refer to qrUrl.href in the response) of the pairing session URL to the user. When the user opens the URL, it opens your app or takes them to a page with instructions on how to install the app. When the app opens the URL, it shares its applicationInstance.id with the service using the Wallet SDK.

Alternatively, you send the applicationInstance.id when you create the Digital Wallet. For example, if you have the user install your app, the user authenticates with your servers. When your app is installed, it creates an application instance. Since the app knows who the user is, the app sends its application instance identifier to your server and then your application sends the applicationInstance.id to the service when creating or updating the Digital Wallet. This creates a Digital Wallet with a known application instance identifier. Activation of the Digital Wallet requires sending some device data, such as SDK version and application bundle ID or package name, to PingOne Credentials:

  1. The service creates a pairing session and sends a pairing request message to the device.

  2. The Wallet SDK receives this request and the app approves the request.

  3. The Wallet SDK sends the device data to PingOne Credentials, which activates the Digital Wallet.

Digital wallet data model

Property Type Required? Mutable? Description

applicationInstance.id

String

Required/Optional

Immutable

Identifier (UUID) of the application running the Wallet SDK on the user’s device and registered with the service. Registration is required before the wallet can be used. Registration is performed by a compatible wallet app using the Wallet SDK, or by the customer application using Create Digital Wallet or one Update Digital Wallet.

createdAt

DateTime

N/A

Read-only

Date and time the Digital Wallet was created.

deviceData

Object

N/A

Read-only

Contains metadata collected about the user’s Wallet SDK.

digitalWalletApplication.id

String

Required

Immutable

Identifier (UUID) of the customer’s PingOne application that interacts with the user’s Wallet SDK.

environment.id

String

N/A

Read-only

PingOne environment identifier (UUID) in which the digital wallet app exists.

id

String

N/A

Read-only

Identifier (UUID) associated with the digital wallet.

notification

Object

Optional

Immutable

Contains notification information. When this property is supplied, the information within is used to create a custom notification.

notification.methods

String[]

Optional

Immutable

Array of methods for notifying the user; can be EMAIL, SMS, or both.

notification.results

Object[]

N/A

Read-only

Array of objects that contain the results of attempts to notify the user.

notification.results.error

Object

N/A

Read-only

Contains information regarding why a notification failed to send.

notification.results.error.code

String

N/A

Read-only

A short alphanumeric code identifying the error.

notification.results.error.details

Object[]

N/A

Read-only

Array of objects that contain details of the error as provided by the source of the error. Exact format varies by source.

notification.results.error.id

String

N/A

Read-only

Identifier (UUID) of the error message.

notification.results.error.message

String

N/A

Read-only

A textual message explaining the error.

notification.results.method

String

N/A

Read-only

Method used in the attempt to notify the user; can be EMAIL or SMS.

notification.results.notification.id

String

N/A

Read-only

Identifier (UUID) of the notification that was sent.

notification.results.sent

Boolean

N/A

Read-only

Whether the notification was successfully sent.

notification.template

Object

Optional

Immutable

Contains template parameters.

notification.template.locale

String

Optional

Immutable

The ISO 2-character language code used for the notification; for example, en.

notification.template.variables

Object[]

Required/Optional

Immutable

An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, refer to Dynamic variables.

notification.template.variant

String

Optional

Immutable

The unique user-defined name for the content variant that contains the custom message text used for the notification. For more information on variants, refer to Creating custom contents.

pairingAttempts

Object[]

N/A

Read-only

Array of result objects of all pairing attempts between the Digital Wallet and the Wallet SDK. Not returned when no pairing was attempted or when creating a Digital Wallet.

pairingAttempts.attemptedAt

DateTime

N/A

Read-only

Date and time the credential pairing was attempted.

pairingAttempts.details

Object

N/A

Read-only

Object with details regarding a pairing failure. Not returned when a pairing was successful. Content of the object varies depending on the error as explained in the Description column of Pairing attempt errors.

pairingAttempts.error

String

N/A

Read-only

As listed in the Error column of Pairing attempt error.

pairingAttempts.message

String

N/A

Read-only

Explanation of the error.

pairingAttempts.success

Boolean

N/A

Read-only

Whether the pairing attempt was successful.

pairingSession

Object

N/A

Read-only

Contains information regarding the pairing session.

status

String

Optional

Mutable

Status of the wallet; can be PAIRING_REQUIRED, ACTIVE, EXPIRED, or DISABLED.

updatedAt

DateTime

N/A

Read-only

Date and time the digital wallet was last updated; can be null.

user.id

String

N/A

Read-only

Identifier (UUID) of the user associated with the digital wallet.

Pairing attempt errors

Error Description

APP_PACKAGE_MISMATCH

The package name or bundle ID sent by the Wallet SDK does not match the mobile settings of the PingOne Application (identified by digitalWalletApplication.id), details includes what was sent by the Wallet SDK in appPackage.

WALLET_ALREADY_PAIRED

The digital wallet is already successfully paired or the instance of the Wallet SDK on the device has already been paired with a different digital wallet of the same user. If a user attempts to pair the same digital wallet twice, details includes the new application instance ID in newApplicationInstanceId. If a user attempts to pair the same Wallet SDK instance with a second digital wallet, details includes the existing digital wallet ID in existingDigitalWalletId.

WALLET_DISABLED

Wallet is disabled.

UNEXPECTED_ERROR

An unexpected error occurred in the service, no details object returned.

The digital wallet service uses the digital_wallet_pairing notification template to send the pairing session URL to the user via email or SMS text. The notification.template object can define a variant and locale for the notification, if needed.

Provisioned Credentials data model (wallet)

This object is shared with user credentials. It is returned only with Read One Digital Wallet Credentials and Read One User Credential Wallets. The former returns all user credentials associated with the specified digital wallet, the latter returns all digital wallets associated with the specified user credential.

Property Type Required? Mutable? Description

claimReference

Object

N/A

Read-only

The serialized JSON object used to create the ClaimReference object returned. This is needed to revoke an issued credential.

createdAt

DateTime

N/A

Read-only

Date and time the credential was provisioned.

credential.id

String

N/A

Read-only

Identifier (UUID) of the user credential associated with the provisioned credential.

digitalWallet.id

String

N/A

Read-only

Identifier (UUID) of the digital wallet associated with the provisioned credential.

environment.id

String

N/A

Read-only

Identifier (UUID) of the environment associated with the provisioned credential.

expiresAt

Date

N/A

Read-only

The date that the provisioned credential expires. If this value is null, the provisioned credential never expires.

id

String

N/A

Read-only

Identifier (UUID) of the provisioned credential.

status

String

N/A

Read-only

Status of the provisioned credential. Can be CREATED, ACCEPTED, REJECTED, REVOKED, or DELETED.

user.id

String

N/A

Read-only

Identifier (UUID) of the user associated with the provisioned credential.

walletActions

Object[]

N/A

Read-only

Array of actions taken regarding the provisioned credential.

walletActions.action

String

N/A

Read-only

Action taken regarding the provisioned credential; can be CREDENTIAL_ACCEPTED, CREDENTIAL_REJECTED, CREDENTIAL_REVOKED, or CREDENTIAL_DELETED.

walletActions.occurredAt

DateTime

N/A

Read-only

Date and time that the action occurred.