Add to Samsung Wallet

'Add to Samsung Wallet' service also known as ATW, defines interfaces for users to conveniently add digital contents to Samsung Wallet.

Service flow

User-Initiated Links

Data Transmit Link

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.

Type	Value			Description
URL	https://a.swallet.link/atw/v3/{cardId}#Clip?cdata={cdata}
Path parameters	cardId	String	Required	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. * Refer to Security for more details.

Example

https://a.swallet.link/atw/v3/1656147182764415319#Clip?cdata=eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0ZWQgdGltZSIsInBhcnRuZXJJRCI6InBhcnRuZXIgSUQifQ.
… … … …
Dn0_oZ3xcr0JuQ3mlSzLIUTxFoTewnZ0MQj7kiNjysNm5Xfwqt5vcN20PeebeLgUx8VJXLy4_9G4BHQ-hd4O9POYuTuAWew.YzdlMTFhO -NYCeL3T0YzNzAD2KcK_HrtwIGEErHLGn6ydaq_fpFdSlxsA3ZJtNpg3wcuqEw5cIdpbPFswbQLropqEpNawg5nlm3DKAA4a1dzaZMbSR1BGZHrH_vIKnx3CY5MO0jNBexl_YIZ5_wB379UYSwumQiPiTZVg2IjYvfht17I4

Data Fetch Link

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.

Type	Value			Description
URL	https://a.swallet.link/atw/v3/{CertificateId}/{cardId}#Clip?pdata={pdata}
Path parameters	certificateId	String	Required	Certificate identifier based on a CSR during onboarding. 4 digits alphanumeric. * Must be generated from Partner Portal
	cardId	String	Required	Wallet card identifier. * It must be generated from Partners Portal.
Hash path parameters	#Clip	String	Required	Parameters for the Hash link
Query parameter	pdata	String	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

https://a.swallet.link/atw/v3/YMtt/1656147182764415319#Clip?pdata=sIgHCzIwM9g

Provider-Initiated API

Register Card API

This is an API that allows partners to provide wallet cards to users. Request payload must include user information. Then the user device is notified of card registration through a push notification.

Card Data Specification

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.

Request

Type	Value			Description
Method	POST
URL	/atw/v1/cards/{cardId}
Headers	Authorization	String(1024)	Required	Credential token. The token can have prefix "Bearer" as an authorization type. i.e., Bearer * See Authorization Token
	x-smcs-partner-id	String(32)	Required	Partner ID.
	x-request-id	String(32)	Required	Request identifier. Random generated UUID string.
	x-smcs-cc2	String(2)	Required	Country Code (ISO-3166-1 alpha-2) of User Account
Path Parameters	cardId	String(32)	Required	Wallet card identifier granted from Partner Portal
Body Parameters	cdata	Object	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 the chapter Security for more details.
payload object	card	Object	Required	Wallet card object
	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
	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 card language code. e.g. en, ko
	data[].attributes	Object	Required	Container of attributes
	data[].attributes.{fields}		Required	Attributes fields by card. type *See Wallet Cards
	data[].localization[]	Array of Object	Optional	Container of localizationed language *See Wallet Cards
	localization[].language	String(8)	Required	Multilingual contenct 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
	account	Object	Conditional	User Account object
	account .type	String	Required	Type of User identifier e.g. phoneNumber, email
	account .value	String	Required	User identifier

Example (Success)

* 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": "삼성 월렛"
                                }
            }]
  }]
},
"account": {
"type": "phoneNumber",
"value": "+821012345678”
}
}
* Example
POST /atw/v1/cards/1656147182764415319
[Headers] Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O... x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR
[Payload]
{
“cdata” : “eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0Z…”
}

Response

Type	Value	Description
HTTP Status	200 OK
Payload	N/A
Example	200 OK

Result

HTTP Status Code		Description
200	200 OK
400	400 Bad Request	Requests cannot or will not be processed the request due to something that is perceived to be a client error
401	401 Unauthorized	Authorization token is invalid or expired.
500	500 Internal Server Error
503	503 Service Unavailable