The Samsungpay payment method specification describes the data formats used by the PaymentRequest API [[!PAYMENTREQUESTAPI]] to support payment by SamsungPay.

Introduction

Samsung Pay is accepted at more places than any other mobile payment service out there, from the grocery store to the coffee shop to your favorite department store. It’s secure, easy to set up and simple to use with your latest Samsung Galaxy device. Currently Samsung Pay is available only on Samsung mobile devices running on Android operating system. This specification is a SamsungPay Payment Method Specification used by the PaymentRequest API [[!PAYMENTREQUESTAPI]]

This is a SamsungPay Payment Method Specification used by the PaymentRequest API [[!PAYMENTREQUESTAPI]] to support payment by Samsung Pay on Samsung devices.

Samsung Pay only supports merchants who accept tokenized payments. With tokenized response, it is intented to provide secured payment method for merchants and issuing banks who currently face many security issues requesting card details from customers.

Dependencies

This specification relies on several other underlying specifications.

Payment Request Architecture
The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [[!PAYMENTARCH]].
Payment Request API
The term PaymentRequest constructor is defined by the PaymentRequest API specification [[!PAYMENTREQUESTAPI]].
Payment Method Identifiers
The term Payment Method Identifier is defined by the Payment Method Identifiers specification [[!METHODIDENTIFIERS]].
Web IDL
The IDL in this specification is defined by Web IDL [[!WEBIDL]].

Payment Method Identifier

The following payment method identifier strings are supported by the Samsung Pay data formats.

Identifier String
https://samsung.com/pay

SamsungPay Prerequisites

SamsungPay Payment flows

Payment Method Specific Data

This section describes payment method specific data that is supplied as part of the data argument to the PaymentRequest constructor.

The following example shows how to construct data parameter and provide requried payment method information:

        var supportedInstruments = [
          {
            supportedMethods: ['https://samsung.com/pay'],
            data: {
              allowedCardNetworks: ['AMEX', 'MASTERCARD', 'VISA', 'DISCOVER'],
              paymentMethodTokenizationParameters: {
                tokenizationType: 'GATEWAY_TOKEN',
                parameters: {
                  // name of the gateway you support. Stripe is an example here. 
                  'gateway': 'stripe',
                  // Stripe publishable key here.
                  'stripe:publishableKey': 'pk_live_fD7ggZCtrB0vJNApRX5TyJ9T',
                  'stripe:version': '2016-07-06'
                }
              }
            }
          }
        ];
      

In order to use Samsung Pay with the gateway token approach, add a JSON object that contains the following parameters per the above example.

Payment Method Specific definition

Data is a JSON-serializable object passed as parameter of PaymentMethodData. The following defines JSON data syntax for SamsungPay payment method data.

         dictionary  SamsungPayRequestData { 
           required sequence<DOMString> allowedCardNetworks;
           object paymentMethodTokenizationParameters;
         };

         dictionary paymentMethodTokenizationParameters {
           required DOMString tokenizationType;
           object parameters;
         };
      
         object parameters {
          required 'gateway' : 'type-of-gateway';
          'gateway:keys' : "values";
          ...        
         };
      

Payment Method Response

Samsung Pay does not process the payment. The merchant would still need to invoke gateway APIs to charge/process the gateway token returned from Samsung Pay. When requesting a gateway token, Samsung Pay makes a call to your processor on your behalf and returns a chargeable gateway token. Payment Request API provides shipping address, contact information as outlined in specification [[!PAYMENTREQUESTAPI]]. SamsungPay returns JSON-serializable object SamsungPayResponse in addition to information received from [[!PAYMENTREQUESTAPI]].

The SamsungPayResponse dictionary contains the response from SamsungPay and returned as part of PaymentResponse details parameter.

Payment Method Response

SamsungPay response consist of follwing information including the token from gateway as specified from merchant.

          paymentRequest.show().then(response => {
            // Manually clone the resulting object
            var data = {};
            data.methodName = response.methodName;
            data.details    = response.details; // SamsungPayResponse
            data.payerEmail = response.payerEmail;
            data.payerPhone = response.payerPhone;
            data.address    = response.shippingAddress;
            data.shipping   = response.shippingOption;
          }
      

Merchant needs to submit response.details token to payment gateway to process payment. How you handle a submitted gateway token depends on the payment gateway. Please refer to the specific gateway’s documentation for more details.

SamsungPayPaymentResponse

      dictionary SamsungPayResponse {
        required DOMString token;
        object billingAddress;
        object contact;
      };
      

The SamsungPayPaymentResponse dictionary contains the following fields:

token
The token field is gateway token returned from your processor
billingAddress
The billingAddress field contains billing address of payee. Please refer SamsungPay response for more details.
contact
The contact field contains payee contact information for your processor. Please refer SamsungPay response for more details.