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.

NoteIn accordance with the applicable Samsung Pay Partners agreements, this Code Lab covers the setup and use of the Samsung Pay Web Checkout SDK for purposes of integrating Samsung Pay with merchant sites. The use cases and corresponding code samples included are representative examples only and should not be considered as either recommended or required.

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

NoteFor SDC24 attendees, skip this step as it’s already done for you. Proceed to 5. Include the Samsung Pay Web Checkout JavaScript SDK.

You will need the following:

Access to Samsung Pay Developers site
Samsung Wallet test app from Samsung Pay Developers site
Samsung Galaxy device that supports Samsung Wallet app
Internet browser, such as Google Chrome
CodeSandbox account

NoteIn this Code Lab, you can use the Samsung Wallet test app to try the functionality of the Samsung Pay Web Checkout service in a staging environment. You can use the official Samsung Wallet app from the Galaxy Store once your service is in the production environment.

Start your project and register your service

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

https://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:

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

Enter your Service Name and select your Service Country.
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.
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.

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.

NoteBy default, the service is initially set to debug or test mode during creation. To switch the service status to release mode, a request must be made through the Samsung Pay Developers site. After successfully transitioning to release mode, change the environment to PRODUCTION.

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).

NoteFor the complete list of specifications for the transactionDetail object, see Samsung Pay Web Checkout API Reference.

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.

NoteFor real transactions, you need to extract the payment credential information from the 3DS.Data key within the paymentCredential object and process it through your payment provider. However, in this Code Lab, you only need to print the paymentCredential to the console.

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:

Open your sample merchant site in a new tab.

Then, click the Pay with Samsung Pay button.

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

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

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

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.

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