Integrate Samsung Pay Web Checkout with merchant sites


Objective

Learn how to integrate the Samsung Pay payment system into your merchant sites using the Samsung Pay Web Checkout SDK.

Partnership Request

To use the Samsung Pay Web Checkout SDK, you must become an official Samsung Pay partner. Once done, you can fully utilize this Code Lab. You can learn more about the partnership process by visiting the Samsung Pay page here in Samsung Developers.

Overview

The Samsung Pay Web Checkout service enables users to pay for purchases on your website with payment cards saved in the Samsung Wallet app on their mobile device. It supports browser-based payments on both computers and mobile devices. A mobile device with Samsung Wallet installed is required to make purchases through Samsung Pay Web Checkout.

When the user chooses to pay with Samsung Pay, they must provide their Samsung account ID (email ID) or scan the QR code on the screen with their mobile device. The user then authorizes the purchase within the Samsung Wallet application, which generates the payment credential on the device and transmits it to your website through the Web Checkout.

For more information, see Samsung Pay Web Checkout.

Set up your environment

You will need the following:

Start your project and register your service

In your browser, open the link below to access the project file of the sample merchant site:

codesandbox.io/s/virtual-store-sample-fnydk5

Click the Fork button to create an editable copy of the project.

Next, follow the steps below to register your sample merchant site in the Samsung Pay Developers site:

  1. Go to My Projects > Service Management.
  2. Click Create New Service.
  3. Select Web Online Payment as your service type.

  1. Enter your Service Name and select your Service Country.
  2. Select your Payment Gateway from the list of supported payment gateways (PG). If your PG uses the network token mode, upload the Certificate Signing Request (CSR) or Privacy Enhanced Mail (PEM) file you obtained from your PG. Contact your PG for details.
  3. Enter the payment domain name(s) for your website in the Service Domain field and click Add. For example, if your domain is mywebstore.com, but the checkout page is hosted on the subdomain payments.mywebstore.com, you will need to enter payments.mywebstore.com as the service domain. For each additional domain URL, click Add.

In this Code Lab, the generated Preview URL of the forked project is your Service Domain.

  1. Click the name of the newly created service to see its details, such as the generated Service ID that you can use for all the registered service domains.

Include the Samsung Pay Web Checkout JavaScript SDK

The Samsung Pay Web Checkout SDK uses JavaScript to integrate the Samsung Pay payment system to your website. This SDK allows users to purchase items via web browser.

In the <head> section of the index.html file of the project, include the Samsung Pay Web Checkout JavaScript SDK file:

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

Initialize the Samsung Pay client

To initiate payments using the Samsung Pay API, create a new instance of the PaymentClient class and pass an argument specifying that the environment as STAGE.

Write the code below in the <script> tag of the <body> section:

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

When the service is still in debug or test mode, you can only use the staging environment to test payment functionality without processing live transactions.

Next, define the Service ID, security protocol, and card brands that the merchant can support as payment methods.
The Service ID is the unique ID assigned to your service upon creation in the Samsung Pay Developers site.

let paymentMethods = {
  version: "2",
  serviceId: "", //Input your Service ID here
  protocol: "PROTOCOL_3DS",
  allowedBrands: ["visa", "mastercard"]
};

Check whether the Samsung Pay client is ready to pay using the given payment method.
Call the createAndAddButton() function if the response indicates that the client is ready:

samsungPayClient
  .isReadyToPay(paymentMethods)
  .then(function (response) {
    if (response.result) {
      createAndAddButton();
    }
  })
  .catch(function (err) {
    console.error(err);
  });

Create and implement the Samsung Pay button

Go to the <body> section and, inside the page-container div, create a container for the Samsung Pay button:

<div align="center" id="samsungpay-container"></div>

Next, go back to the <script> tag and write the createAndAddButton() function. Inside this function, generate the Samsung Pay button by calling the createButton() method.

Ensure that the button appears on the page by appending it to the container you created:

function createAndAddButton() {
  const samsungPayButton = samsungPayClient.createButton({
    onClick: onSamsungPayButtonClicked,
    buttonStyle: "black"});

  document
    .getElementById("samsungpay-container")
    .appendChild(samsungPayButton);
}


