Web Checkout v1 SDK: API Integration Guide

---

API Integration

Include the Web Checkout SDK file

Samsung Pay Web Checkout SDK is developed using JavaScript. Partners should add the code in front-end as below after uploading in resource path.

SDK for Staging environment

<script src="https://d35p4vvdul393k.cloudfront.net/sdk_library/us/stg/ops/pc_gsmpi_web_sdk.js"></script>

SDK for Production environment

<script src="https://d16i99j5zwwv51.cloudfront.net/sdk_library/us/prd/ops/pc_gsmpi_web_sdk.js"></script>

Call the 'connect' function

Web Checkout SDK provides a connect() function wherein the arguments of this function is retrieved from the response of Create transaction API. This function checks whether the user's browser is in a mobile or desktop environment, and opens the Web Checkout UI page.

SamsungPay.connect( 
    Transaction ID, href, Service ID, Callback URL, Cancel URL, Country Code, PublicKey(Mod), PublicKey(Exp), Key ID
);

Field	Description
Transaction ID	Retrieve id generated from Create Transaction API response.
href	Retrieve href generated from Create Transaction API response.
Service ID	Unique identifier for your system in the Web Checkout service. This is generated after the Partner Onboarding in Samsung Pay Partner Portal.
Callback URL	This is the return URL after the authorization is verified by the user. When redirecting to this callback URL after user verification, Web Checkout server adds a reference ID (ref_id) query string.
Cancel URL	Cancel URL to redirect when the user cancels the payment.
Country Code	Default country code when the checkout page is popped up e.g.: If the country code is set to ru, Web Checkout UI displays in Russian language.
PublicKey(Mod)	Retrieve encInfo.mod generated from Create Transaction API response.
PublicKey(Exp)	Retrieve encInfo.exp generated from Create Transaction API response.
Key ID	Retrieve encInfo.keyId generated from Create Transaction API response.

Sample code (ajax)

$.ajax({
  type: "POST",
  url: "./transactions",
  data: #API Request body in here,
  success: function (result) {
    SamsungPay.connect(
      result.id, result.href, serviceId, callback, cancel, countryCode,
      result.encInfo.mod, result.encInfo.exp, result.encInfo.keyId
    );	
  },
  error: function (result) {
  }
}); 

Supported Country Codes

The country codes supported by Web Checkout service follows the ISO 639-1 standard country code formatting.

Country Code	Country – Displayed Language
en-AU	Australia – English
pt-BR	Brazil – Portuguese
fr	France – French
de	Germary – German
zh-HK	Hong Kong – Chinese (Hong Kong)
it	Italy – Italian
kk-KZ	Kazakhstan – Kazakh
ru-KZ	Kazakhstan – Russian
en	Malaysia – English
ru	Russia – Russian
en	Singapore – English
es	Spain – Spanish
sv	Sweden – Swedish
de-CH	Switzerland – German
en-CH	Switzerland – English
fr-CH	Switzerland – French
it-CH	Switzerland – Italian
zh-TW	Taiwan – Chinese (Traditional)
th	Thailand – Thai
ar-AE	United Arab Emirates (UAE) – English
ae-AE	United Arab Emirates (UAE) – Arabic
en-AE	United Arab Emirates (UAE) – English
en-GB	United Kingdom (UK) – English
en-US	United States of America (USA) – English
vn	Vietnam – Vietnamese
kr	South Korea – Korean
en	United Kingdom (UK) – English

Integration on WebView

To configure the browser's WebView enablements, refer to Integration on WebView.

---

Integration Test

Once the integration for Create Transaction API and Web Checkout SDK is set up, the service is ready to be tested.

1. To start the integration test, initiate checkout via browser with Web Checkout UI.
2. User is prompted to sign in with either of the following:
   2-1. Samsung account email
   2-2. Scan QR code
3. After confirming the user input, check for a push notification in Samsung Wallet app for a payment. Once accepted, user is prompted to verify their identity via PIN or biometrics.
4. Once done, a "Verified" page is displayed in both wallet app and Web Checkout UI to finish the authorization process.
5. User is redirected to the partner callback URL once the authorization process is finished.

