Samsung pay - LiteCore API Reference

Samsung Pay on the web involves three separate decisions:

Where the customer checks out.
Who owns the Samsung Pay service.
Who decrypts the Samsung Pay payment credential.

These decisions are related, but independent. A merchant can own the Samsung Pay service while Lite decrypts the payment credential. The deciding factor for decryption is who holds the private key behind the CSR registered in Samsung Developer Portal.

Samsung Pay is not Apple Pay Samsung Pay Web Checkout does not use a .well-known domain-association file. It uses a Samsung Pay service with a Service ID, configured website and callback URLs, and a CSR that tells Samsung which public key to use when encrypting payment credentials.

Terminology

Term	Meaning
Samsung Pay service	The Samsung configuration for accepting online payments. It has a country, a payment gateway, and a Service ID.
Service ID	The identifier the Samsung Web Checkout SDK uses to start Samsung Pay in the browser.
Payment credential	The encrypted payment data returned by Samsung Wallet after the customer approves payment.
CSR	A file containing a public key. Samsung encrypts the payment credential with this key.
Private key	The secret key paired with the CSR. Whoever holds it can decrypt the payment credential.
Result notification	The `notify()` call that tells Samsung whether the payment was charged, rejected, cancelled, timed out, or failed.

Choose an integration route

Route	Checkout experience	Samsung Pay service	Who runs Samsung’s Web Checkout SDK	Who decrypts
1. Hosted Checkout	Lite-hosted payment page	Lite-managed	Lite	Lite
2. Lite SDK	Merchant page, Lite SDK renders Samsung Pay	Lite-managed	Lite SDK	Lite
3. Direct API, Lite-managed service	Merchant-built checkout	Lite-managed	Merchant	Lite
4. Direct API, merchant-owned service	Merchant-built checkout	Merchant-owned	Merchant	Lite by default. Merchant decryption is an approved advanced option.

Lite-managed service means Lite acts as the Samsung Pay payment gateway for the merchant. Lite provisions or assigns the Samsung configuration, holds the CSR private key, decrypts the payment credential, and processes the payment. The merchant never creates a Samsung Developer account or handles a CSR. In every route, Lite processes the payment: authorization, capture, refunds, voids, and payment lifecycle webhooks.

What ownership controls

Decision	What it controls
Samsung Pay service ownership	Who uses Samsung Developer Portal, creates the service, manages the Service ID, and configures Samsung-side URLs and gateway settings.
Private key ownership	Who decrypts the Samsung Pay payment credential.
Payment processing	Always Lite.

For merchant-owned services (Route 4), two key models exist: Lite decrypts (Route 4A). Lite generates the CSR and keeps the private key. The merchant uploads the Lite-provided CSR to Samsung Developer Portal. This is safe: a CSR contains only a public key. The merchant never sends a private key to Lite, and Lite never asks for one. Merchant decrypts (Route 4B). The merchant generates its own key pair and CSR, uploads its CSR to Samsung, decrypts the payment credential, and sends Lite the payment payload Lite defines. This route requires Lite approval and carries PCI DSS responsibilities on the merchant side.

Route 1: Hosted Checkout

Fastest launch. The merchant redirects the customer to Lite Hosted Checkout. Lite owns the Samsung Pay browser flow and all Samsung-side operations.

Onboarding

Enable Samsung Pay for the Lite channel in Lite Dashboard.
Lite checks merchant, channel, country, and card scheme eligibility, then provisions or links a Lite-managed Samsung Pay service.
Samsung Pay is ready to test.

Payment flow

Merchant steps

Enable Samsung Pay for the Lite channel.
Create a Lite checkout session from your backend.
Redirect the customer to Lite Hosted Checkout.
Verify and process Lite webhooks.

The merchant does not create a Samsung Developer account, handle a CSR, configure Samsung URLs, run Samsung’s SDK, touch the payment credential, or call Samsung result notification APIs.

Route 2: Lite SDK

Samsung Pay appears inside the merchant’s checkout page, but Lite SDK owns the Samsung Web Checkout flow. Onboarding is identical to Route 1: enable Samsung Pay for the channel, and Lite provisions the Lite-managed service.

Payment flow

Merchant steps

