Server-Initiated Card Provisioning

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 and managed internally by Samsung Wallet.
Since this value is not disclosed to partners, external partners generally have no legitimate way to obtain a valid dmId, making this option impractical for normal partner integrations.
saId

 O

 Samsung Account identifier.
CI

 O

 Identification value for distinguishing Korean users.

Resolution Logic

  • 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 and 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 Wallet Card is typically added after user interaction, such as selecting the Add to Wallet button or link. This API also supports automatically adding a Wallet Card for special-purpose use cases, with the 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. Card registration is confirmed when the card state is updated to ADDED through 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 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 serialized as a JWS-wrapped JWE token, not a plain JWT. See the Security chapter for details.

Request

Type

 Value

 Description
Method

 POST
URL

 /atw/v1/cards/{cardId}
  • For requests targeting the KR region, prepend KR/ to the path (e.g., /KR/atw/v1/cards/{cardId}).
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token may use the "Bearer" authorisation scheme.
i.e., Bearer <credentials>
* See 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)
Wallet card object.
* See Card object for structure and field definitions.
account
Object

 (Conditional)
User account object.
account.type
String(16)

 (Required)
Type of user identifier, e.g. phoneNumber, email.
* See Account Object and User Resolution
account.value
String(64)

 (Required)
User identifier

Example: Card object

{
  "card": {
    "type": "ticket",
    "subType": "movies",
    "data": [{
        "refId": "ref-20230304-001",
        "createdAt": 1612660039000,
        "updatedAt": 1612660039000,
        "language": "en",
        "attributes": {
          "title": "Samsung Wallet",
          "mainImg": "https://{base-url}/main.png"
          // Add the required attributes for the selected card type and subtype.
        },
        "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": "<CDATA_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

Pushed Updating Wallet Card API

This API allows partners to push an update to a wallet card that has already been added to Samsung Wallet. Samsung Wallet applies the update to the existing wallet card instance(s) identified by each data[].refId under {cardId}. If no wallet card matching a given refId exists, the update for that entry fails.

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

Request

Type

 Value

 Description
Method

 POST
URL

 /atw/v1/cards/{cardId}/updates
  • For requests targeting the KR region, prepend KR/ to the path (e.g., /KR/atw/v1/cards/{cardId}/updates).
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token may use the "Bearer" authorisation scheme.
i.e., Bearer <credentials>
* See 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)
Wallet card object containing the updated data.
* See Card object for structure and field definitions.
* data[].refId identifies the existing wallet card instance(s) to update.

Example

POST /atw/v1/cards/1656147182764415319/updates

[Headers]

Authorization: <JWT_SERIALIZED>

x-smcs-partner-id: partner-id-0001

x-request-id: req-202303140004

Payload

{
  "cdata": "<CDATA_SERIALIZED>"
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A

[Result]

HTTP Status Code

 Description
200 OK

 Success
400 Bad Request

 Requests cannot or will not be processed due to something that is perceived to be a client error, including when no wallet card matching refId exists.
401 Unauthorized

 Authorization token is invalid or expired.
500 Internal Server Error

 The server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable

 Server is not ready to handle the request.