At the callback URL page, partners should retrieve the ref_id from the query string and call the Get payment credentials API. Once the payment credentials are retrieved, partner should decrypt the credentials, then process in their respective payment flows to Acquirer.

To decrypt the payment credentials, refer to Decrypting payment credentials.

Upon processing the payment flows from the partner side, call the Notify result API and send the payment results to Web Checkout server.

---

API Reference

Common Headers

Following common headers are required to be included in all requests. The ones marked 'only for device' is only mandatory for the requests from device. The others are required to be provided for internal servers or partners integration. If any one of these headers is not included, TR may return the mandatory parameters missing parameter missing error with a 400 Bad Request HTTP status.

Request

Key	Value	Required
Content-Type	application/json	Required
X-Request-Id	Unique identifier for the request	Required

Response

Key	Value	Required
X-Response-Id	Unique identifier for the response Same as X-Request-Id	Required

Error Message Format

Key	Type	Required	Description
resultCode	String	Required	Error code defined
resultMessage	String	Required	Description of the cause of this error

To integrate Web Checkout v1 SDK, the following APIs should be added:

No	Method	URL	Description
1	POST	/ops/v1/transactions	Create transaction with details
2	GET	/ops/v1/transactions/paymentCredentials/{referenceId}	Get payment credentials
3	POST	/ops/v1/notifications	Notify payment result
4	HEAD	/ops/v1/internal/health	Health check

Create transaction with details

This API is used for creating transactions within the Web Checkout service. This is the point of entry for service integration. The response table is used for calling the connect() function by entering them as arguments.

Request Body

Key	Type	Required	Description
callback	String	Required	Callback URL *Maximum length: 1000 characters
paymentDetails	JSON Object	Required	Payment information container
paymentDetails.service	JSON Object	Required	Service object container
paymentDetails.service.id	String	Required	Service ID given to the user *Maximum length: 22 characters
paymentDetails.orderNumber	String	Conditional	Order number for transaction *Allowed characters: [A-Z][a-z][0-9,]
paymentDetails.isRecurring	Boolean	Optional	TRUE if payment is recurring. Default value is FALSE.
paymentDetails.protocol	JSON Object	Conditional	Payment protocol container *Conditional: Required if transaction for payment
paymentDetails.protocol.type	String	Required	Payment protocol type Value must be one of: - 3DS *Maximum length: 30 characters
paymentDetails.protocol.version	String	Required	Payment protocol version *Maximum length: 20 characters
paymentDetails.amount	JSON Object	Conditional	Payment amount information container *Conditional: Required if transaction for payment
paymentDetails.amount.option	String	Optional	Display option Value must be one of: - FORMAT_TOTAL_ESTIMATED_AMOUNT - Display the total estimated amount on payment sheet - FORMAT_TOTAL_PRICE_ONLY - Display total price amount on custom payment sheet *Maximum length: 45 characters
paymentDetails.amount.currency	String	Required	Currency code *Maximum length: 3 characters
paymentDetails.amount.total	Number	Required	Payment total amount in the provided currency. Format should be in integer or any value valid in the provided currency. *Typically in decimal format with 2 fractional digits after the separator (e.g.: 300.50)
paymentDetails.merchant	JSON Object	Required	Merchant information container
paymentDetails.merchant.name	String	Required	Merchant name *Maximum length: 100 characters
paymentDetails.merchant.reference	String	Optional	Merchant reference *Maximum length: 45 characters
paymentDetails.merchant.url	String	Required	Merchant domain URL *Maximum length: 100 characters
paymentDetails.allowedBrands[i]	Array of Strings	Optional	Allowed card brands This specifies card brands accepted by the merchant. If no brand is specified, all brands are accepted by default. If at least one brand is specified, all unspecified card brands is set to "Card not supported" on the payment sheet. Example values are: - VI - Visa - MC - Mastercard - AX - American Express - DS - Discover - MADA - MADA
features	JSON Array	Optional	Supported features container
features[i]	JSON Object	Required	Supported feature information
features[i].id	String	Required	Features enabled Example values are: - COMBOCARD - DSRP
features[i].type	String	Conditional	Feature type Value must be one of: If id = DSRP: - UCAF (Default) - ICC
type	String	Optional	Transaction type This value is specifically supported for MADA tokens and will not apply to other token types. Value must be one of: - PURCHASE (Default) - PREAUTHORIZATION