Enable Samsung Pay for the Lite channel.
Create a Lite checkout session from your backend.
Pass client-safe session data to the browser.
Initialize and mount Lite SDK, then handle its events.
Verify and process Lite webhooks.

Lite SDK owns availability checks, the Samsung Pay button, Samsung Web Checkout initialization, the Samsung Wallet handoff, credential delivery to Lite, the Samsung result notification, and result presentation. The merchant writes no Samsung Web Checkout code and never calls notify().

Direct API (Routes 3 and 4)

Use Direct API when you need full control over checkout behavior. You build the checkout page and integrate Samsung’s Web Checkout SDK. Lite decrypts the credential, processes the payment, and returns a result you use to notify Samsung.

Route 3: Lite-managed service

Lite owns the Service ID, the CSR private key, and decryption. You own the browser integration. Onboarding:

Select Direct API and enable Samsung Pay in Lite Dashboard.
Provide your checkout URL, merchant display name, country, and required business details.
Lite checks channel eligibility, provisions or links the Lite-managed Samsung Pay service, and returns your Samsung Pay configuration.

Route 4: Merchant-owned service

You own the Samsung Developer Portal configuration. Lite still decrypts by default (Route 4A) and always processes the payment. Onboarding:

Select Direct API and merchant-owned Samsung Pay service in Lite Dashboard.
Get your CSR:
- Lite decrypts: download the Lite-generated CSR from Lite Dashboard.
- Merchant decrypts (approval required): generate your own key pair and CSR.
Create a Web Online Payment Service in Samsung Developer Portal.
Select Lite as the payment gateway where Lite is available in the Samsung portal for your market.
Add your website URL and the callback URLs Samsung requires.
Upload the CSR from step 2.
Save the Samsung Service ID in Lite Dashboard. Lite validates the configuration.
Complete Samsung staging and production approval.

Payment flow (Routes 3, 4A, and 4B)

Route 4B differs in one step: your backend decrypts the credential with your private key and sends Lite the Lite-defined authorization payload instead of the encrypted credential. Route 4B is not yet available for public implementation. Lite must approve your use of it and will provide the request schema, accepted fields, error model, and PCI DSS responsibilities.

Build the browser integration

This section applies to Direct API.

1. Load Samsung’s Web Checkout SDK

<script src="https://img.mpay.samsung.com/gsmpi/sdk/samsungpay_web_sdk.js"></script>

2. Define the payment methods

Define the supported payment methods and Samsung Pay API version in the paymentMethods object. The serviceId identifies the Samsung Pay service used for your integration. Use the Service ID and allowed card brands configured for your Lite channel, delivered from your backend. Do not hardcode them in browser code.

const paymentMethods = {
  version: "2",
  serviceId: "<samsung-service-id>",
  protocol: "PROTOCOL_3DS",
  allowedBrands: ["visa", "mastercard"],
};

3. Check availability before showing the button

Initialize the Samsung Pay client with the operation environment, then check availability with isReadyToPay().

const samsungPayClient = new SamsungPay.PaymentClient({
  environment: "STAGE",
});

const availability = await samsungPayClient.isReadyToPay(paymentMethods);

if (availability.result) {
  showSamsungPayButton();
}

Show the Samsung Pay button only when isReadyToPay() succeeds. Use the official Samsung Pay button asset, or the SDK’s createButton() method, and follow Samsung’s branding guidelines.

4. Create the transaction details

const transactionDetail = {
  orderNumber: "<order-number>",
  merchant: {
    name: "<merchant-name>",
    url: "<merchant-url>",
    id: "<merchant-id>",
    countryCode: "SA",
  },
  amount: {
    option: "FORMAT_TOTAL_ESTIMATED_AMOUNT",
    currency: "SAR",
    total: 300,
  },
};

Build transactionDetail from server-controlled order data. Do not trust amount, currency, or order values supplied by browser code.

5. Launch the payment sheet

Call loadPaymentSheet() when the customer clicks the Samsung Pay button. When the customer confirms the payment on their device, the promise resolves with the encrypted paymentCredential object.

const paymentCredential = await samsungPayClient.loadPaymentSheet(
  paymentMethods,
  transactionDetail,
);

Send the complete paymentCredential object to your backend, then to Lite for decryption and processing.

Send the complete paymentCredential Samsung’s generic documentation tells merchants to extract the 3DS.data field and pass it to their payment provider. Lite requires the complete paymentCredential object, which also includes the card brand, last four digits, and recurring-payment flag. Do not send only 3DS.data.

6. Notify Samsung of the payment result

After Lite processes the payment and returns a result, report the final status to Samsung with notify():

samsungPayClient.notify(paymentResult);

The paymentResult object contains the payment status and the payment gateway name. Map Lite’s payment result to Samsung’s status:

Samsung status	Use when
`CHARGED`	Lite confirmed the payment was charged.
`REJECTED`	The issuer or acquirer rejected the payment.
`CANCELED`	The customer, merchant, or Lite cancelled the payment.
`TIMEOUT`	Lite could not return a final result within the configured time.
`ERRED`	A technical error occurred.

Send CHARGED only after Lite confirms the charge. A payment credential from Samsung Wallet is not a charge.

Payment result and fulfillment

Samsung Wallet approval and Samsung’s Verified screen mean Samsung has created a payment credential. They do not mean Lite has charged the customer. Lite launches Samsung Pay with automatic capture. The sequence for fulfillment:

Lite processes the credential and confirms the payment was charged.
Samsung receives CHARGED through the result notification.
Lite sends you a payment-captured webhook.
You ship the order or provide the service.

Ship only after step 3. Never fulfill based on the Samsung Wallet approval screen, the browser result, or the immediate API response alone.

Testing

Samsung provides three Web Checkout environments:

Environment	Purpose
`STAGE`	Staging with real device authorization
`STAGE_WITHOUT_APK`	Staging simulation without device authorization
`PRODUCTION`	Live payments

Before going live, verify:

Samsung Pay is enabled for the Lite production channel and the Samsung Pay service is approved for production.
The Service ID matches the Samsung environment in use.
The button appears only after isReadyToPay() succeeds.
Desktop device binding works with both Samsung account email and QR code.
The complete payment credential reaches Lite without being logged.
Each outcome works end to end: charged, rejected, cancelled, timed out, and technical error, with the matching Samsung result notification.
Webhooks are signature-verified and duplicate events are ignored.
Fulfillment waits for the payment-captured webhook.
Refund and void operations work through Lite’s Payments API.

Security requirements

Create checkout sessions and payments from your backend. Keep Lite API keys out of browser code.
Use server-controlled order number, amount, currency, merchant name, and Service ID.
Use an idempotency key for payment creation and any retryable Lite operation.
Do not log payment credentials, encrypted JWE data, CSRs, private keys, or decrypted token data.
If you hold your own private key (Route 4B), store it in an HSM or a secure key-management service. Never upload a private key to Lite.
Verify Lite webhook signatures and ignore duplicate events.

​Terminology

​Choose an integration route

​What ownership controls

​Route 1: Hosted Checkout

​Onboarding

​Payment flow

​Merchant steps

​Route 2: Lite SDK

​Payment flow

​Merchant steps

​Direct API (Routes 3 and 4)

​Route 3: Lite-managed service

​Route 4: Merchant-owned service

​Payment flow (Routes 3, 4A, and 4B)

​Build the browser integration

​1. Load Samsung’s Web Checkout SDK

​2. Define the payment methods

​3. Check availability before showing the button

​4. Create the transaction details

​5. Launch the payment sheet

​6. Notify Samsung of the payment result

​Payment result and fulfillment

​Testing

​Security requirements

Terminology

Choose an integration route

What ownership controls

Route 1: Hosted Checkout

Onboarding

Payment flow

Merchant steps

Route 2: Lite SDK

Payment flow

Merchant steps

Direct API (Routes 3 and 4)

Route 3: Lite-managed service

Route 4: Merchant-owned service

Payment flow (Routes 3, 4A, and 4B)

Build the browser integration

1. Load Samsung’s Web Checkout SDK

2. Define the payment methods

3. Check availability before showing the button

4. Create the transaction details

5. Launch the payment sheet

6. Notify Samsung of the payment result

Payment result and fulfillment

Testing

Security requirements