Integrate Samsung Pay Web Checkout

Use the following steps to integrate Web Checkout into your website.

Step 1: Include the Samsung Pay Web SDK

Include the Samsung Pay Web SDK script in your website’s frontend so that you can access the Web Checkout features.

<script src="https://img.mpay.samsung.com/gsmpi/sdk/samsungpay_web_sdk.js"></script>

Step 2: Define supported payment methods

Create the paymentMethods object to define the supported card brands, API version, and service ID.

const paymentMethods = {
  "version": "2",
  "serviceId": "dcc1cbb25d6a470bb42926",
  "protocol": "PROTOCOL_3DS",
  "allowedBrands": ["visa","mastercard"]
}

Step 3: Initialize the Samsung Pay client

Instantiate PaymentClient and set the operating environment.

The following environments are available:

• STAGE = Test payments on the staging environment with a real device.
• STAGE_WITHOUT_APK = Simulate payments without device authorization.
• PRODUCTION = Use the live production environment.

const samsungPayClient = new SamsungPay.PaymentClient({environment: "STAGE"});

If your site applies a Content Security Policy (CSP), add a nonce. The nonce is a unique, randomly generated value that you assign to script tags and the Samsung Pay configuration. It allows inline or injected content to execute when CSP rules are applied.
Generate a new nonce for each page load to maintain security.

const samsungPayClient = new SamsungPay.PaymentClient({environment: "STAGE", nonce: "your-randomly-generated-nonce"});

Step 4: Check Samsung Pay availability

Check whether Samsung Pay is supported for the current device, browser, and card brands. Call the isReadyToPay() method with the paymentMethods object. Only show the Samsung Pay button if response.result is true.

samsungPayClient.isReadyToPay(paymentMethods).then(function(response) {
  if (response.result) {
    // Show the payment button 
  }
}).catch(function(err) {
  console.error(err); 
});

Step 5: Show the Samsung Pay button

Show the Samsung Pay button on your page using the official branded asset.

<div id="samsungpay-container">
  <button id="samsung-pay-btn">
      <img src="/your/path../samsung-pay-button.png" alt="Samsung Pay" style="{follow Samsung's official branding guideline}" />
  </button>
</div>

Step 6: Attach a click event handler

Add a click handler to the Samsung Pay button.

document.getElementById("samsung-pay-btn").addEventListener("click", onSamsungPayButtonClicked);

Step 7: Prepare transaction details

Build the transactionDetail object with the order, merchant, and amount information based on what the customer wants to purchase.

const transactionDetail = {
  "orderNumber": "DSTRF345789dsgTY",
  "merchant": {
    "name": "Virtual Shop",
    "url": "virtualshop.com",
    "id": "xn7qfnd",
    "countryCode": "US"
    // If cardholder name and billing address are required:
    "isBillingAddressRequired" = "true",
    "isCardholderNameRequired" = "true"

},
  "amount": {
    "option": "FORMAT_TOTAL_ESTIMATED_AMOUNT",
    "currency": "USD",
    "total": 300
  }
}

Step 8: Launch the payment flow

From the Samsung Pay button's click handler:

1. Call the loadPaymentSheet() method to launch the Web Checkout UI. After the customer confirms the payment from their device, the method returns the payment token (generated on the device) inside the paymentCredential object.

2. Extract the token from 3DS.data within the paymentCredential object, decrypt it, and process it with your payment gateway. The token decryption and processing must take place on the server side. For more details, see Decrypt payment credentials and the payment gateway documentation.

3. After the payment gateway confirms the payment result, call the notify() method with the paymentResult object to update the payment status in the Samsung server.

function onSamsungPayButtonClicked() {
  samsungPayClient.loadPaymentSheet(paymentMethods, transactionDetail).then(function(paymentCredential) {
    // Process payment with payment gateway
    ...
    ...
    const paymentResult = {
      "status": "CHARGED",
      "provider": "PG Name"
    }  
    samsungPayClient.notify(paymentResult);
  }).catch(error => {
    // Show error in developer console for debugging
    console.error(err);
  });
}

The following code snippet is an example of the returned paymentCredential object:

{
  "method": "3DS",
  "recurring_payment": false,
  "card_brand": "visa",
  "card_last4digits": "8226",
  "3DS": {
    "type": "S",
    "version": "100",
    "data": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiIxZHlsbkFVRVJtTk53Z0J0MmVzcEVWU1pOSWRZZGhqbVI3bzhQcDVKaGVBPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.JyKXN2h9pk1Uj-4kNPuij1r49yKw7-3aElZnHAdzsZTcLVJLhOYjOmujfl1H21yQ_5rMdwZ9Lj6o67j8M6KN_1dNKvNQAUgi203oL5teGF-J15n_pcINJ1nYcfYIVOhazIdbg9FQ2nztS_mUu9cvYKIZ-iFsuz6RfL9aiuoaKjpcTZPN8LWlddZxZme3j86sD45i-AhXWBuJFVy9D2ZRT1sddgOxGOrJRzy3o5S29PYbKAYtJMcpc_Jicu-sDSX3S1Snm_CVHAqiCcOxYidIh6hFwo35FssWysvxu8yFPgTWbcdaI9uJkptVR7npNp1cH85JA3DvW3MI87v-pwiqmw.HdZesNBxU0d0T68e.pCv1CSIBW7JGtlgFOOvmeBM-wGGpW9rHOnBkDb_qWWFL_CuF7_0nj_kNuozQ4pUDK0_vzkTbHi3kV0Gt2YBmQs6ZfpnXD3CDPgK_lYiO8Z8xCiASoz5vLTamJG7n5mAAdXxPVqWtCPk_TbKsVE2ke8W7R3U4kApFJl2EnE06J3E4rkae367X8_aOXy2l3LHoeqZl4lFsNtFs71xfc-s9h5-Bgi2clKBa-9hLRtpbxTUmWa830rwywm7M.Fs5-tfBxQ73L7ICRRWKblA"
  },
  "encryptedMessage": "pCv1CSIBW7JGtlgFOOvmeBM-wGGpW9rHOnBkDb_qWWFL_CuF7_0nj_kNuozQ4pUDK0_vzkTbHi3kV0Gt2YBmQs6ZfpnXD3CDPgK_lYiO8Z8xCiASoz5vLTamJG7n5mAAdXxPVqWtCPk_TbKsVE2ke8W7R3U4kApFJl2EnE06J3E4rkae367X8_aOXy2l3LHoeqZl4lFsNtFs71xfc-s9h5-Bgi2clKBa-9hLRtpbxTUmWa830rwywm7M"
}