Response Status

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

Response Body

Key	Type	Required	Description
resultCode	String	Required	Result code
resultMessage	String	Required	Result message
id	String	Required	Created transaction ID
href	String	Required	Resource href (web URL) to be passed in Web Checkout SDK
encInfo	JSON Object	Required	Encrypt information
encInfo.keyId	String	Required	RSA Key ID
encInfo.mod	String	Required	RSA public key - modulus
encInfo.exp	String	Required	RSA public key - exponent

Errors

HTTP Code	Result Code	Description
201	0	SUCCESS
400	OPM1N1001	%s mandatory parameter does not exist or is empty
400	OPM1N1002	%s parameter value is invalid
400	OPM1N1003	%s parameter format is invalid ↳ one of the parameters has invalid value Could not read document ↳ Whole request body has invalid JSON format
400	OPM1N1005	%s parameter length is longer than the max length limit
400	OPM1N1035	Service %s does not exist
409	OPM2N1103	The transaction is already bound to a device
500	OPM3N1002	Data encryption error
500	OPM5N9001	DB data processing error

Get payment credentials

This API is used for getting payment credential data generated in the user’s mobile device. This credential data is temporarily stored within the Samsung server upon generation, then the Web Checkout UI is redirected to the partner callback URL, with the reference ID as a query parameter.

https://{Your Callback URL}?ref_id={reference ID}

Once the partner callback URL is called, the partner system should retrieve the reference ID from the query string, and it is used for the path parameter for the Get payment credentials API.

/ops/v1/transactions/paymentCredentials/{referenceId}?serviceId={serviceId}

Request Parameters

Location	Key	Required	Description
Path	referenceId	Required	Reference ID
Query	serviceId	Required	Service ID

Response Status

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

Response Body

Key	Type	Required	Description
resultCode	String	Required	Result code
resultMessage	String	Required	Result message
wallet_dm_id	String	Optional	Unique identifier of the user's device
method	String	Required	Inputted payment protocol type e.g.: 3DS
recurring_payment	Boolean	Required	TRUE if the credential is enabled for recurring payment
card_last4digits	String	Optional	Last 4 digits of FPAN
card_brand	String	Optional	Card brand
3DS	JSON Object	Conditional	Transaction 3DS data object
3DS.type	String	Required	3DS type Example value: - S = Samsung Pay
3DS.version	String	Required	3DS version Example value: - 100 = current version
3DS.data	String	Required	The payment credentials data encrypted the partner CSR (public). Upon decrypting in partner side, proceed with processing the payment with Acquirer.
certificates	JSON Array	Conditional	Certificate array
certificates[i]	JSON Object	Required	Certificate object
certificates[i].usage	String	Required	Certificate usage Value must be one of: - CA - VER
certificates[i].alias	String	Required	Certificate alias
certificates[i].content	String	Required	Certificate container
features	JSON Array	Optional	Supported features container
features[i]	JSON Object	Required	Supported feature information
features[i].id	String	Required	Features to be enabled Example values are: - COMBOCARD - DSRP
features[i].type	String	Required	Feature type Value must be one of: If id = COMBOCARD: - CREDIT - DEBIT If id = DSRP: - UCAF (Default) - ICC

Errors

HTTP Code	Result Code	Description
200	0	SUCCESS
400	OPM1N1001	%s mandatory parameter does not exist or is empty
400	OPM1N1002	%s parameter value is invalid
400	OPM1N1009	Transaction has been cancelled by user or an error occurred
400	OPM1N1033	This partner is not approved status
400	OPM1N1035	Service %s does not exist
500	OPM3N1002	Data encryption error
500	OPM5N9001	DB data processing error

The 3DS.data is encrypted by the partner public CSR, which uses JWE or JWE/JWS (without AAD) encryption. The partner can decrypt them, and proceed with processing the payment with the Acquirer.

