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.
- Your company can only obtain partnership for a single Samsung account.
- Store your private key securely, as it is needed for wallet card management. Your encryption settings cannot be modified without administrator approval.
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:
- 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. - On your Samsung device, go to the “Add to Wallet” Test Tool and sign in with your Samsung Account.
- Select the card from the list and provide test data in the appropriate fields.
- In the “Partner’s Private Key” field, paste your decrypted private key. This must be the same private key that was used during onboarding.
-----BEGIN ENCRYPTED PRIVATE KEY-----
Once decoded, the key starts with the following text:
-----BEGIN PRIVATE KEY-----
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.
Figure 1: Wallet card launched
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).
Implementing “Add to Wallet” links
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.
