'Add to Wallet' Interfaces

Typical flow

Once a 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, but also card data in the below URL format.

[Link Format]

https://a.swallet.link/atw/v1/{Card Id}#Clip?cdata={encrypted data}

For backward compatibility, we support also:
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 capital)

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 details.

cdata:
Actual payload data in basic JSON format to communicate between partners and Samsung Wallet. See the details on the below sheet.

Card Data Token:
The specific wallet card data mentioned as cdata must be secured in JWT(JSON Web Token) format. See a chapter Security for details.

Type	Value			Description
URL	https://a.swallet.link/atw/v1/{Card Id}#Clip?cdata={Card Data Token}
Path Parameters	Card Id	String(32)	Mandatory	Wallet card identifier * It must be generated from Partner Portal
Hash Path Parameters	#Clip	String(5)	Mandatory	Parameters for the Hash link *Fixed
Query Parameters	cdata	Object	Mandatory	Card object. (JSON) * This field needs to be encrypted. * See Security.
Card object	card	Object	Mandatory	Card information.
	card.type	String(16)	Mandatory	Wallet Card type *See Wallet Cards
	card.subType	String(16)	Mandatory	Wallet Card sub type *See Wallet Cards
	card.data[]	Array of Object	Mandatory	Wallet card data container Allows up to 10 objects at once
	data[].refId	String(32)	Mandatory	A unique content identifier defined by the content provider
	data[].createdAt	Long(13)	Mandatory	Data creation timestamp. Epoch timestamp in milliseconds. *UTC±00:00
	data[].updatedAt	Long(13)	Mandatory	Data update timestamp. Epoch timestamp in milliseconds. *UTC±00:00
	data[].language	String(8)	Mandatory	Default content language code. e.g., en, ko
	data[].attributes	Object	Mandatory	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)	Mandatory	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": "Parasite",
                    "mainImg": https://../main.png
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "Samsung Wallet"
                        }
                    }
                ]
            }
        ]
    }
}

• 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 browser can be truncated. In most cases, recommendation is that the JWT don't exceed 2048 bytes.

This chapter proposes a 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 a 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 guarantee 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	Mandatory	Wallet card identifier * It must be generated from Partner Portal
Hash Path Parameters	#Clip	String	Mandatory	Parameters for the Hash link.
Query Parameter	pdata	String	Mandatory	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