To decrypt the payment credentials, refer to Decrypting payment credentials.

Notify payment result

This API is used to notify the Samsung Pay Web Checkout server of the payment result. After processing the payment with the Acquirer, partners can retrieve the result from their Acquirer, and sent it to Web Checkout server through this API.

Request Body

Key	Type	Required	Description
payment	JSON Object	Required	Payment information container
payment.service	JSON Object	Required	Service object container
payment.service.id	String	Required	Service ID given to partner
payment.reference	String	Required	Payment reference used in transaction. payment.reference should be passed to the callback URL of the web script to get payment credential and notification
payment.status	String	Required	Payment status Value must be one of: - CHARGED – Payment was charged successfully - CANCELED – Payment was canceled by either user, merchant, or Acquirer - REJECTED – Payment was rejected by Acquirer - TIMEOUT – Payment received a timeout during the payment process - ERRED – Error has occurred during the payment process
payment.provider	String	Optional	PG name
merchant	JSON Object	Optional	Merchant information container
merchant.name	String	Optional	Merchant name
merchant.reference	String	Optional	Merchant reference (PG-managing identifier)
timestamp	Number	Required	Request timestamp Value must be epoch in milliseconds

Response Status

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8

Response Body

Key	Type	Required	Description
resultCode	String	Required	Result code
resultMessage	String	Required	Result message

Errors

HTTP Code	Result Code	Description
202	0	SUCCESS
400	OPM1N1001	%s mandatory parameter does not exist or is empty
400	OPM1N1002	%s parameter value is invalid
400	OPM1N1003	%s parameter format is invalid ↳ one of the parameters has invalid value Could not read document ↳ Whole request body has invalid JSON format
404	OPM1N1035	Service %s is not exist
500	OPM3N1002	Data encryption error
500	OPM5N9001	DB data processing error

Health check

A Health check implementation is available for checking communication status between the Samsung server, PG, or merchant servers. This functionality checks the bidirectional communication. It is required to implement the health check on the PG/Merchant server side.

The health check is first triggered from the Samsung server to the PG/Merchant server side. Then, the PG/Merchant server side checks the communication with the Samsung server and depending on the status, returns a final response to the Samsung server.

To configure this API, refer to Configuring the Health check API.

---

Decrypting payment credentials

1. Generate der file using your private key

$ openssl pkcs8 -topk8 -in Merchant.key -outform DER -nocrypt -out rsapriv.der

2. Decrypt JWE credential data

Sample code(Java)

import java.io.*;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import javax.crypto.*;
...
public static void main(String[] args) {
  String encPayload = {{encryptedPayload}};
  String privateKeyFilePath = "./rsapriv.der";
  getDecryptedData(encPayload, privateKeyFilePath);
}

public static String getDecryptedData(String encPayload, String privateKeyFilePath) {
  String delims = "[.]";
  String[] tokens = encPayload.split(delims);

  Decoder urlDecoder = Base64.getUrlDecoder();
  byte[] encKey = urlDecoder.decode(tokens[1]);
  byte[] iv = urlDecoder.decode(tokens[2]);
  byte[] cipherText = urlDecoder.decode(tokens[3]);
  byte[] tag = urlDecoder.decode(tokens[4]);
  byte[] plainText = new byte[cipherText.length];

  try {
    // Read private key file
    File privateKeyFile = new File(privateKeyFilePath);
    DataInputStream dis = new DataInputStream(new FileInputStream(privateKeyFile));
    byte[] privKeyBytes = new byte[(int) privateKeyFile.length()];
    dis.read(privKeyBytes);
    dis.close();

    // Set private key spec
    PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(privKeyBytes);
    KeyFactory keyFactory = KeyFactory.getInstance("RSA");
    PrivateKey privKey = keyFactory.generatePrivate(spec);

    Cipher decryptCipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
    decryptCipher.init(Cipher.DECRYPT_MODE, privKey);
    byte[] plainEncKey = decryptCipher.doFinal(encKey);

    final Cipher aes128Cipher = Cipher.getInstance("AES/GCM/NoPadding");
    final GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(16 * Byte.SIZE, iv);
    final SecretKeySpec keySpec = new SecretKeySpec(plainEncKey, "AES");
    aes128Cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmParameterSpec);

    int offset = aes128Cipher.update(cipherText, 0, cipherText.length, plainText, 0);
    aes128Cipher.update(tag, 0, tag.length, plainText, offset);
    aes128Cipher.doFinal(plainText, offset);
  } catch (Exception e) {
  }
  return new String(plainText);
}

