Notification for Partners

Deliver personalized push messages to Samsung Wallet users, linked to their Wallet Cards. Samsung Wallet enables authorized partners to send targeted push notifications using pre-approved message templates. This feature supports marketing, transactional, and engagement-driven use cases.

Only partners with administrative approval can access and use the Notifications feature. The Notifications tab is hidden for unauthorized accounts.

Notification Workflow Overview

Step 1: Create Notification Template

Partners can create push message templates through the Partner Portal or Notification API. Templates define the structure and content of the notification.

  • Type: Only Merchant Push is supported.
  • Message Category: Choose from Marketing or Other.
  • Variables: Use dynamic placeholders with {{ }} syntax
    e.g., Hello {{name}}, your pass for {{event}} is ready.

If your Wallet Card supports multiple languages, a message template must be provided for each language variant.

After drafting the message:

  • Run Harmfulness Check to detect prohibited content.
  • Results: Pass or Fail
  • Even if failed, templates can still be submitted but may be rejected in the next step.

Step 2: Request Template Approval

Once the template is complete:

  • Click the Request Approval button in the portal.
  • An administrator will review the content.

If Rejected:

  • The reason is provided via system email.
  • Partners can revise and resubmit the template for approval.

If Approved:

  • The Approved Date will appear in the portal.
  • The template becomes eligible for use in the notification API.

Step 3: Push Notification with Template

Once a template is approved, partners can push notifications to users linked to their Wallet Cards using a secure POST API request.

Required Parameters:

  • Template ID – Issued after template approval
  • Reference ID – A unique identifier tied to the user’s Wallet Card (created during the Add to Wallet process)

Only pre-approved templates can be used in push requests.

Step 4: Monitor Impressions and Clicks

After the push is delivered, partners can track:

  • Impressions – Number of users who viewed the notification
  • Clicks – Number of interactions with the push

These metrics can be accessed through the Partner Portal dashboard, enabling performance evaluation of each campaign.

Send Notification

This API sends notifications to end users who have added the wallet card.

[Request]

Type

 Value

 Description
Method

 POST
URL

 /{cc2}/wltex/cards/{Card Id}/notifications/{Template Id}/send
Header

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
e.g., Bearer <credentials>.
* Refer to Authorization Token for more details.
x-smcs-partner-id
String(32)

 (Required)
