Notification Service

Purpose and scope

The Notification service enables partners to send messages to users who have registered a Wallet Card issued by that partner. Notifications are template-driven and may be used for both service and marketing purposes, subject to template approval and content policy checks. Partners can create templates via the Partner Portal or programmatically, then use approved templates to deliver encrypted, JWT-wrapped notification payloads that target specific card instances. Delivery metrics (impressions, clicks) are recorded and exposed in the Samsung Wallet Partners Portal for campaign evaluation.

Notification Workflow

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.

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.

Geofence Notification

Geofence Notification enables Samsung Wallet to provide a location-triggered notification for a Wallet Card that has already been added by the user. This capability uses the locations field in Wallet Card Data (CData) and evaluates the user's device location against a configured geofence policy. When the configured condition is met, Samsung Wallet may display a notification to the user.

This feature is based on card data registered through Add to Wallet, but the notification behavior itself is performed after card enrollment. For this reason, Geofence Notification is described as a specialized notification scenario rather than as part of the core Add to Wallet flow.

At a high level, the partner provides location information and a geofenceType in the card data. Samsung Wallet uses the provided location data and service configuration to evaluate whether a location-triggered notification should be displayed on the device.

Prerequisites

  • The Wallet Card must already be added to Samsung Wallet.
  • The partner must provide valid locations data in the Wallet Card Data (CData).
  • The partner must provide a geofenceType for each location intended for Geofence Notification.
  • The user must allow location access on the device for location-triggered behavior.
  • Availability of Geofence Notification may depend on service policy or feature enablement.

Partner Input Example

{
  "locations": "[{\
\"lat\":37.12345,\
\"lng\":127.12345,\
\"name\":\"Store 1\",\
\"address\":\"110 Example-ro\",\
\"geofenceType\":\"100\",\
\"message\":\"Welcome to Store 1. Check your available benefits in Samsung Wallet.\"\
}]"
}

The locations field is represented as a stringified JSON array in Wallet Card Data (CData). Each location object may contain basic place information such as latitude, longitude, place name, and address. For Geofence Notification, the partner additionally provides geofenceType as a string value and may provide a notification message.

Geofence Notification Configuration

For Geofence Notification, the partner provides geofenceType as a string value in each applicable location entry. Supported values are "100", "200", "300", "400", and "500". These values indicate the geofence radius in meters, such as 100 m, 200 m, 300 m, 400 m, and 500 m. Samsung Wallet uses the provided value together with service-side configuration to apply the Geofence Notification scenario to the card.

Each value must be provided as a string in the locations entry.

Supported geofenceType values:

  • "100": 100 m radius
  • "200": 200 m radius
  • "300": 300 m radius
  • "400": 400 m radius
  • "500": 500 m radius

Geofence Notification Flow

Step 1: Prepare card data
The partner prepares Wallet Card Data (CData) and includes locations entries for the relevant places. For Geofence Notification, each target location entry includes geofenceType and message.

Step 2: Register the card through Add to Wallet
The partner submits the card through the Add to Wallet flow using the appropriate card template and Wallet Card Data.

Step 3: Resolve geofence policy
Samsung Wallet applies the Geofence Notification scenario associated with each geofenceType and prepares the card for location-triggered behavior on the device.

Step 4: Add the card and grant location access
The user adds the card to Samsung Wallet. To support location-triggered behavior, location access must be enabled on the device.

Step 5: Detect geofence events
The device evaluates the user's location against the configured geofence conditions, such as entry, radius, and active time range.

Step 6: Display notification
When the configured condition is satisfied, Samsung Wallet displays the notification associated with the location entry.

Notification Service APIs

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/{cardId}/notifications/{TemplateId}/send
Header

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See REST API Authorization Token (JWT / JWS) 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 (Send Card Event).
cardId
String (32)

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

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

 ndata
String

 (Required)
Notification object (JSON).
* This field needs to be encrypted.
* Refer to Card Data Token (cdata) 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 <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

/* [Payload] */
{
   "ndata": <JWT_SERIALIZED>
}

/*[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 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.

Create Targeted Notification Job

This API creates a targeted notification job for users who match the specified filter conditions.

[Request]

Type

 Value

 Description
Method

 POST
URL

 /wltex/cards/{cardId}/notifications/{TemplateId}/jobs
Header

 Authorization
String(1024)

 (Required)
Credential token. The token can have prefix "Bearer" as an authorization type.
x-smcs-partner-id
String(32)

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

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

 cardId
String(32)

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

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

 filter
Object

 (Required)
Targeting condition object. The supported filter key is eventId.
data
Object

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

Example

POST /wltex/cards/12584806754/notifications/12353465344/jobs

/* [Headers] */
Authorization: Bearer <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

/* [Payload] */
{
  "filter": {
    "eventId": "event-003"
  },
  "data": {
    "name": "Logan",
    "place": "Samsung Wallet"
  }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 id
String

 Targeted notification job identifier.
status
String

 Targeted notification job status. The initial status is READY.

Example

200 OK
{
  "resultCode": "0",
  "resultMessage": "SUCCESS",
  "id": "targeting-job-id",
  "status": "READY"
}

[Result]

HTTP Status Code

 Description
200 OK

 Success
400 Bad Request

 Requests cannot or will not be processed due to a client error.
401 Unauthorized

 Authorization token is invalid or expired.
404 Not Found

 Targeted notification job does not exist or does not belong to the requested card.
500 Internal Server Error

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

Get Targeted Notification Job

This API retrieves the status and timestamps of a targeted notification job.

[Request]

Type

 Value

 Description
Method

 GET
URL

 /wltex/cards/{cardId}/notifications/{TemplateId}/jobs/{jobId}
Header

 Authorization
String(1024)

 (Required)
Credential token. The token can have prefix "Bearer" as an authorization type.
x-smcs-partner-id
String(32)

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

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

 cardId
String(32)

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

 (Required)
Approved notification template identifier from Samsung Wallet Partners Portal.
jobId
String(36)

 (Required)
Targeted notification job identifier returned when creating the job.

Example

GET /wltex/cards/12584806754/notifications/12353465344/jobs/targeting-job-id

/*[Headers]*/
Authorization: Bearer <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140004

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 job
Object

 Targeted notification job object.
job.id
String

 Targeted notification job identifier.
job.status
String

 Targeted notification job status.
job.createdAt
String

 Date and time when the targeted notification job was created.
job.endedAt
String

 Date and time when the targeted notification job ended. The value can be null while processing.

Example

200 OK
{
  "resultCode": "0",
  "resultMessage": "SUCCESS",
  "job": {
    "id": "targeting-job-id",
    "status": "READY",
    "createdAt": "2026-03-16T00:00:00Z",
    "endedAt": null
  }
}

[Result]

HTTP Status Code

 Description
200 OK

 Success
400 Bad Request

 Requests cannot or will not be processed due to a client error.
401 Unauthorized

 Authorization token is invalid or expired.
404 Not Found

 Targeted notification job does not exist or does not belong to the requested card.
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 Samsung 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 Samsung Wallet Partners Portal.

[Request]

Type

 Value

 Description
Method

 POST
URL

 /partner/v1/card/template/{cardId}/notification
Header

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
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)
The wallet card identifier granted through the Samsung Wallet Partners 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 Card Data Token (cdata) 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: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

/* [Payload] */
{
  "ntemplate" : "<JWT_SERIALIZED>"
}

[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/{cardId}/notification
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
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)
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: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK

Example

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/{cardId}/stats/notifications
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
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)
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: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK

Example

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