Tutorials Mobile

Seamlessly Integrate “Add to Wallet” for Samsung Wallet

M. A. Hasan Molla

Engineer, Samsung Developer Program

Samsung Wallet enables users to easily access various digital content, such as boarding passes, tickets, and coupons, on their Samsung device. Users can save the content to their Samsung Wallet by clicking an “Add to Wallet” button or link.

This article describes how to integrate your digital content with Samsung Wallet. Each piece of digital content is represented by a wallet card which you must create and launch within the Samsung Wallet portal. After successfully launching the card, you can create an “Add to Wallet” link for it.

Prerequisites

Before you can create wallet cards for Samsung Wallet, complete the Samsung Wallet partner registration and onboarding process, including encryption setup.

After onboarding, you receive an email with your public key and signed security certificate. Keep this information in a safe place.

Creating wallet cards

Samsung Wallet supports the following wallet card types:

  • Boarding pass
  • Event ticket
  • Coupon
  • Gift card
  • Loyalty card
  • ID card

Create your wallet card at the Samsung Wallet portal. You can create as many cards as you need. The Samsung Wallet portal also allows you to manage your cards and monitor their performance.

Testing wallet cards

Use the “Add to Wallet” test tool to test the card at any time, before or after launching it:

  1. In the Samsung Wallet portal, enable Testing mode for the card you want to test.
    Skip this step if you have already launched the card.
  2. On your Samsung device, go to the “Add to Wallet” Test Tool and sign in with your Samsung Account.
  3. Select the card from the list and provide test data in the appropriate fields.
  4. In the “Partner’s Private Key” field, paste your decrypted private key. This must be the same private key that was used during onboarding.
5. Tap the “Add to Samsung Wallet” button to add the card to Samsung Wallet on your device.

For more information about testing wallet cards, see “Add to Wallet” Test Tool.

Launching wallet cards

When you are ready to make the wallet card accessible to users, click “Launch” to start the verification process. Launching a card cannot be canceled.

undefined
undefined
undefined
undefined
undefined

Figure 1: Wallet card launched

undefined

The Samsung Wallet administrator reviews the card and approves or rejects it. If your card is rejected, check the rejection email for the reason. Modify the card to address the issue and launch it again.

For more information about wallet card verification, see Launch Wallet Cards (Verifying status) and Launch Wallet Cards (Rejected status).

After launching your wallet card, create a link that users can click to add the content to their Samsung Wallet.

  • To include the card data in tokenized form, use the following URL format:

    https://a.swallet.link/atw/v1/{Card ID}#Clip?cdata={CData Token}

    where:
    • {Card ID} path parameter is the unique identifier for the wallet card in the Samsung Wallet portal.
    • #Clip hash parameter is case-sensitive.
    • cdata query parameter contains the encrypted card data in JWT format. For more information, see the "CData token generation" section below.
  • If the encrypted card data is longer than 2048 bytes, or you do not want to include the tokenized data in the URL, store and reference the card data on your server. Create the URL in the following format:

    https://a.swallet.link/atw/v1/{Card ID}#Clip?pdata={Reference ID}

    where:
    • {Card ID} path parameter is the unique identifier for the wallet card in the Samsung Wallet portal.
    • #Clip hash parameter is case-sensitive.
    • pdata query parameter is the unique identifier for the card data stored on your server.

For more information on “Add to Wallet” links, see Add to Wallet Interface.

CData token generation

The card data in basic JSON format must be provided as a JWT (JSON Web Token). For token generation details, see Security. You can also study the CData generation sample code.

To ensure your CData token is valid, keep the following requirements in mind:

  • Pay attention to the mandatory fields in the card object.
  • All timestamps are UTC epoch time in milliseconds.
  • Card data attributes vary based on the card type. For detailed card data specifications, see Wallet Cards.
  • Your private key must match the key used for the security certificate signed by Samsung. If you are using the correct private key, the following commands generate the same hash: 
    $ openssl rsa -noout -modulus -in partner.key | openssl md5
$ openssl x509 -noout -modulus -in partner.crt | openssl md5
  • Generated JWT tokens expire in 30 seconds. The “Add to Wallet” link must be used within this time. Otherwise, you must generate a new token and new link.

Next steps

To integrate the “Add to Wallet” feature as a button in your application or website, see Implement the button.

You can update the information on a card that has been stored in a user’s Samsung Wallet by communicating between your server and the Samsung server. For information, see Server Interaction.

If you have any questions or face difficulties implementing the content in this article, you can contact Samsung Developer Support.

Recent Posts