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.

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 can obtain the value of each field.

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.