Sample code
The following packages need to be installed for C# .netCore

Install-Package ChilkatDnCore -Version 9.5.0.69 (https://www.nuget.org/packages/ChilkatDnCore/)
Install-Package jose-jwt (https://www.nuget.org/packages/jose-jwt/)

using Jose;
using System;
using System.Text;
...
static void Main(string[] args)
{
  String encPayload = {{encryptedPayload}};
  String privateKeyFilePath = "./rsapriv.der";
  getDecryptedData(encPayload, privateKeyFilePath);
}

static void getDecryptedData(String encPayload, String privateKeyFilePath) {
  char delims = '.';
  string[] tokens = encPayload.Split(delims);
  byte[] header = Base64Url.Decode(tokens[0]);
  string headerString = Encoding.UTF8.GetString(header);
  Console.WriteLine("headerString: " + headerString);
  byte[] encKey = Base64Url.Decode(tokens[1]);
  byte[] iv = Base64Url.Decode(tokens[2]);
  byte[] cipherText = Base64Url.Decode(tokens[3]);
  byte[] tag = Base64Url.Decode(tokens[4]);
  byte[] plainText = new byte[cipherText.Length];

  Chilkat.Rsa rsa = new Chilkat.Rsa();
  bool success = rsa.UnlockComponent("Anything for 30-day trial");
  if (success != true) {
    Console.WriteLine(rsa.LastErrorText);
    return;
  }

  Chilkat.PrivateKey privateKey = new Chilkat.PrivateKey();
  success = privateKey.LoadPemFile(privateKeyFilePath);
  if (success != true) {
    Console.WriteLine(privateKey.LastErrorText);
    return;
  }

  success = rsa.ImportPrivateKeyObj(privateKey);
  if (success != true) {
    Console.WriteLine(rsa.LastErrorText);
    return;
  }

  rsa.EncodingMode = "base64";
  rsa.OaepPadding = false;
  bool usePrivateKey = true;
  byte[] plainEncKey = rsa.DecryptBytes(encKey, usePrivateKey);
  Console.WriteLine(
      "plainEncKey: " + Encoding.UTF8.GetString(plainEncKey) + ", size: " + plainEncKey.Length);

  AesGcmEncryption aesGcmEngine = new AesGcmEncryption(128);
  plainText = aesGcmEngine.Decrypt(null, plainEncKey, iv, cipherText, tag);
  Console.WriteLine("plainText: " + Encoding.UTF8.GetString(plainText));
}

Configuring the Health Check API

Sample code(Java)

import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.*;
import org.springframework.web.bind.*;
import org.springframework.web.client.*;

@RestController
public class HealthCheckController {

    @Value("${ops.address}")
    private String onlinePaymentsAddress;

    @RequestMapping(method = RequestMethod.HEAD, value = "/samsungpay/integration/health")
    public ResponseEntity<Void> health() {

        String healthcheckAddress = onlinePaymentsAddress + "/ops/v1/internal/health";
        RestTemplate restTemplate = new RestTemplate();
        ResponseEntity<Void> healthcheckResponse;

        try {
            healthcheckResponse = restTemplate.exchange(healthcheckAddress, HttpMethod.HEAD,
                    null, Void.class);
        } catch (RestClientException e) {
            return new ResponseEntity<>(HttpStatus.BAD_GATEWAY);
        }

        if (healthcheckResponse.getStatusCode() != HttpStatus.NO_CONTENT) {
            return new ResponseEntity<>(HttpStatus.BAD_GATEWAY);
        }

        return healthcheckResponse;
    }
}