Create and Launch a Card Programme

This chapter defines the card programme configuration and payload fields that determine how a card is presented in Samsung Wallet. Complete it before generating production Add to Samsung Wallet links.
Start with the portal workflow, then use the common data model and the specification for your selected card type. Read the barcode, structured-data and image pages only when your design uses those fields.

Design completion criteria

Before moving to security and implementation, confirm that:

  • the card type and subtype match the approved use case;
  • the card programme has a Card ID;
  • every required common and card-type-specific attribute has a value source;
  • all image assets meet the documented dimensions and formats;
  • the barcode or QR-code format, if used, can be produced by the partner system; and
  • the card has been validated in Testing Mode.

Template management

A Wallet Card Template defines the UI layout, card attributes, and behaviour policies (e.g., privacy mode, capture prevention) applied to Wallet Cards.
Partners can create and manage Wallet Card Templates using one of the following methods:

  • Portal-based management: Create and manage templates manually through the partner portal.
  • API-based management: Create and manage templates programmatically through APIs for automation and system integration.
    This section provides an overview of template management via the Portal and via APIs.

Overview

The following figure illustrates the overall flow of Wallet Card Template management and its usage.

Description

  1. The partner creates and manages a Wallet Card Template in advance (via Portal or API).
  2. When issuing or registering a Wallet Card, the system references the template and applies the defined layout and policies.
  3. Template updates should be managed carefully, considering operational policies such as versioning and the scope of impact (e.g., new cards vs. existing cards).

Manage Wallet Card Template via Portal

Partners can create and manage Wallet Card Templates using the Portal. Portal-based management is useful for initial setup, manual operations, and administrative control.
Main capabilities

  • Create a template
  • View and search templates
  • Update a template
  • Manage template operational settings (e.g., status, test/production-related options)
    Basic procedure (example)
  1. Sign in to the Portal and navigate to the Wallet Card Template management menu.
  2. Select Create Template.
  3. Enter required fields (e.g., Title, Card Type/SubType).
  4. Configure optional/conditional fields as needed (e.g., no-network support, share button exposure, privacy mode, capture prevention).
  5. Save and verify the created template.
  6. Update the template or operational settings if required.
    Note: Portal UI labels and menu names may vary depending on the Portal version.

Step 1 - Create Wallet Cards Templates

Begin by drafting the cards that will be added to Samsung Wallet. These cards can include loyalty cards, tickets, boarding passes, and more. Draft Status - Initially, these cards will be in Draft status until they are fully configured and ready for testing.
Private key helps to enable encryption and is the most important component of certificates.
Manage Cards
Partners can manage all registered wallet cards. This includes edit, update, and monitor the status of the wallet cards.

General Information
The General Information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet.

Folder

 Contents
Testing mode

 All data generated in Testing mode is periodically deleted.
Be sure to turn off the "Testing mode" setting after the test is over.
Wallet Card name

 Representative title of the wallet card
Wallet Card ID

 Unique wallet card domain name
Partner app package name

 Partner application package name
Wallet Card Template

 Pre-defined partner wallet card template
Partner Get card data

 URL for the partner API call to receive card data.
If the partner uses this API, enter the URL. Otherwise leave it blank.
Partner Send card state

 URL for the partner API call to send a card state notification.
If the partner uses this API, enter the URL. Otherwise leave it blank.
Samsung Server IPs

 Samsung Wallet Server IPs which need to be allowed by the partner’s firewall, separately described for inbound and outbound
Wearable Wallet assistance

 Whether to support the Wearable Wallet service
Support ‘No Network’ status

 Whether to support wallet card opening during the ‘No Network’ status
Description

 Description of the wallet card

Select Template
The Samsung Wallet Portal offers various wallet card templates optimised for different use cases, including boarding passes, tickets, coupons, and digital IDs.
To streamline your integration, you can easily select the appropriate template from the Select Wallet Card Template pop-up window.
Steps to select Wallet Card Template

  1. Navigate to the Select Wallet Card Template option within the portal.
  2. In the Wallet Card Type drop-down menu, select the category that best suits your use case (e.g., Boarding Pass, Ticket, Coupon, or Digital ID).
  3. Once the card type is selected, a list of templates will appear in the Wallet Card Sub Type section.
  4. Choose one of the available templates from the list that corresponds to your selected card type.
  5. After selecting the template, you can proceed with configuring the card’s details, including the branding, content, and data fields specific to the selected template.

    Samsung Wallet supports various wallet card types designed to cater to different use cases. Each card type is optimised for specific functions, making it easier for partners to provide a seamless experience to users.
View Wallet Cards Partners can easily manage all their registered wallet cards through the Samsung Wallet Portal. This includes the ability to view, edit, and delete wallet cards as needed.

Step 2 - Launch Wallet Cards (Verifying status)

