Adding Cards to a User Wallet Using the Adding Wallet Cards API
M. A. Hasan Molla
Engineer, Samsung Developer Program
Samsung Wallet provides an e-wallet service to its customers through wallet cards. Adding a card to the user device is normally triggered by user interaction, cards are added to their device when the Add to Wallet button or link is pressed. The Adding Wallet Cards API provides the functionality to add cards to user devices directly without user interaction. A partner can provide wallet cards to the user’s wallet directly using the user’s email or mobile number.
This article demonstrates a complete implementation of the Adding Wallet Cards API. In the example scenario, we add a Coupon type card to a user device from a partner’s server using this API without any user interaction.
System requirements
The Adding Wallet Cards API has the following prerequisites:
- New Samsung Wallet users must first complete the onboarding procedure and obtain the required security certificates.
- Create a new Coupon card template through the Wallet Partners Portal and launch the card. As a partner you can also create a card template through the partner server. For more details, refer to the Create Samsung Wallet Card Templates Using the Server API.
- Using the Adding Wallet Cards API requires explicit permission from Samsung. Contact Samsung Developer Support for authorization.
API fundamentals
This RESTful interface enables partners to deliver wallet cards directly to user accounts from their servers.
Endpoint: The service URL where card addition requests are processed.
https://tsapi-card.walletsvc.samsung.com/atw/v1/cards/{cardId}
Headers: Only verified partners can utilize this API. Header information establishes secure communication between the partner and Samsung servers.
Authorization: Bearer token authentication. Refer to JSON Web Token documentation for specifications.x-smcs-partner-id: Your unique partner identifier required for API access.x-request-id: A unique UUID string that identifies each request.
Body: Must include a cdata parameter containing a JWT token with card details and user account information.
Detailed API specifications are available in the official documentation.
API implementation process
The Adding Wallet Cards API enables partners to deliver cards directly to the user's account or wallet. Follow this step-by-step approach to implement the API. For a better understanding of the overall process, download the sample source code.
Step 1: Cryptographic key management
Extract necessary keys from security certificates for JWT token generation in subsequent steps.
Public key retrieval
The following function extracts public keys from partner.crt and samsung.crt certificate files received during the onboarding process.
def getPublicKey(crt_path):
"""
Extract public key from a .crt file.
"""
try:
with open(crt_path, "rb") as f:
crt_data = f.read()
certificate = x509.load_pem_x509_certificate(crt_data, default_backend())
public_key = certificate.public_key()
public_key_pem = public_key.public_bytes(
encoding=serialization.Encoding.PEM,
format=serialization.PublicFormat.SubjectPublicKeyInfo
)
return public_key_pem
except Exception as error:
print(f"Error reading public key from {crt_path}: {error}")
return None
Private key retrieval
This function retrieves the private key from the .pem file generated during the onboarding process.
def getPrivateKey(pem_path):
'''
Extract private key from a .pem file.
'''
try:
with open(pem_path, "rb") as data:
private_key = serialization.load_pem_private_key(
data.read(),
password=None,
backend=default_backend()
)
return private_key
except Exception as error:
print(f"Error reading private key from {pem_path}: {error}")
return None
Step 2: Authentication token creation
Samsung validates each API request through an authorization token in JWT format. To generate a valid authentication token:
- Construct an
authHeaderwithAUTHas the payload content type. Include the certificate ID from My account > Encryption Management in the Wallet Partners Portal. - Build the payload using the
authHeaderstructure. - Generate the final authorization token.
The following code snippet implements the steps above.
def generateAuthToken(partnerId, certificateId, utcTimestamp, privateKey, cardId):
auth_header = {
"cty": "AUTH",
"ver": 3,
"certificateId": certificateId,
"partnerId": partnerId,
"utc": utcTimestamp,
"alg": "RS256"
}
auth_payload = {
"API": {
"method": "POST",
"path": f"/atw/v1/cards/{cardId}"
},
}
auth_token = jwt.encode(
payload=auth_payload,
key=privateKey,
algorithm='RS256',
headers=auth_header
)
return auth_token
Step 3: Card data token generation (cdata)
The request payload requires a cdata parameter containing a JWT token with card information and user details. Follow these steps to construct the cdata token.
Card information structure
Build a card data object containing all necessary information about the card to be delivered and the target user account.
cDataPayload = {
"card": {
"type": "coupon",
"subType": "others",
"data": [{
"refId": "e389dc8a-4616-494c-a8b3-80380f449fc2",
"createdAt": 1727913600000,
"updatedAt": 1727913600000,
"language": "ko",
"attributes": {
"title": "Strawberry Icecream-1",
"orderId": "order-001",
"groupingId": "grouping-001",
"mainImg": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/IHGhULmHRiqfhI73YdQZcA/LDZf4FWLQ9i5iqoym1R2yw.png",
"brandName": "Cioud Icecream",
"expiry": 1762225720029,
"issueDate": 1727913600000,
"redeemDate": 1727913600489,
"noticeDesc": "<div>▶Precautions<br>-This product is an example image and may be different from the actual product. <br>-Only available within the expiration date.<br><br>",
"editableYn": "N",
"deletableYn": "Y",
"displayRedeemButtonYn": "N",
"addToWalletCouponYn": "Y",
"notificationYn": "Y",
"appLinkLogo": "https://play-lh.googleusercontent.com/O5iWMHHBRmiGA_4XDsXMiZThLd-wwu2ln6FBz6zNPdlmKif0i98sfHtWZkYzjan-Tw=w240-h480-rw",
"appLinkName": "Cioud Icecream",
"appLinkData": "https://www.samsung.com/us",
"barcode.value": "1111222233334444",
"barcode.serialType": "BARCODE",
"barcode.ptFormat": "BARCODESERIAL",
"barcode.ptSubFormat": "CODE128"
},
}]
},
"account": {
"type": "email",
"value": "example@samsung.com"
}
}
Cdata JWT token construction
Generate the JWT token using the following implementation. Additional information about the JWT format is available in the Card Data Token section of the Security documentation.
def generateCDataToken(partnerId, samsungPublicKey, partnerPrivateKey, certificateId, utcTimestamp, data):
jwe_header = {
"alg": "RSA1_5",
"enc": "A128GCM"
}
jwe_token = jwe.encrypt(
data,
samsungPublicKey,
encryption=jwe_header["enc"],
algorithm=jwe_header["alg"]
)
print(f"jwe_token: \n{jwe_token}\n")
jws_header = {
"alg": "RS256",
"cty": "CARD",
"ver": 3,
"certificateId": certificateId,
"partnerId": partnerId,
"utc": utcTimestamp,
}
jws_token = jws.sign(
jwe_token,
key=partnerPrivateKey,
algorithm='RS256',
headers=jws_header
)
print(f"jws_token: \n{jws_token}\n")
return jws_token
Step 4: Build HTTP request and execute
With all required components prepared, construct the card addition HTTP request using the following code structure:
# --- Prepare JSON body (Python dictionary) ---
c_data_json_body = {
"cdata": cDataToken
}
# --- Build HTTP Request ---
headers = {
"Authorization": "Bearer " + authToken,
"x-smcs-partner-id": partnerId,
"x-request-id": requestId,
"x-request-cc2": "KR",
"Content-Type": "application/json"
}
# --- Execute HTTP Request ---
try:
response = requests.post(endpoint, json=c_data_json_body, headers=headers)
response.raise_for_status()
print("Wallet Card Added successfully: " + json.dumps(response.json()))
except requests.exceptions.RequestException as e:
print("Failed to add Wallet Card:")
print(f"Error: {e}")
if response:
print("Response body:", response.text)
Running the application
Once the four steps described above are implemented, open the sample project and do the following:
- Update the partner id, certificate id, and card id values in
src/main.pywith your actual credentials. - Replace the
partner.crt,samsung.crtandprivate_key.pemfiles with your credential files in the/certdirectory. - Install all dependencies listed in the
requirements.txtfile using commandpip install -r requirements.txt. - Run the main script using the command
python src/main.pyin the terminal.
After successful execution of the requests, you will get a Success message. Get the full response code in the Response section of the documentation. A push notification is sent to the user’s device to confirm the successful card registration. Once this is done, open your Samsung wallet and navigate to the coupon card list and you will find the card there.
Conclusion
Now that you have familiarized yourself with the process of adding cards to the user device using the Adding Wallet Cards API, you can implement this logic to your server and use it to improve your card management.
Additional resources
For more information on this topic, consult the following resources.