Partner ID
x-request-id
String(32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path parameters

 cc2
String(2)

 (Required)
Country code (cc2) from Send Card State.
Card Id
String(32)

 (Required)
Wallet card identifier granted from Partners Portal.
Template Id
String(32)

 (Required)
Approved notification template identifier from Partners Portal.
Payload

 ndata
String

 (Required)
Notification object (JSON).
* This field needs to be encrypted.
* Refer to Security for more details.
* The value of "cty" must be set to "NOTIFICATION".
Notification Object

 refIds
Array of String(100)

 (Required)
Unique content identifier defined by the content provider.
data
Object

 (Required)
Name-value pair for use in notification template.

[Example]

POST /wltex/cards/12584806754/notifications/12353465344/send

/*[Headers]*/
Authorization: Bearer eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

/*[Payload]*/
{
   “ndata”: “eyJjdHkiOiJBVVRIIiwidmVyI…”
}

/*[Notification Object]*/
{
    "refIds": [
        "ref-20230304-0003",
        "ref-20230304-0004"
],
    "data": {
        "name": "Logan",
        "place": "Samsung Wallet"
    }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A

[Result]

HTTP Status Code

 Description
200 OK

 Success
400 Bad Request Requests

 Requests cannot or will not be processed the request due to something that is perceived to be a client error.
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.

Adding Notification Templates

In general, card notification creation is possible through the ‘Wallet Partners Portal'. However, a server API is provided for cases where it is necessary to create a large number of card notifications. Card notifications created through API can also be checked and managed in the same way on the ‘Wallet Partners Portal'

[Request]

Type

 Value

 Description
Method

 POST
URL

 /partner/v1/card/template/{Card Id}/notification
Header

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See JSON Web Token.
x-smcs-partner-id
String (32)

 (Required)
Partner ID.
x-request-id
String (32)

 (Required)
Request identifier.
Random generated UUID string.
Path Parameters

 Card Id
String(32)

 (Required)
The wallet card identifier granted through the Partner Portal.
* The identifier is needed when updating a specific card template.
Body parameters

 ntemplate
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 Security for more details.
Payload Object

 type
String(20)

 (Required)
Notification Type
(M: Merchant Push, G:Geo Push)
messageType
String(20)

 (Required)
Purpose of Notification
(S: Service, M: Marketing)
messageDetails[]
Array Of Object

 (Required)
Container of notification message.
messageDetails[]. languageCode
String(20)

 (Required)
Default notification language code,
e.g. en, ko.
messageDetails[].message
String(500)

(Required)
Notification message.
forceSaveYn
String(10)

 (Optional)
Sets whether to save when harmfulness is detected.
This must be set to either 'Y' or 'N'.
* Default: 'N'.

[Example: Notification Template object ]

{
"type": "M",
"messageType": "S",
"messageDetails": [
{
"languageCode": "en",
"message": "It’s notification message."
}]
}

[Example]

POST /partner/v1/card/template/3hdpejr6qi380/notification
[Headers] 
Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR
  
/** Payload **/]
{
  "ntemplate" : "eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0Z…"
}

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK
Payload

 HarmfulResult

 Harmfulness check result.
Responded as “Pass” or “Fail”.
HarmfulLabels

 Reason for harmfulness detection.
Responded only when HarmfulResult is “Fail”.
save

 Indicates whether the forceSaveYn option has been set.
When set to “Y”, it is responded as “force”.

[200 OK]

{
"resultCode": "0",
"resultMessage": "success",
"HarmfulResult": "Pass"
}

[200 OK]

{
"resultCode": "0",
"resultMessage": "success",
"HarmfulResult": "Fail",
"HarmfulLabels": "Hate,Violence"
}

[200 OK]

{
"resultCode": "0",
"resultMessage": "success",
"save": "force",
"HarmfulResult": "Fail",
"HarmfulLabels": "Violence"
}

[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

Get Notification Templates

[Request]

Type

 Value

 Description
Method

 GET
URL

 /partner/v1/card/template/{Card Id}/notification
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See JSON Web Token.
x-smcs-partner-id
String(32)

 (Required)
Partner ID.
x-request-id
String(32)

 (Required)
Request identifier.
Random generated UUID string.
Path Parameters

 Card Id
String(32)

 (Required)
The wallet card identifier granted through the Partner Portal.
* The identifier is needed when updating a specific card template.

[Example]

GET /partner/v1/card/template/3hdpejr6qi380/notification
[Headers]
Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK

[200 OK]

{
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "templates": [
        {
            "id": "4091356465432138240",
            "type": "M",
            "messageType": "S",
            "approval": "APPROVED",
            "messageDetails": [
                {
                    "languageCode": "en",
                    "message": "Hi! {{name}}, This is Merchant Push."
                }
            ]
        },
        {
            "id": "4092425423713135680",
            "type": "M",
            "messageType": "S",
            "approval": "NONE",
            "messageDetails": [
                {
                    "languageCode": "en",
                    "message": " Hi! {{name}}, This is Merchant Push"
                }
            ]
        },
]
}

[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

Get Notification Statistics

[Request]

Type

 Value

 Description
Method

 GET
URL

 /partner/v1/card/template/{Card Id}/stats/notifications
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See JSON Web Token.
x-smcs-partner-id
String(32)

 (Required)
Partner ID.
x-request-id
String(32)

 (Required)
Request identifier.
Random generated UUID string.
Path Parameters

 Card Id
String(32)

 (Required)
The wallet card identifier granted through the Partner Portal.
* The identifier is needed when updating a specific card template.
Query Parameters

 notificationId
String(32)

 (Optional)
If specified, statistics are returned only for the specified notification.
If not specified, aggregated statistics for all notifications of the card are returned.
start
Timetamp(ms)

 (Required)
Start Date(Unix timestamp in milliseconds)
end
Timestamp(ms)

 (Required)
End Date(Unix timestamp in milliseconds)
metric
String(32)

 (Required)
Metric(impression

 click)

[Example]

GET /partner/v1/card/template/3hdpejr6qi380/stats/notifications?notificationId=123456789&start=1764514800000&end=1765465200000&metric=impression
[Headers]
Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK

[200 OK]

{
  "resultCode": "0",
  "resultMessage": "SUCCESS",
  "statistics": [
    [
      1764820800000,
      1
    ],
    [
      1764896400000,
      2
    ],
    [
      1764900000000,
      1
    ],
    [
      1764903600000,
      0
    ],
    [
      1764907200000,
      1
    ],
    [
      1765134000000,
      0
    ]
  ]
}

[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