Implement a Save to Pay integration

The Save to Pay SDK (s2p.min.js) is the piece of Samsung-provided code the partner embeds on their frontend. It sits between the partner's page and Samsung's Wallet/Save to Pay backend: the partner's code makes a single call into it, and the SDK internally handles device detection, rendering the QR modal or hidden iframe, listening for status updates, and (on mobile) triggering the deep-link redirect into the Samsung Wallet app. None of that device-branching logic needs to live in the partner's own code.

The welcomeUrl this SDK consumes comes from the partner's backend calling POST /registrations (see API Reference) — the SDK never talks to Samsung's registration endpoints directly.

Include the SDK

Load the script from Samsung’s CDN, and use the matching environment.

Staging

<script src="https://d1ea2ye0qee75q.cloudfront.net/s2p/libs/js/0.0.4/s2p.min.js"></script>

Production

<script src="https://spay.samsung.com/s2p/libs/js/0.0.4/s2p.min.js"></script>

This registers a global window.spay.saveToPayUI object with the three functions below.

showWelcomeModalPromise relies on native ES6 Promises. For IE11 and older Android WebViews, load a Promise polyfill (e.g. core-js) before the SDK script:

<script src="https://cdnjs.cloudflare.com/ajax/libs/core-js/2.4.1/core.js"></script>
<script src="https://spay.samsung.com/s2p/libs/js/0.0.4/s2p.min.js"></script>

Interface Reference

Functions

Function

Returns

Description

showWelcomeModal(request)

void

Shows the welcome UI. When it reaches a final state, the whole page navigates away to a redirect URL configured during onboarding.

showWelcomeModalPromise(request)

Promise<S2PResponse>

Shows the welcome UI. The page stays put — the returned Promise resolves once the welcome UI closes, with the result available in-line. On Android the Promise can resolve earlier, when the provisioning session concludes (see Promise Resolution Behavior). Recommended for most integrations.

closeWelcomeModal()

void

Programmatically dismisses the modal — use if the partner's own page has, e.g., its own "Cancel" control.

Request shape (S2PRequest)

Field

Type

Validation

Description

welcomeUrl

String

Required

The welcomeUrl returned by POST /registrations or GET /registrations/{regId}. The full POST /registrations response object may also be passed; the SDK reads only this field.

Response shape (S2PResponse)

Field

Type

Validation

Description

status

Enum

Required

Outcome of the welcome flow — see table below

isIframeClosed

Boolean

Required

true if resolution was triggered by the modal/iframe being closed (user or partner page); false if resolution was triggered by a final status arriving on its own — this can only happen on mobile Android

details

Details

Optional

Only present when status = FAILURE. Shape: { errorCode: ErrorCode, message?: string }

Status values

Value

Description

SUCCESS

Card was successfully added to Samsung Wallet

FAILURE

Something went wrong – check details.errorCode for the reason

DEVICE_NOT_SUPPORTED

The end user's device/OS/browser can't run the welcome flow

DEFAULT_PENDING

Modal was closed before a final outcome was reached — treat as inconclusive, not a failure

ErrorCode values (only present when status = FAILURE)

Value

Description

INVALID_INPUT

welcomeUrl was missing or malformed

PROVISION_FAILURE

Card provisioning failed on Samsung's/issuer's side

NETWORK_ERROR

A network call failed during the flow

UNKNOWN_ERROR

Unclassified failure

CARD_ALREADY_PRESENT

The card is already in the user's wallet

CANCELED

The user cancelled the flow

Usage Examples

Promise-based (recommended)

<script src="https://spay.samsung.com/s2p/libs/js/0.0.4/s2p.min.js"></script>
<script>
  var request = {
    welcomeUrl: "https://s2p.mpay.samsung.com/v1/welcome/<token-from-registration-response>"
  };

  function onWelcomeSuccess(response) {
    console.log(response.status); // "SUCCESS" | "FAILURE" | "DEVICE_NOT_SUPPORTED" | "DEFAULT_PENDING"
    if (response.status === "FAILURE") {
      console.log(response.details.errorCode, response.details.message);
    }
  }

  function onWelcomeError(error) {
    console.error(error);
  }

  window.spay.saveToPayUI
    .showWelcomeModalPromise(request)
    .then(onWelcomeSuccess, onWelcomeError);
</script>

.then(onSuccess, onError) and .then(onSuccess).catch(onError) both handle a rejected Promise the same way, but .catch also catches errors thrown inside onSuccess.

Use whichever fits the partner's code style; .catch is safer when the success handler does work that may throw:

window.spay.saveToPayUI
  .showWelcomeModalPromise(request)
  .then(onWelcomeSuccess)
  .catch(onWelcomeError);

Passing the complete POST /registrations response object as request is also supported. The SDK extracts only the welcomeUrl field.

Redirect-based

<script src="https://spay.samsung.com/s2p/libs/js/0.0.4/s2p.min.js"></script>
<script>
  var request = {
    welcomeUrl: "https://s2p.mpay.samsung.com/v1/welcome/<token-from-registration-response>"
  };

  window.spay.saveToPayUI.showWelcomeModal(request);
  // Page will navigate to the partner's pre-registered redirect URL once a final state is reached.
</script>

Closing the modal programmatically

// e.g. wired to the partner's own "Cancel" button elsewhere on the page
document.getElementById("cancel-btn").addEventListener("click", function () {
  window.spay.saveToPayUI.closeWelcomeModal();
});

Promise Resolution Behavior (device-dependent)

This is the key behavior to understand: the same showWelcomeModalPromise call resolves differently depending on the end user's device, and the partner's frontend should be designed with this in mind:

Device type

When the Promise resolves

Desktop, Tablet, Mobile iOS

Only when the modal/iframe is closed (by the user, or via closeWelcomeModal()). The partner must read response.status afterward to learn the real outcome — closing the modal doesn't by itself mean success or failure.

Mobile Android

As soon as the provisioning session itself concludes — card added, failure, timeout, or user cancellation — or when closeWelcomeModal() is invoked, whichever comes first.

This distinction is why, on Android specifically, the SDK can resolve the Promise even if the user never manually closes anything: it's listening for the same postMessage result relay described in the end-to-end sequence diagram — the one that also drives the brief "REDIRECTING" dialog observed during testing before the deep-link handoff to the Wallet app.

Where this fits in the overall flow

This SDK is the component we labeled "SDK (s2p.min.js)" in the end-to-end sequence diagram — sitting between Partner Web UI and Samsung's Save to Pay/Samsung Wallet App. The alt branch in that diagram (QR modal vs. hidden iframe + deep link) is exactly the internal logic showWelcomeModal/showWelcomeModalPromise perform on the partner's behalf.