Operational Security Controls

This section consolidates operational requirements and recommended practices that improve replay resistance, traceability, network safety, and troubleshooting.

Replay Prevention and Time Discipline

This subsection defines minimum controls to reduce replay risk and avoid failures due to clock skew.

  • Tokens include utc as epoch milliseconds and use UTC±00:00.

  • Because cdata is issued in a short window, token issuers SHOULD ensure time synchronization (e.g., NTP) and minimize delays between token creation and link invocation.

  • If a request is retried, issuers SHOULD generate a fresh token rather than reusing near-expiry tokens.

Request Identifier (x-request-id)

This subsection defines the request identifier used for traceability and operational correlation.

Many APIs define x-request-id as a randomly generated UUID used for traceability. Partners SHOULD log and propagate this identifier end-to-end for troubleshooting and audit correlation.

Field

 Description
x-request-id
String(64)

 (Recommended)
UUID is preferred (36 chars); 64 allows future formats.

Reference ID (refId / pdata) and Indirection Safety

This subsection defines safety guidance for indirection identifiers used in Data Fetch Link flows.

For Data Fetch Link flows, the link includes only a reference identifier (pdata), which maps to refId. Partners SHOULD generate refId with high entropy, avoid embedding PII or predictable business identifiers, and consider using encryption or hashing with server-side mapping if plaintext exposure is a concern.

Field

 Description
pdata (refId)
String(256)

 (Recommended)
Recommended High-entropy, non-sequential identifier; do not embed PII.

Network Security and Environments

This subsection defines allowlisting guidance, domain/callback considerations, and environment separation practices.

  • Allowlisting: When partners enforce inbound allowlists, they may need to register Samsung server IP addresses; operational inbound/outbound IP information should be referenced from Partner Portal card details.

  • Domain/callback context: Callback-based context (e.g., parameters such as cc2) may be required for subsequent calls depending on the integration flow.

  • Environment separation: Partners SHOULD use separate Card IDs/services per environment (test vs production) to avoid cross-environment contamination.

Allowlisting and Server IP Ranges

If the partner enforces network allowlisting, the following Samsung Wallet server IP addresses shall be allowed as applicable.

Current operational IP ranges

  • Samsung to Partner: 33.200.172.231/32, 14.209.94.70/32

  • Partner to Samsung: 75.2.124.84, 99.84.241.41, 15.197.207.89, 4.44.192.37

Operational guidance

  • The IP list above reflects the currently assigned operational addresses at the time of publication.

  • Partners must treat the Samsung Wallet Partner Portal as the source of truth for the latest inbound and outbound IP information.

  • These IP addresses may be updated for operational, security, or infrastructure reasons.

  • Partners are responsible for monitoring the Partner Portal and updating firewall rules accordingly.

  • Unless otherwise explicitly agreed, the partner must not assume that the IP list is permanently fixed.

Environment note

  • Test and production environments may have different operational settings, policies, or infrastructure configurations.

  • Partners should verify the applicable allowlist information for each environment in the Partner Portal before go-live.

Troubleshooting Quick Checks (Operational)

This subsection provides a minimal checklist for common failures.

  • 401 Unauthorized: Verify Authorization Token signature and time validity; ensure correct API.method and API.path binding.

  • cdata failures: Generate cdata inside click handlers; avoid pre-generation to reduce expiry issues.

  • Network timeouts / 5xx: Confirm allowlist configuration and Partner Portal operational IP references; confirm domain/callback parameters (e.g., cc2) are correctly applied.

Operational Resilience and Infrastructure Expectations

Partners operating Samsung Wallet integrations must maintain a production environment that can safely support card registration, callback handling, content updates, and security-sensitive server communication.

Minimum expectations

  • The partner MUST operate the integration service in a stable and monitored production environment.

  • The partner MUST maintain sufficient logging and traceability for security events, callback processing, API failures, and state-changing requests.

  • The partner MUST be able to recover from temporary failures without causing inconsistent card lifecycle behaviour.

  • The partner SHOULD implement service redundancy, backup and recovery procedures appropriate for the criticality of the deployed card programme.

  • The partner SHOULD avoid single points of failure in systems responsible for card issuance, callback reception, and update processing.

  • The partner MUST ensure that retry behaviour does not create duplicate or conflicting lifecycle operations.

Operational preparedness

  • The partner SHOULD document escalation contacts and incident handling procedures for production issues affecting Samsung Wallet integration.

  • The partner SHOULD maintain a disaster recovery or business continuity plan for infrastructure supporting Samsung Wallet services.

  • If requested during onboarding, review, or incident handling, the partner may be required to explain its operational recovery approach and production support model.