4.1 Overview

Samsung Online Relying party supports two modalities:

  • Online same-device RPApp-to-WalletApp
  • Online same-device Web-to-Wallet App

We currently do not support Cross-device functionality. The identity verification as part of Samsung Wallet is accomplished with the "Verify with Samsung Wallet" button. This section describes the flows that are two currently supported: the App2App and Web2App ones. RP Partners should select the model based on their integration preference.

4.1.1 Same-device App2App (via Native Wallet SDK)

Diagram with numbered flows

Explanation of each flow

  1. Makeup contents
  2. Load Button resources
    The Verify with Samsung Wallet Integration and the sample code are both supported
  3. Check Service Available Devices
    This is the process of checking whether the device supports the Verify with Samsung Wallet function. RP Partners can implement it by referring to the provided sample code.
  4. Show button with web link
    You can implement it by referring to the provided sample code.
    Refer to the Data Transmit Link
  5. Tokenize card data as JWT
    This step generates cdata and Card Data Token.
    Refer to the Implementing VWW button
  6. Verify with Samsung Wallet link
    The link will invoke the WalletApp using AppLink technology. In the meantime, the App2app SDK makes a direct connection between the WalletApp and PartnerApp
  7. getMdocRequestData(DeviceEngagementBytes)
    The WalletApp makes DeviceEngagementBytes according to the ISO-18013-5 and send it to the PartnerApp
  8. sendMdocRequestData(sessionEstablishment)
    The PartnerApp build sessionEstablishmentBytes (ISO-18013-5) and encrypt it with HKDF (ISO-18013-5, 9.1.1.5 Cryptographic operations)
  9. sendMdocResponse(encryptedResponse)
    The WalletApp sends an encrypted ISO-18013-5 response payload to the PartnerApp

4.1.2 Same-device Web2App (via Wallet API)

Diagram with numbered flows

Explanation of each flow

  1. Makeup contents
  2. Load Button resources
    Verify with Samsung Wallet Integration and the sample code both supported
  3. Check Service Available Devices
    This is the process of checking whether the device supports the Verify with Samsung Wallet function. RP Partners can implement this by referring to the provided sample code.
  4. Show button with web link
    RP Partners can implement this by referring to the provided sample code.
    Refer to the Data Transmit Link
  5. Tokenize card data as JWT
    This step generates cdata, Card Data Token.
    Refer to the Implementing VWW button
  6. Verify with Samsung Wallet link
    The link will invoke the WalletApp using the AppLink technology
  7. Transfer DeviceEngagement
    The WalletApp makes DeviceEngagementBytes according to the ISO-18013-5 and sends it to the PartnerServer through the Wallet Server
  8. Request key API Send Key
    The Wallet Backend Server converts the data received from the request and cardId information into JWT (JWS + JWE) and delivers it to the partner server.
  9. The partner server must decrypt the JWT (JWS + JWE) data again.
  10. The PartnerApp build sessionEstablishmentBytes (ISO-18013-5) and encrypt it with HKDF (ISO-18013-5, 9.1.1.5 Cryptographic operations)
  11. The partner server must create and transmit the data fields required for authentication as JWT (JWS + JWE) in response to the Wallet Backed Server.
  12. Partners should refer to the code links below for encryption, decryption, require Data.
  13. Send Mdoc response
    The WalletApp sends an encrypted ISO-18013-5 response payload to the PartnerServer through the Wallet Server
  14. Request auth API Send authentication data
    The authentication data card information received in step 14 is converted into JWT (JWS+JWE) and transmitted to the partner server.
    The partner server must decrypt the JWT (JWS + JWE) data again.

RP Partner can refer to the code links below for decryption, verify.
Cross-device (Not Supported)
Currently, Samsung Wallet does not support Cross-device functionality. This functionality will be added soon.

Pre-requisites – Technical and System Requirements

  • Samsung Wallet currently supports same-device RP functionality only. Device and Android OS version limitations are given below:
    • Driver's Licenses or State IDs can be added to the following Galaxy devices
      • Galaxy S Series - S20 or later
      • Galaxy Z Series - Z Flip 5G, Z Fold 5G, Z Flip 2, and Fold 2 or later
      • Galaxy A Series - A53, A54
    • Mobile Driver's License or State ID is only available on devices running Android 12(S) or later
  • App2App SDK (RpSdk) Requirements
    • Minimum Android SDK : RpSdk requires a minimum API level of 26
    • Kotlin : 1.7.10 is required

Integration Steps

The following steps describe the integration process

  • Step 1. Samsung Wallet portal on-boarding. Please refer Wallet Portal On-boarding Information
    • Review the Samsung Wallet portal on-boarding guide.
    • Register in the Samsung Wallet portal and proceed with on-boarding process.
    • Create a wallet card as the 'Relying Party' type in Wallet portal.
  • Step 2. Select App2App or Web2App
  • Step 3. Test 'Verify with Samsung Wallet' function and release the function to user
    • Test overall 'Verify with Samsung Wallet' function.
    • Remove test mode in Wallet portal after test is done.
    • Expose the 'Verify with Samsung Wallet' function to the user in Partner side.