The most common and straightforward method is the Data Transmit Link approach, which securely includes tokenized data in the ATW link. The ATW link format for this method is as follows.
The name Data Transmit Link has been changed from Typical flow.
Wallet card identifier issued from Partner portal when the partner manager signs up for partner services and registers the wallet card they want to service.
Hash path parameters
#Clip
String
Required
Parameters for the Hash link * The first letter is capitalized
Query parameters
cdata
String
Required
Actual payload data in basic JSON format to communicate between partners and Samsung Wallet. This must be secured in JWT(JSON Web Token) format. * See Security
In cases involving sensitive data or when providing static links, Data Fetch Link method is highly recommended. Links using this approach include only a unique reference ID, and Wallet Cards are added by querying data through Get Card Data path as specified in Partner portal.
The name Data Fetch Link has been changed from Slim data flow.
Please be aware that if the link is exposed to unintended users, it can be exploited. Please prepare the integration with this in mind.
It is crucial to ensure that the refId, used for a reference value, is generated in a manner that is not easily deducible by potential attackers.
Certificate identifier based on a CSR during onboarding. 4 digits alphanumeric. * Must be generated from Partner Portal
cardId
String(32)
Required
Wallet card identifier. * It must be generated from Partners Portal.
Hash path parameters
#Clip
String(5)
Required
Parameters for the Hash link
Query parameter
pdata
String(2048)
Required
Unique ID defined by content providers. This has identification for each user's Wallet Card contents. * For secure transactions, a Reference ID(refId) must be in a form that cannot be inferred.
Example
Example: web link
https://a.swallet.link/atw/v3/YMtt/1656147182764415319#Clip?pdata=sIgHCzIwM9g
Updating Wallet Cards
The added users’ cards allow updating its data using server interactions. Find the card details to configure API on Partner portal if partners want to manage the added cards.
Samsung server will notify the result of 'Add to Wallet' via Send Card State.
Partners get the callback URL for Samsung Server API from Send Card State payload.
Using the callback URL, partners can make actions for the added cards via Samsung Server API.
Depending on the interfaces, Samsung Server triggers specific operations. For example, when Update Notification is called, Samsung server calls partners' server to look up the updated contents.
Partner Server API
Samsung server can call the following API by using endpoint on the registered card information.
If the partner server manages an inbound allow list, contact us to register Samsung server IP address.
Get Card Data
Returns the current information of the card.
Request
Type
Value
Description
Method
GET
URL
{Partner server URL}/cards/{cardId}/{refId}?fields={fields}
Headers
Authorization
String (1024)
Required
Credential token. The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>. * see Authorization Token
Requests cannot or will not be processed the request due to something that is perceived to be a client error.
401 Unauthorized
Authorization token is invalid or expired.
500 Internal Server Error
Server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable
Server is not ready to handle the request.
Send Card State
Partners can manage the state or history of the card using this API.
If the Card state is changed on the Samsung device, Samsung calls this API using a refId.
Request
Type
Value
Description
Method
POST
URL
{Partner server URL}/cards/{cardId}/{refId}
Headers
Authorization
String (1024)
Required
Credential token. The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>. * See Authorization Token(/wallet/api_new/references/security.html)
The domains can be selectively used depending on your service requirement.
If the service needs to register static IPs on your system, we recommend using Private domain. In this case, use the domain received in the request 'callback' field from Send Card State API.
If the service does not require IP registration, Public domain can be a good choice. In this case, country code(cc2) is required as a path parameter.
To configure integration for each environment, register a new card service and get new card ID.
To guarantee safe communication, servers should configure Token-based Authentication. See Authorization Token for the details.
Update Notification
If wallet card data content is updated, send a notification to the Samsung server.
Request
Type
Value
Description
Method
POST
URL
{cc2}/wltex/cards/{cardId}/updates
Headers
Authorization
String (1024)
Required
Credential token. The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>. * See Authorization Token
Unique content identifier defined by the content provider
data[].state
String (16)
Required
Wallet card state. For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED. * See Card States for details
data[].fields
String (128)
Optional
Wallet Cards attributes which has been updated. Can be specified using commas(,) as separators. It is used when 'data[].state' is UPDATED. e.g. balance,barcode.value * Supported Wallet Card types: generic
Example:
POST /wltex/cards/12584806754/notification
[Headers]
Authorization: Bearer eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
[Payload]
(Case 1: In general cases)
{
"card": {
"type": "ticket",
"data": [
{
"refId": "ref-ticket-0001",
"state": "UPDATED"
}
]
}
}
(Case 2: In case of deletion)
{
"card": {
"type": "boardingpass",
"data": [
{
"refId": "ref-boardingpass-0001",
"state": "DELETED"
}
]
}
}
(Case 3: When a specific field is updated)
{
"card": {
"type": "idcard",
"data": [
{
"refId": "ref-idcard-0001",
"state": "UPDATED",
"fields": "balance"
}
]
}
}
Response
Type
Value
Description
HTTP Status
200 OK 204 No Content
Payload
N/A
Example
200 OK
Result
HTTP Status Code
Description
200 OK
Success.
204 No Content
Card doesn’t exist.
400 Bad Request
Requests cannot or will not be processed the request due to something that is perceived to be a client error.
401 Unauthorized
Authorization token is invalid or expired.
500 Internal Server Error
Server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable
Server is not ready to handle the request.
Cancel Notification
If a cancelation happens for events such as performances, sports, movies, and journeys, partners can send a notification about it and set all of the related cards to expire.
This API does not support updates for specific attributes on the card.
Request
Type
Value
Description
Method
POST
URL
{cc2}/wltex/cards/{cardId}/cancels
Headers
Authorization
String (1024)
Required
Credential token. The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>. *See Authorization Token
Required if "card.type" has been set as "boardingpass".
data[].estimated OrActualStartDate
Long (13)
data[].state
String (16)
Required
Wallet card state. For example CANCELED * See Card States for details
Example:
POST /wltex/cards/12584806754/cancelation
[Headers]
Authorization: Bearer eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140004
[Payload]
* A movie ticket has been canceled.
{
"card": {
"type": "ticket",
"data": [
{
"eventId": "event-722164a1a7",
"state": "CANCELED"
}
]
}
}
Response
Type
Value
Description
HTTP Status
200 OK
Payload
N/A
Example
200 OK
Result
HTTP Status Code
Description
200 OK
Success.
204 No Content
Card doesn’t exist.
400 Bad Request
Requests cannot or will not be processed the request due to something that is perceived to be a client error.
401 Unauthorized
Authorization token is invalid or expired.
500 Internal Server Error
Server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable
Server is not ready to handle the request.
Implementing Button
For Wallet integration, you need to insert ‘Add To Wallet’ script into your system. We usually follow the procedures below to implement the ‘Add to Wallet’ button
Second, create tokenized card data (Cdata) and insert the data token into the script above. Card data is the actual content data of wallet cards and has several formats based on card type. Please See Generate_Cdata Sample Code for detail.
ImportantCdata token should expire in 30 seconds after creation, so cdata token needs to be created right after users actually click “Add to Wallet” button.
To implement ‘Add to Wallet’ button, you may need some base data. You can find the base data and other necessary information on Partner portal’s Wallet card page.
Samsung Wallet on the Web
This section explains how to implement an "Add to Wallet" button using JavaScript in a web view.
Web Button Reference with importing API Javascript
If you implement the "Add to Wallet" button using this script, the button is shown only on the devices that support Samsung Wallet.
To automatically parse <samsung:wallet> HTML tags when the page is loaded, include the following standard JavaScript:
You can use these tags or JavaScript functions for the web button if you're rendering HTML and you have proper partner permissions. You can also use the script by referring to the various attributes.
samsung:wallet HTML Tag
The ‘samsung:wallet’ namespace tag defines the placement and various attributes of the "Add to Wallet" web button for Samsung Wallet.
Wallet card identifier * Value granted from the Partners Portal.
cdata
String
Y
Encrypted card object (JSON). * This field needs to be encrypted. * See Security
partnercode
String
Y
Partner code. * Value granted from the Partners portal.
buttonid
String
Y
DOM element ID for the "Add to Wallet" web button for Samsung Wallet
buttontype
String
N
"Add to Wallet" button type. [ "btnSW" / "btnATSW", default : btnSW ] * See Image resources
inline
String
N
Flag to display the "Add to Wallet" image button in one-line format. Default: true (one-line).
locale
String
N
Locale of the "Add to Wallet" image button. * See Image resources
rdclickurl
String
Y
URL for logging a button click event. * Value granted from the Partners Portal.
rdimpressionurl
String
Y
URL for logging a button impression event. * Value granted from the Partners Portal.
showforced
String
N
Flag to force the "Add to Wallet" button to be displayed. Default: false.
mediatheme
String
N
Load the button’s resources from the media theme policy. There are 4 themes: default, inversion, lightonly, and darkonly. Default: default. *default: Load the button’s theme according to the prefers-color-scheme policy. *inversion: Load the inverse of the default button’s theme. *lightonly: Load the light theme of the default button. *darkonly: Load the dark theme of the default button.
style
String (CSSStyleDeclaration)
N
Load the button with custom style
target
String
N
Option to choose button’s target name * default : “WALLET”
onshowbutton
Function
N
Callback handler function for the button’s on-show event
onclickbutton
Function
N
Callback handler function for the button’s on-click event. If you register the handler function, you must return a callback or promise value. * See Usage of onClickButton Handler .
samsungWallet.addButton Function
This function allows you to explicitly render the Samsung Wallet API for the "Add to Wallet" web button.
Unlike the samsung:wallet HTML tag, you must use camelCase in the button attributes in function case.
Attributes
Type
Required
Description
cardId
String
Y
Wallet card identifier. * Value granted from the Partners Portal.
cdata
String
Y
Encrypted card object (JSON). * This field needs to be encrypted. * See Security
partnerCode
String
Y
Partner code. * Value granted from the Partners Portal.
targetId
String
Y
DOM (Document Object Model) Element ID to place the "Add to Wallet" web button for Samsung Wallet
buttonId
String
Y
DOM Element ID for the "Add to Wallet" web button for Samsung Wallet
buttonType
String
N
"Add to Wallet" button type ("btnSW" and "btnATSW") Default : btnSW * See Image resources
inline
String
N
Flag to display the "Add to Wallet" image button in one-line format. Default: true (one-line).
locale
String
N
Locale of the "Add to Wallet" image button. * See Image resources
RDClickUrl
String
Y
URL of logging a button click event. * Value granted from the Partners Portal.
RDImpressionUrl
String
Y
URL of logging a button impression event. *Value granted from the Partners Portal.
showForced
String
N
Flag to force the "Add to Wallet" button to be displayed. Default: false.
mediaTheme
String
N
Load the button’s resources from the media theme policy. There are 4 themes: default, inversion, lightonly, and darkonly. Default: default. *default: Load the button’s theme according to the prefers-color-scheme policy. *inversion: Load the inverse of the default button’s theme. *lightonly: Load the light theme of the default button. *darkonly: Load the dark theme of the default button.
style
Object (CSSStyleDeclaration)
N
Load the button with a custom style
target
String
N
Option to choose button’s target name * default : “WALLET”
onShowButton
Function
N
Callback handler function for the button’s on-show event.
onClickButton
Function
N
Callback handler function for the button’s on-click event. If you register the handler function, you must return a callback or promise value. * See Usage of onClickButton Handler
Usage of onClickButton Handler
You can choose whether to proceed with the next "Add to Wallet" step using a promise or a callback function, if you register a callback handler in onClickButton. We recommend that you add the process of generating JWT cdata (add cdata to options.cdata) to this handler, because of the cdata expiration time. The function parameters are defined as follows.
Attributes
Type
Required
Description
options
Button attributes
N
Attributes of the current button
callback
Function
N
Callback function to pass the flag to proceed. Default: false.
(Promise resolve)
Function
N
Promise-resolved value to pass the flag to proceed Default: false.
Callback to web button process from callback attributes (for ES5)
By executing a callback function with a flag, you can proceed to the next 'Add to Wallet' process.
onClickButton: function (options, callback) {
// TODO partner's process
callback(flag)
}
Callback to web button process from returning Promise (for ES6)
By returning a promise with a resolving flag, you can proceed to the next ‘Add To Wallet’ process.
onClickButton: async (options) => {
return new Promise(async (resolve, reject) => {
// TODO partner's process (await)
resolve(flag)
})
}
ImportantThe card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “Add to Wallet” button.
Samsung Wallet on the App
The following outline explains how to implement the "Add to Wallet" button on a native application.
Get button graphic resources from a repository depending on your service environment. For more information, See Image resources.
Check availability by calling the "Check service available devices" APO, then determine whether to show up the "Add to Wallet" button on the user device.
A. If "available" on response has "true" -> SUPPORT
B. If has "false" -> NOT SUPPORT
Implement a JWT web link on the button triggered action.
App Button Reference
App Button on Android
Sample code implementation
public class WalletCodeSample {
protected final static String TAG = "SamsungWalletSample";
protected static final String HOST = "https://api-us3.mpay.samsung.com";
protected static final String PATH = "wallet/cmn/v2.0/device/available";
/**
* sample entry point of the usage
*/
public static void main() {
Executors.newSingleThreadExecutor().submit(() -> {
final String modelName = Build.MODEL;
final String countryCode = null; // (optional) country code (ISO_3166-2)
final String serviceType = "WALLET"; // (Required, fixed) for Samsung Wallet
final String partnerCode = null; // (Required)
try {
WalletCodeSample sample = new WalletCodeSample();
boolean isWalletSupported = sample.checkWalletSupported(
modelName, countryCode, serviceType, partnerCode);
String msg = String.format(
"query for model(%s), countryCode(%s), serviceType(%s), partnerCode(%s) / wallet supported? (%s)",
modelName,
countryCode,
serviceType,
partnerCode,
isWalletSupported);
Log.d(TAG, msg);
} catch (Exception e) {
// failed to check due to some reasons
Log.e(TAG, e.getMessage(), e);
}
});
}
/**
* please See the Wallet API Spec document > '6.6 Check service available devices' for more details
*
* @return true if wallet supported, otherwise false
* @throws Exception throws exception when it's not possible to get status due to any reasons
*/
public boolean checkWalletSupported(@NonNull String modelName, @Nullable String countryCode,
@NonNull String serviceType, @NonNull String partnerCode) throws Exception {
if (modelName == null || modelName.isEmpty()) {
Log.e(TAG, "model name is Required parameter");
throw new Exception("something went wrong (failed to get device model name)");
}
if (serviceType == null || serviceType.isEmpty()) {
Log.e(TAG, "serviceType is Required parameter");
throw new Exception("something went wrong (failed to get device serviceType)");
}
if (partnerCode == null || partnerCode.isEmpty()) {
Log.e(TAG, "partnerCode is Required parameter");
throw new Exception("something went wrong (failed to get device partnerCode)");
}
String urlString = makeUrl(modelName, countryCode, serviceType);
Log.i(TAG, "urlString: " + urlString);
try {
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestProperty("partnerCode", partnerCode);
connection.setRequestMethod("GET");
int responseCode = connection.getResponseCode();
Log.i(TAG, "responseCode: " + responseCode);
BufferedReader bufferedReader;
if (responseCode == 200) {
bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
} else {
bufferedReader = new BufferedReader(new InputStreamReader(connection.getErrorStream()));
}
StringBuilder sb = new StringBuilder();
String inputline;
while ((inputline = bufferedReader.readLine()) != null) {
Log.i(TAG, inputline);
sb.append(inputline);
}
connection.disconnect();
bufferedReader.close();
// parse result
JSONObject jsonObject = new JSONObject(sb.toString());
String resultCode = jsonObject.getString("resultCode");
String resultMessage = jsonObject.getString("resultMessage");
if ("0".equals(resultCode) && "SUCCESS".equals(resultMessage)) {
return jsonObject.getBoolean("available");
} else {
throw new Exception("something went wrong, resultCode(" + resultCode + "),
resultMessage(" + resultMessage + ")");
}
} catch (IOException e) {
Log.e(TAG, e.getMessage(), e);
throw new Exception("something went wrong (IOException), " + e.getMessage());
} catch (JSONException e) {
Log.e(TAG, e.getMessage(), e);
throw new Exception("something went wrong, receive wrong formatted response, " + e.getMessage());
}
}
protected String makeUrl(@NonNull String modelName, @Nullable String countryCode, @NonNull String serviceType) {
StringBuilder sb = new StringBuilder();
sb.append(HOST).append('/');
sb.append(PATH);
sb.append('?').append("serviceType").append('=').append(serviceType);
sb.append('&').append("modelName").append('=').append(modelName);
if (countryCode != null && !countryCode.isEmpty()) {
sb.append('&').append("countryCode").append('=').append(countryCode);
}
return sb.toString();
}
}
ImportantThe card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “Add to Wallet” button.
Samsung Wallet on an MMS/Email
The following guides how to configure wallet code on email and MMS messages.
Implement the Data Fetch Link process, including server APIs. You need to create a unique "reference ID". For security reasons, make sure the "reference ID" is complex enough that no important information can be inferred.
Deliver a message including the web link through the chosen message platform. For MMS, the designed link shows up as a "Smart Suggestion" on Samsung devices. You can find a sample web link on the Wallet Cards guide on the Partners Portal.
For card data, Samsung Wallet asks the partner system to provide card details through the server API.
Duplicate requests are prohibited on the same device.
Link to “Add to Wallet” on an MMS/Email
You can add an “Add to Wallet” web button even in environments where the JavaScript API cannot be loaded, such as SMS or email.
These methods do not support controlling “Add to Wallet” button visibility.
MMS Link
URL Link: URL
Attributes
Type
Required
Description
URL
String
Y
“Add to Wallet” link URL. * See [Data Transmit Link][Data Transmit Link] * See [Data Fetch Link][Data Transmit Link]
Impressions logging URL. * Value granted from the Partners Portal.
Statistics Service
Samsung Wallet serves useful statistics data of the integrated service on the Partners Portal. The data configured by making simple API calls for each event such as button impression and click. These are necessary to provide better services as well.
NoteStatistics API sample code
You can find actual code sample at wallet script guide section in ‘Wallet Cards’ menu on the partner portal.
{event}:
For each event in the following situations:
- impression: When the “Add to Wallet” button has been shown
- click: When the “Add to Wallet” button has been clicked
{parameters}:
Includes key factors to figure out the service.
{channel}:
- app: "Samsung Wallet" button in a native application
- web: "Samsung Wallet" button on the web
- email: "Samsung Wallet" button in an email
For details, please visit 'Wallet Cards' menu on the partner portal.
Manage Your Cookies
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
.samsungdeveloperconference.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
LinkedIn
.ads.linkedin.com, .linkedin.com
Advertising Cookies
These cookies gather information about your browser habits. They remember that
you've visited our website and share this information with other organizations such
as advertisers.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Preferences Submitted
You have successfully updated your cookie preferences.