function onSamsungPayButtonClicked() {
  // Create the transaction information
  //Launch the payment sheet
}

From the createAndAddButton() function, call the onSamsungPayButtonClicked() function when the user clicks the generated button.

Create the transaction information

In the onSamsungPayButtonClicked function, create the transactionDetail object for the user’s purchase.

Input your service domain in the url key.

let transactionDetail = {
  orderNumber: "sAmPle0n1y123", 
  merchant: {
    name: "Virtual Shop",
    url: "", //Input your service domain
    countryCode: "US"
  },
  amount: {
    option: "FORMAT_TOTAL_ESTIMATED_AMOUNT",
    currency: "USD",
    total: 2019.99
  }
};

Below are the descriptions of the keys included in the transactionDetail object:

Key

Type

Description

orderNumber

String

Order number of the transaction
(Allowed characters: [A-Z][a-z][0-9,-])

merchant

Object

Data structure containing the merchant information

merchant.name

String

Merchant name

merchant.url

String

Merchant domain URL (e.g., samsung.com)

The maximum length is 100 characters.

merchant.countryCode

String

Merchant country code (e.g., US for United States)
ISO-3166-1 alpha-2

amount

Object

Data structure containing the payment amount

amount.option

String

Display format for the total amount on the payment sheet:
FORMAT_TOTAL_ESTIMATED_AMOUNT = displays "Total (Estimated amount)" with the total amount
FORMAT_TOTAL_PRICE_ONLY = displays the total amount only

amount.currency

String

Currency code (e.g., USD for US Dollar)
The maximum length is 3 character

amount.total

String

Total payment amount in the currency specified by amount.currency
The amount must be an integer (e.g., 300) or in a format valid for the currency,
such as 2 decimal places after a separator (e.g., 300.50).

Launch the payment sheet

After creating the transaction information, call the loadPaymentSheet() method to display the Web Checkout UI.

The user can either input their email address or scan the generated QR code. A timer screen in the Web Checkout UI is displayed after the user input, while a payment sheet is launched in the user's Samsung Wallet app.

The payment sheet contains the payment card option(s) and the transaction details.

When the user confirms their payment on their mobile device, you will receive the paymentCredential() object generated by the device.

Then, inform the Samsung server of the payment result using the notify method. The paymentResult() object contains the payment result information during transaction processing and after the payment is processed with the PG network.

samsungPayClient
  .loadPaymentSheet(paymentMethods, transactionDetail)
  .then(function (paymentCredential) {
    console.log("paymentCredential: ", paymentCredential);


    const paymentResult = {
      status: "CHARGED",
      provider: "TEST PG"
    };
    samsungPayClient.notify(paymentResult);
  })
  .catch(function (error) {
    console.log("error: ", error);
  });

Other possible values of the status key are:

  • CHARGED - payment was charged successfully
  • CANCELED - payment was canceled by either the user, merchant, or the acquiring bank
  • REJECTED - payment was rejected by the acquiring bank
  • ERRED - an error occurred during the payment process

Test the Samsung Pay button

After integrating the Samsung Pay Web Checkout service into your sample merchant site, follow the steps below to test the functionality of the integrated service:

  1. Open your sample merchant site in a new tab.

  1. Then, click the Pay with Samsung Pay button.

  1. In the Web Checkout UI, enter the email address of your Samsung Account to send a payment request to Samsung Pay.

  1. Tap the push notification sent to the Samsung Wallet app installed on your mobile device. Then, click Accept.

  1. When the payment sheet is loaded, tap on PIN and enter your PIN to proceed.

  1. A Verified message will display in both the Samsung Wallet app and Web Checkout UI to indicate that the payment was processed successfully.

You're done!

Congratulations! You have successfully achieved the goal of this Code Lab topic. Now, you can integrate the Samsung Pay Web Checkout service into your website by yourself. If you're having trouble, you may check the complete code below:

codesandbox.io/s/virtual-store-complete-dkhzfx

To learn more about developing apps for Samsung Pay devices, visit:
developer.samsung.com/pay