Create Push Notification Templates Using the Samsung Wallet Server API
M. A. Hasan Molla
Engineer, Samsung Developer Program
Samsung Wallet provides powerful tools for partners to engage with their users and improve the user experience. Push notification is one of these features, allowing partners to send customized notifications to their users. But before they can do that, partners need to create a notification template and receive approval for it from Samsung.
Partners can create individual notification templates from the Wallet Partners Portal. As a partner, if you need to create a large number of card notifications, the Adding Notification Templates server API comes in handy.
In the example scenario in this blog, we create a notification template from a partner's server using the Adding Notification Template API.
System requirements
The Adding Notification Template API has the following prerequisites:
-
Complete the onboarding procedure to obtain the required security certificates if you are new to Samsung Wallet, and create your wallet card.
-
Get permission from Samsung to use the Adding Notification Template API as explicit permission is needed. Reach out to Samsung Developer Support for further assistance.
API fundamentals
To create a notification template, you need to handle an HTTP POST request which contains the endpoint, headers, and a body. For a successful execution of the API, you need to follow the following specification.
Endpoint: Use the following URL as endpoint.
URL
https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template/{Card Id}/notification
Headers: To ensure secure communication between the Samsung server and the partner server, implement the following headers.
Authorization:Bearer token for authentication. For details, follow REST API Authorization Token.x-smcs-partner-id:Use the Samsung Wallet partner ID.x-request-id:A unique UUID string that identifies each request.
Body: Contains detailed template data in the JWT token format. See the Adding Notification Templates for a detailed API specification.
API implementation
The steps below show how to implement the Adding Notification Template API. For a better understanding of the implementation process, download the sample source code.
Certificate management
The KeyManager class is a static utility class that provides methods for loading cryptographic keys from files. This separation of concerns ensures that certificate handling logic is isolated and reusable.
Loading public keys from certificate files
First, you need to load RSA public certificates from X.509 certificate files. The GetPublicKeyRSA() method loads RSA public keys from the partner.crt and samsung.crt files you received during the onboarding process. If the certificate doesn't contain an RSA key, this method raises an exception.
public static RSA GetPublicKeyRSA(string certPath)
{
try
{
var cert = new X509Certificate2(certPath);
return cert.GetRSAPublicKey() ?? throw new InvalidOperationException("Certificate does not contain RSA public key");
}
catch (Exception ex)
{
throw new InvalidOperationException($"Failed to load certificate: {ex.Message}", ex);
}
}
Loading private keys from a PEM file
The GetPrivateKeyRSA() method loads an RSA private key from a PEM file. This is used to generate JWT tokens.
public static RSA GetPrivateKeyRSA(string pemPath)
{
try
{
string keyData = File.ReadAllText(pemPath);
// Remove PEM headers and whitespace
keyData = keyData.Replace("-----BEGIN PRIVATE KEY-----", "")
.Replace("-----END PRIVATE KEY-----", "")
.Replace("-----BEGIN RSA PRIVATE KEY-----", "")
.Replace("-----END RSA PRIVATE KEY-----", "")
.Replace("\n", "")
.Replace("\r", "")
.Trim();
byte[] keyBytes = Convert.FromBase64String(keyData);
var rsa = RSA.Create();
rsa.ImportPkcs8PrivateKey(keyBytes, out _);
return rsa;
}
catch (Exception ex)
{
Console.WriteLine($"Failed to load private key from {pemPath}: {ex.Message}");
return null;
}
}
Token generation
The TokenGenerator class is the heart of the implementation, responsible for creating secure tokens using cryptographic techniques.
Constructor and properties
The class stores all necessary cryptographic keys and identifiers.
private string _partnerId = "";
private string _certificateId = "";
private readonly RSA _samsungPublicKey;
private readonly RSA _partnerPublicKey;
private readonly RSA _partnerPrivateKey;
public TokenGenerator(string partnerId, string certificateId, RSA samsungPublicKey, RSA partnerPublicKey, RSA partnerPrivateKey)
{
_partnerId = partnerId;
_certificateId = certificateId;
_samsungPublicKey = samsungPublicKey;
_partnerPublicKey = partnerPublicKey;
_partnerPrivateKey = partnerPrivateKey;
}
Generating an authentication token
An authentication token proves that your request to Samsung's server is legitimate. It contains the following:
- The API method and path being accessed.
var authPayload = new Dictionary<string, object>
{
["API"] = new Dictionary<string, string>
{
["method"] = "POST",
["path"] = $"/partner/v1/card/template/{cardId}/notification"
}
};
-
Timestamp and other metadata like certificate id. Retrieve this metadata from My account > Encryption Management in the Wallet Partners Portal.
-
A digital signature that verifies the sender's identity. The token is used in the Authorization header of the HTTP request.
public string GenerateAuthToken(Dictionary<string, object> authPayload, string contentType_auth)
{
string dataStr = JsonSerializer.Serialize(authPayload);
string authToken = SignJws(dataStr, contentType_auth);
return authToken;
}
Generating a notification template token
Next, generate the JWT token for notification template data (ntemplate). It is recommended to generate this token after a user action. For details about the JWT format, follow Card Data Token (cdata).
Preparing a notification template
Define the notification template according to the following code snippet. Define your message details and message type here. Get details about the template fields from the “[Request]” section of the Adding Notification Templates documentation.
var notificationTemplate = new
{
type = "M",
messageType = "M",
messageDetails = new[]
{
new
{
languageCode = "en",
message = "Sample merchant push notification message."
}
},
forceSaveYn = "N"
};
forceSaveYn = “Y”, if you want to save the template even if the message is detected as harmful. If your message is detected as harmful, your template can be rejected by Samsung. The default value of the forceSaveYn property is “N”.Implementing encryption (JWE)
The notification template data or payload is encrypted using the Samsung public key and this encrypted payload is used for signing.
public string GenerateCdata(string payloadData, string notification)
{
string jweTokenString = JWT.Encode(payloadData, _samsungPublicKey, JweAlgorithm.RSA1_5, JweEncryption.A128GCM);
string jwtTokenString = SignJws(jweTokenString, notification);
return jwtTokenString;
}
Implementing JWS signing
The encrypted JWE token is then signed with the partner's private key. This signature proves the token originated from a legitimate partner. Samsung can verify this signature using the partner's public key.
AUTH as the content type when signing an auth token and use NOTIFICATION as the content type when signing the notification template data.private string SignJws(string payload, string contentType)
{
try
{
// Create header
var header = new Dictionary<string, object>
{
["alg"] = "RS256",
["cty"] = contentType,
["partnerId"] = _partnerId,
["ver"] = 3,
["certificateId"] = _certificateId,
["utc"] = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
};
return JWT.Encode(payload, _partnerPrivateKey, JwsAlgorithm.RS256, header);
}
catch (Exception ex)
{
throw new InvalidOperationException($"JWS signing failed: {ex.Message}", ex);
}
}
Building and executing the POST request
The next stage of the process is to construct the HTTP POST request to generate a new notification.
client.DefaultRequestHeaders.Clear();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {authToken}");
client.DefaultRequestHeaders.Add("x-smcs-partner-id", partnerId);
client.DefaultRequestHeaders.Add("x-request-id", requestId);
try
{
HttpResponseMessage response = await client.PostAsync(endpoint, content);
response.EnsureSuccessStatusCode();
string responseContent = await response.Content.ReadAsStringAsync();
Console.WriteLine("Successfully generated notification template: " + responseContent);
}
catch (HttpRequestException e)
{
Console.WriteLine("Failed to generate notification template: " + e.Message);
}
catch (Exception e)
{
Console.WriteLine("Unexpected error during HTTP request: " + e.Message);
}
Running the sample application
Once you are done with the above steps, open the sample project and do the following:
- Update the
partnerId,cardId, andcertificateIdvalues in the src/Program.cs file with your actual values. - Place your
partner.crt,samsung.crtandprivate_key.pemfiles in the /cert directory. - Navigate to the src directory, then build and run the project. Find the details for responses and errors from the [Response] section of the documentation.
# Build the project
dotnet build
# Run the application
dotnet run
Conclusion
Now that you know how to create a new notification template using the Adding Notification Template API, you can implement it with your server if you need to generate a larger number of notification templates at once.
Additional resources
For more information on this topic, consult the following resources:
