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
You will need the following:
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:
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);
});
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.
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.
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
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. 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