Overview

Description

Samsung Pay Web Checkout
This page provides guidance for the SamsungPay Web Checkout service. It is primarily aimed at partners that want to integrate with this service. This document includes onboarding processes, service flows, Web SDK and API call instructions, and other elements of the integration process. This document must not be distributed to anyone except authorized partner members.

Terms

Term	Description
PG	Payment Gateway
Web SDK	Web development kit which is included in the partners’ web system to integrate with the SamsungPay payment system
Web Checkout UI	SamsungPay web page for Web Checkout

Prerequisites

User needs to have a SamsungPay-enabled mobile device, even for PC payments.
Acquirer/Issuer supports tokenized transactions for in-app purchases according to card network specifications.

Facts

Support for PC and mobile browser-based payments, using cards tokenized on a mobile device
User identification and device binding based on Samsung account ID (email ID)
Requires server-to-server integration between Samsung and Partner backend servers
User authentication and payment credential generation happen in the user device

User Scenario

Partner webpage and device binding

User authentication (on mobile device)

Payment processing & order completion

Web Checkout flow

Payment through PC Web

You can provide a SamsungPay option on your website for users. The user can select the SamsungPay option to pay, and a push message requesting payment arrives on the user’s device. The payment is then confirmed by user authentication. The generated payment cryptogram and data are passed to your system and finally sent to PG (Payment Gateway) and the card network for transaction approval.

Figure 1. Transaction creation and account binding flow in a PC web environment

Figure 2. Payment confirmation flow in a PC web environment

Figure 3. Transaction completion flow in a PC web environment

Payment through Mobile Web

If the user accesses the merchant’s web site through a mobile web browser, the SamsungPay web SDK detects this environment. In this case, the account binding process is done at the device level because the web browser and SamsungPay application run on the same device. You can see the detailed steps of device-level account binding in the following figures.

Figure 4. Transaction completion flow in a PC web environment

Figure 5. Transaction completion flow in a PC web environment

SamsungPay Web Checkout is designed to operate in Samsung Internet and Google Chrome browsers. For Android apps which use WebView, you must invoke the SamsungPay InApp SDK, instead of using this Web Checkout SDK.

Service integration procedure

Integration preparation

For onboarding as a new partner of the SamsungPay Web Checkout service, you need to provide the following information to the SamsungPay team so they can register it at the admin portal. After registration, the SamsungPay team provides you with your Service ID. The Service ID is used to integrate with SamsungPay Web Checkout APIs and the Web Checkout UI.

Info	Description
Service name	Provide the PG or Merchant service name
Domains	This is used for verifying server-to-server API calls. The SamsungPay Web Checkout API server compares the domain or IP that calls the API with this field. If they do not match, the transaction creation fails.
CSR	Your CSR (Public) file needs to be delivered to the SamsungPay team. If you have separate files for development and production environments, submit these two files together.
The SamsungPay team registers your CSR at the admin portal, and payment credential data is encrypted using this CSR.
Development server IPs	Submit your development server IPs for registering them in the firewall exception list in our development environment. The Web UI and Web Checkout API server in the Samsung development environment is then opened for these IP addresses.
Production server IPs	Submit your production server IPs for registering them in the firewall exception list in our production environment for server-to-server connection. The Web Checkout API server is then opened for these IP addresses.
Developer IPs	Developers need to manually call the Web Checkout APIs for testing purposes. In order to support this, we need the developers’ IP addresses on your side. These need to be external IP addresses such as proxy server IPs. The Samsung team then registers them.
Service ID	Unique identifier for identifying your system in the SamsungPay Web Checkout service. The service ID is used for the whole flow of the Web Checkout service. Refer to this document for information on how to use it.

InformationAfter completing the registration, the Samsung team provides you with your service ID for the Web Checkout service. This Service ID is very important because it is used for the whole Web Checkout service flow. The Samsung team provides two Service IDs: one for the development environment and the other for the production environment.

Integration environment settings

Firewall exception registration

Initially, the Samsung team registers your servers’ and developers’ IP addresses in the development environment. Once the service integration between you and Samsung is completed in the development environment, your production server IPs are registered in the same way.
Testing the Web checkout API server connection

After the firewall registration by the Samsung team, you need to test the server-to-server connection.

Environment API endpoint

Development https://api-ops.stg.mpay.samsung.com

Production https://api-ops.mpay.samsung.com
Calling the Web Checkout API for testing

If the server-to-server connection is confirmed, you can call the Web Checkout APIs for testing purposes. With this testing, you can obtain the value of each field.

Environment	API endpoint
Development	https://api-ops.stg.mpay.samsung.com
Production	https://api-ops.mpay.samsung.com

Development

POST https://api-ops.stg.mpay.samsung.com/ops/v1/transactions
Content-Type:application/json
{
    "callback": "https://merchant.host.endpoint/order/KjeNvldA64v91gaHa/result",
    "paymentDetails": {
        "service": {
        "id": "dcc1cbb25d6a470bb42926acfbe1210f"
        },
    "orderNumber": "DSTRF345789dsgTY","protocol": {
        "type": "3DS",
        "version": "80"
        },
    "amount": {
        "option": "FORMAT_TOTAL_ESTIMATED_AMOUNT",
        "currency": "USD",
        "total": 300
        },
    "merchant": {
        "name": "virtual shop",
        "url": "virtualshop.com",
        "reference": "xn7qfnd"
        },
    "allowedBrands": [
        "VI",
        "MC"
        ]
    }
}

Production

POST https://api-ops.mpay.samsung.com/ops/v1/transactions
Content-Type:application/json
{
    "callback": "https://merchant.host.endpoint/order/KjeNvldA64v91gaHa/result",
    "paymentDetails": {
        "service": {
        "id": "dcc1cbb25d6a470bb42926acfbe1210f"
        },
    "orderNumber": "DSTRF345789dsgTY","protocol": {
    "type": "3DS",
    "version": "80"
    },
    "amount": {
        "option": "FORMAT_TOTAL_ESTIMATED_AMOUNT",
        "currency": "USD",
        "total": 300
    },
    "merchant": {
        "name": "virtual shop",
        "url": "virtualshop.com",
        "reference": "xn7qfnd"
    },
    "allowedBrands": [
        "VI",
        "MC"
        ]
    }
}

If the call is successful, the following response is returned

{
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "id": "59e30acf1eba4d998e646e",
    "href": "https://us-online.stg.mpay.samsung.com/onlinepay",
    "encInfo": {
        "mod": "f65146e3497b8f737d449d1cf428f878f",
        "exp": "10001",
        "keyId": "9a010e4f3d484c07bddb"
    }
}

Getting started with the Samsung Pay Web Checkout SDK file

When the Samsung team sends you your Service ID, they also share the Web Checkout SDK information. This SDK is used for opening the Web Checkout UI page. To learn more about the Web Checkout SDK, see section API Integration.