Overview

Description

Samsung Pay Web Checkout
This page describes all 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 others except for authorized partner members.

Terms

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

Pre-requisites

  • User needs to have SamsungPay-enabled mobile device, even for PC payments.
  • Acquirer/Issuer supports Tokenized transactions for In-App purchases according to the Card Network specifications.

Facts

  • Support for PC and Mobile browser-based payments, using cards tokenized on mobile device
  • User identification and Device binding are 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 for payment to users on your web site. The user can then select the SamsungPay option to pay, and then a push message requesting payment arrives to the user’s device and the payment can be confirmed by user authentication. The generated payment cryptogram and data are passed to your system and finally bypassed to PG (Payment Gateway) and card network side 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 can detect this environment. In this case, the account binding process can be done at the device level because the web browser and SamsungPay application run on 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 the 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

Ingetration 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 that they can register it at the admin portal. After registration, the SamsungPay team informs you of your Service ID. The Service ID is used to integrate with SamsungPay Web Checkout APIs and 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 matche, 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 purpose. In order to support this, we need to get the developers’ IP addresses from 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 figuring out how to use it.

Integration environment settings

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

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

  3. 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 are able to get the value of each field.

    Development

    ```json
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"
    }
}
  1. Getting started with the Samsung Pay Web Checkout SDK file

When the Samsung team sends you your Service ID, they also provide the Web Checkout SDK. This script file is used for opening the Web Checkout UI page. To learn more about the Web Checkout SDK, see the 6. Getting Started with the Web Checkout SDK section of this document.