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.
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:
Keep your client certificate secure and monitor its expiration dates.
Log and monitor inbound and outbound requests for verification and debugging.
Maintain a testing (staging) environment for ongoing testing.
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
.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:
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.
Manage Your Cookies
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
developer.samsung.com, .samsung.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
Samsung Electronics
.samsung.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
Samsung Electronics
developer.samsung.com, google.account.samsung.com
Preferences Submitted
You have successfully updated your cookie preferences.