5.3 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.

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