'Add to Wallet' Interfaces
Typical flow
Once the template is ready, partners receive an 'Add to Wallet' link. The following contents describe the web link and card data specification by types.
Web link includes identifier for the partner, and also card data in the URL format below.
[Link Format]
https://a.swallet.link/atw/v1/{Card Id}#Clip?cdata={encrypted data}
For backward compatibility, we also support:
https://api-card.walletsvc.samsung.com/wlt/{Product Id}/{Card Id}#Clip?cdata={encrypted data}
[Card Data Specification]
#Hash name and query parameters:
the hash name is '#Clip' (The first letter is capitalized)
Card ID:
{Card Id} is an ID issued when the partner manager signs up for partner services and register the wallet card they want to service. Refer to Partner Onboarding guide document for more details.
cdata:
Actual payload data in basic JSON format to communicate between partners and Samsung Wallet. See the details on the sheet below.
Card Data Token:
The specific wallet card data mentioned as cdata must be secured in JWT(JSON Web Token) format. See the chapter Security for more details.
Type | Value | Description | ||
---|---|---|---|---|
URL | https://a.swallet.link/atw/v1/{Card Id}#Clip?cdata={Card Data Token} | |||
Path Parameters | Card Id | String(32) | Required | Wallet card identifier *Must be generated from Partner Portal |
Hash Path Parameters | #Clip | String(5) | Required | Parameters for the Hash link *Fixed |
Query Parameters | cdata | Object | Required | Card object. (JSON) * This field needs to be encrypted. * See Security. |
Card object | card | Object | Required | Card information. |
card.type | String(16) | Required | Wallet Card type *See Wallet Cards |
|
card.subType | String(16) | Required | Wallet Card sub type *See Wallet Cards |
|
card.data[] | Array of Object | Required | Wallet card data container Allows up to 10 objects at once |
|
data[].refId | String(32) | Required | A unique content identifier defined by the content provider | |
data[].createdAt | Long(13) | Required | Data creation timestamp. Epoch timestamp in milliseconds. *UTC±00:00 | |
data[].updatedAt | Long(13) | Required | Data update timestamp. Epoch timestamp in milliseconds. *UTC±00:00 | |
data[].language | String(8) | Required | Default content language code. e.g., en, ko | |
data[].attributes | Object | Required | Attributes of card data. | |
data[].attributes.{fields} | Attribute fields by card type. *See Wallet Cards |
|||
data[].localization[] | Array of Object | Optional | Information for multilingual support. | |
localization[].language | String(8) | Required | Multilingual content language code. e.g., en, ko | |
localization[].attributes.{fields} | For displaying a given language, ‘data[].attributes’ can be replaced by localized versions. *See Wallet Cards |
Example: Card object
{
"card": {
"type": "ticket",
"subType": "movies",
"data": [{
"refId": "ref-20230304-001",
"createdAt": 1612660039000,
"language": "en",
"attributes": {
"title": "Samsung Wallet",
"mainImg": "https://../main.png"
*Refer to Wallet Cards
},
"localization": [{
"language": "ko",
"attributes": {
"title": "삼성 월렛"
}
}
]
}
]
}
}
- Refer to Wallet Cards
Example: web link
https://a.swallet.link/atw/v1/1656147182764415319#Clip?cdata=eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0ZWQgdGltZSIsInBhcnRuZXJJRCI6InBhcnRuZXIgSUQifQ.
… … … …
Dn0_oZ3xcr0JuQ3mlSzLIUTxFoTewnZ0MQj7kiNjysNm5Xfwqt5vcN20PeebeLgUx8VJXLy4_9G4BHQ-hd4O9POYuTuAWew.YzdlMTFhO -NYCeL3T0YzNzAD2KcK_HrtwIGEErHLGn6ydaq_fpFdSlxsA3ZJtNpg3wcuqEw5cIdpbPFswbQLropqEpNawg5nlm3DKAA4a1dzaZMbSR1BGZHrH_vIKnx3CY5MO0jNBexl_YIZ5_wB379UYSwumQiPiTZVg2IjYvfht17I4
Slim data flow
In some cases, the tokenized data exceeds specific character limits on browsers and should be truncated. In most cases, it is recommend that the JWT don't exceed 2048 bytes.
This chapter proposes an option which contains reference ID(refId) only for the web link. With the unique id, Samsung server attempts inquiring wallet card data in the typical flow data format. For details, see the chapter Get Card Data.
[Link Format]
https://a.swallet.link/atw/v1/{Card Id}#Clip?pdata={Reference Id}
[Card Data Specification]
pdata:
This has identification for each users' wallet card contents called refId. For secure transactions, reference ID must be in a form that cannot be inferred.
Type | Value | Description | ||
---|---|---|---|---|
URL | https://a.swallet.link/atw/v1/{Card Id}#Clip?pdata={refId} | |||
Path Parameters | Card Id | String | Required | Wallet card identifier * Must be generated from Partner Portal |
Hash Path Parameters | #Clip | String | Required | Parameters for the Hash link. |
Query Parameter | pdata | String | Required | Reference ID Unique ID defined by content provider |
Example | * Example: web link https://a.swallet.link/atw/1](https://a.swallet.link/atw/)656147182764415319#Clip?pdata=sIgHCzIwM9g |