Once a wallet card is ready for launch, it must go through the Verifying status before it can be activated and made available to users. Partners can launch and activate their cards once they have been reviewed and approved, ensuring the card meets all requirements.
Steps to launch wallet cards

  1. To begin the launch process, click Yes to confirm and approve the activation of the wallet card.
  2. To begin the activation process, click the Launch button for the card you wish to activate.
  3. Once a card is launched, the button text changes to Launched. The activation cannot be cancelled.
  4. After the card is launched, its status will change to Verifying. During this stage, the system will conduct a final review to ensure all information is accurate and meets the necessary requirements.
  5. After verification, the card will undergo administrator approval. The admin will review and approve the card for activation.
  6. Once the card is approved by the administrator, its status will change to Active, making it available for users to add to their Samsung Wallet.
    Launch Wallet Cards (Rejected status)
    If the wallet card is rejected after launching, you can modify the card and re-launch.


    Steps to modify the card and re-launch
  7. The administrator registers the reason for rejection when rejecting the launched wallet card.
  8. It is sent to the partner by email from the system, including the reason for rejection.
  9. Partners can apply for launch again by checking the reason for rejection and modifying the wallet card information.

Step 3 – Testing Mode

Partners can use the Testing Mode to test a wallet card internally before it is officially released to users. This feature ensures that all aspects of the card, including its functionality and user experience, are working as expected.

  1. When you create a new wallet card, the Testing Mode option is enabled by default, allowing you to perform internal tests without affecting user access.
  2. All data generated during testing is periodically deleted to ensure that no test data remains in the system once testing is complete.
  3. Even though Testing Mode is enabled, the card is still visible and accessible in the system. Testing does not prevent the card from being exposed to users, so you can verify its functionality without any restrictions.
  4. Once testing is complete and you are satisfied with the card’s performance, be sure to turn off Testing Mode.

Step 4 - Admin Approval (Active Status)

After a wallet card is launched, it must go through an administrator approval process before it becomes active and visible to users.
Steps for Admin approval

  1. Once the Launch button is clicked, the card’s status automatically changes to Verifying.

  2. During this stage, the card is reviewed for accuracy, completeness, and compliance with Samsung Wallet requirements.

    administrator will verify the results through server-side test logs.

  3. An administrator will review the submitted wallet card to ensure it meets all content and technical guidelines. If the card passes the review, it is approved for activation.

  4. Upon administrator approval, the card status updates 'Active'.

  5. Once the card reaches Active status, it becomes visible and accessible to end users, enabling them to add it to their wallets.
    Approval Readiness and Required Evidence
    Before administrator approval is granted, the partner may be required to demonstrate that the proposed card programme has completed the necessary implementation, validation and operational readiness checks.

    Typical approval evidence may include

    • Successful end-to-end integration test results
    • Server-side test logs demonstrating expected registration, callback and update behaviour
    • Evidence that required security controls are implemented
    • Confirmation that the card template, content and user-facing behaviour match the approved use case
    • Verification that mandatory tracking, callback handling, and lifecycle processing are functioning correctly
    • For access-related programmes, evidence of capability validation, security review completion and model-specific readiness

    Important notes

    • The exact approval scope and required evidence may vary depending on the card type, business model, region, and whether access capability is involved.
    • Samsung may request additional validation artifacts, scenario-based test evidence, or security-related documentation for specific use cases.
    • Completion of implementation alone does not guarantee approval.
    • Administrator approval is granted only after Samsung confirms that the service satisfies the applicable technical, operational, and policy requirements.

Next — implement card addition

After the card programme and template are ready, continue to Secure Your Integration and Add Cards to Samsung Wallet. The card addition contract and channel-specific entry-point guidance are maintained there so that this portal procedure does not duplicate them.

Optional — configure a Merchant Push template

Partners can create a Message template for sending pushes on each of their Wallet cards.
Merchant Push template configuration in the Wallet Partners Portal

Type

  • Partners can only choose the Merchant Push type.
    Message Type
  • You can choose a Message Type from marketing or others
    Rejected Comment
  • If the merchant push notification is rejected after request approval, you can modify the Message Template.
  • The administrator registers the reason for rejection when rejecting the merchant push notification
  • It is sent to the partner by email from the system, including the reason for rejection.
  • Partners can request for approval again by checking the reason for rejection and modifying the Message Template.
    Approved Date
  • Displays the date and time when the push message is approved by the administrator.
    Message Template
  • You can create the contents of the push, and it is also possible to put the available variables in '{{}}'
  • After configuring the content, click Harmfulness Verification to verify whether there is a harmful expression in the content.
  • The verified result is displayed as Pass or Fail, and if it is Fail, it shows the filtered harmful expression together.
  • Even if the verified result is Fail, an approval request can be made, but it can be rejected by the administrator.
  • If a different language is added to the default language in General Information, the Message Template must also be entered for each added language.
    Request Approval Button
  • After completing the Message Template, click this button to send an e-mail requesting approval to the administrator.

Manage Wallet Card Template via API

Partners can create and manage Wallet Card Templates programmatically using the Card Template Management. This approach is recommended for automation, bulk operations, and integration with partner back-end systems.

Prerequisites / Access Control

  • API-based template management is available only after successful partner onboarding.
  • Samsung administrative permission/approval is required to use server-side APIs. If your account is not authorised, the API features may be unavailable until approval is granted.

Typical use cases

  • Automatically create/update templates from an internal system to standardize operations
  • Manage templates for multiple services/brands at scale
  • Integrate template lifecycle management into deployment pipelines or operational tools

Related specifications

  • For detailed API definitions (endpoints, headers, request/response formats) and card-type-specific template specifications, refer to Template Management APIs.