Server-Initiated Adding Wallet Card

This subsection defines the server-initiated flow for adding wallet cards and how Samsung Wallet determines which user to register the card to based on the account object embedded in the card payload.

High-level Flow

1. Partner backend prepares the wallet card payload (card + optional account) and required metadata.
2. The card payload is securely tokenized using JWT and supplied in the cdata body parameter when calling the server Add API (POST /atw/v1/cards/{cardId}).
3. Samsung Wallet receives and validates the request, then inspects the account object to determine the target user.
4. If a push notification is required by policy or template configuration, Samsung Wallet sends a push to the resolved device/account.
5. The card is registered to the resolved user/device and the card instance lifecycle starts.

Account object & User Resolution

When present, the account object is conditional but, if provided, is used to identify the target recipient of the server-initiated card. The account object structure (from the payload) is:

 "account": {
    "type": "phoneNumber", // e.g. phoneNumber, email, etc. 
    "value": "+821012345678" 
 }

The account.type values supported and their meaning are:

Type	Requires additional configuration	Description
email	X	Email address registered with Samsung Account. e.g., test@google.com
phoneNumber	X	Phone number registered with Samsung Account on. e.g., +821012345678
extPmId	O	Partner-specific user identifier issued by Payment service.
pmId	O	Partner-specific user identifier issued by Wallet service.
dmId	O	User device identifier issued by Wallet service.
saId	O	Samsung Account identifier.
CI	O	Identification value for distinguishing Korean users.

Resolution logic (summary)

• If account.type is email or phoneNumber, Samsung Wallet attempts to locate the Samsung Account matching that value and deliver/register the card against that account.
• If account.type is one of the optional identifiers (extPmId, pmId, dmId, saId, CI), Samsung Wallet will use partner-specific mappings and preconfigured integrations (Partner Portal configuration / agreements) to resolve the target user or device. These modes may require prior coordination or additional configuration from the partner.
• If account is omitted or cannot be resolved, Samsung Wallet follows the fallback policy specified by the template / partner configuration (for example, rejecting the request, logging for manual reconciliation, or requiring a different delivery flow such as Data-Fetch). (Policy specifics depend on partner onboarding and template settings in the Partner Portal.)

Security & Operational requirements

• All card payloads must be JWT-tokenized and calls authenticated (see Chapter 3).
• Partners must ensure the account.value is normalized (e.g., E.164 for phone numbers) and matches the Samsung Account data format expected by Wallet.
• Use of optional account types (extPmId/pmId/dmId/saId/CI) requires prior configuration in the Partner Portal and, where applicable, contractual/technical setup per onboarding guidance.

Adding Wallet Card APIs

A typical addition to the wallet card is triggered by user interaction, such as pressing the Add To Wallet button or link. The API also supports adding a wallet card automatically to the user for a special purpose with user’s consent.

This API allows partners to provide wallet cards to users. The request payload must contain information about the target to which the card is added. This information may be related to the user’s account, or it may contain information about a card that is already registered. A push notification is sent to the user’s device to confirm successful card registration. The success of card registration must be determined that the card is registered normally when it is updated to ADDED of Send Card State (Send Card Event).

An administrator must grant permission for partners to use this API.

Card Data Specification

Card ID:
{cardId} 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] Partner Onboarding guide document for details.

cdata:
Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. See the details in the table below.

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)	(Optional) Credential token. The token can have prefix "Bearer" as an authorization type. i.e., Bearer <credentials> * See the REST API Authorization Token (JWT / JWS).
	x-smcs-partner-id String(32)	(Required) Partner ID.
	x-request-id String(32)	(Required) Request identifier. Random generated UUID string.
Path Parameters	cardId String(32)	(Required) Wallet card identifier granted through the Partner Portal.
Body Parameters	cdata Object	(Required) Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. This must be in the secure JWT (JSON Web Token) format. * See the chapter Card Data Token (cdata) for more details.
payload object	card Object	(Required) Partner ID.
	card.type String(16)	(Required) Wallet Card type. *See Card Specs
	card.subType String(32)	(Required) Wallet Card sub type. *See Card Specs
	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 creation 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) Attributes container.
	data[].attributes.{fields}	(Required) Attributes fields by card.type *See Card Specs
	data[].localization[] Array of Object	(Optional) Localized language container. *See Card Specs
	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 Card Specs
	account Object	(Conditional) User account object.
	account .type String(16)	(Required) Type of user identifier, e.g. phoneNumber, email. See Account object & User Resolution
	account .value String(64)	(Required) User identifier.

Example: Card object

{
    "card": {
        "type": "ticket",
        "subType": "movies",
        "data": [{
            "refId": "ref-20230304-001",
            "createdAt": 1612660039000,
            "language": "en",
            "attributes": {
                "title": "Samsung Wallet",
                "mainImg": "https://{base-url}/main.png"

                    *Refer to Wallet Cards

            },
            "localization": [{
                "language": "ko",
                "attributes": {
                    "title": "삼성 월렛"
                }
            }]
        }]
    },
    "account": {
      "type": "phoneNumber",
      "value": "+821012345678”
    }
}

Example

POST /atw/v1/cards/1656147182764415319
[Headers] Authorization: <JWT_SERIALIZED> x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

Payload

{
  "cdata": "<JWT_SERIALIZED>"
}

[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