> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lite.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Samsung pay

Samsung Pay on the web involves three separate decisions:

1. Where the customer checks out.
2. Who owns the Samsung Pay service.
3. 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

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

### Payment flow

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant M as Merchant backend
    participant H as Lite Hosted Checkout
    participant L as Lite
    participant S as Samsung Pay
    participant W as Samsung Wallet
    participant G as Acquirer or gateway

    M->>L: Create checkout session
    L-->>M: Return payment link
    M-->>C: Redirect to Lite Hosted Checkout

    C->>H: Open checkout page
    H->>S: Check Samsung Pay availability
    C->>H: Select Samsung Pay
    H->>S: Start Samsung Web Checkout
    S-->>C: Show device binding screen or QR code
    C->>W: Approve payment in Samsung Wallet
    W-->>S: Return payment credential
    S-->>H: Return encrypted payment credential

    H->>L: Send payment credential and checkout context
    L->>L: Decrypt credential
    L->>G: Authorize and capture payment
    G-->>L: Return payment result
    L-->>H: Return checkout result
    H->>S: Notify Samsung of payment result
    H-->>C: Show payment result

    L->>M: Send payment lifecycle webhook
```

### Merchant steps

1. Enable Samsung Pay for the Lite channel.
2. Create a Lite checkout session from your backend.
3. Redirect the customer to Lite Hosted Checkout.
4. 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

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant M as Merchant backend
    participant W as Merchant website
    participant SDK as Lite SDK
    participant L as Lite
    participant S as Samsung Pay
    participant SW as Samsung Wallet
    participant G as Acquirer or gateway

    M->>L: Create checkout session
    L-->>M: Return client-safe session data
    M-->>W: Return client-safe session data
    W->>SDK: Initialize and mount Lite SDK

    SDK->>S: Check Samsung Pay availability
    SDK->>SDK: Render Samsung Pay button
    C->>SDK: Select Samsung Pay
    SDK->>S: Start Samsung Web Checkout
    S-->>C: Show device binding screen or QR code
    C->>SW: Approve payment in Samsung Wallet
    SW-->>S: Return payment credential
    S-->>SDK: Return encrypted payment credential

    SDK->>L: Send payment credential and checkout context
    L->>L: Decrypt credential
    L->>G: Authorize and capture payment
    G-->>L: Return payment result
    L-->>SDK: Return checkout result
    SDK->>S: Notify Samsung of payment result
    SDK-->>C: Show payment result

    L->>M: Send payment lifecycle webhook
```

### Merchant steps

1. Enable Samsung Pay for the Lite channel.
2. Create a Lite checkout session from your backend.
3. Pass client-safe session data to the browser.
4. Initialize and mount Lite SDK, then handle its events.
5. 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:

1. Select Direct API and enable Samsung Pay in Lite Dashboard.
2. Provide your checkout URL, merchant display name, country, and required business details.
3. 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:

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

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

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant W as Merchant website
    participant M as Merchant backend
    participant S as Samsung Pay
    participant SW as Samsung Wallet
    participant L as Lite
    participant G as Acquirer or gateway

    M->>L: Create checkout session
    L-->>M: Return Samsung Pay configuration
    M-->>W: Return client-safe configuration

    W->>S: Load Web Checkout SDK
    W->>S: isReadyToPay(paymentMethods)
    S-->>W: Return availability
    W->>W: Render Samsung Pay button

    C->>W: Select Samsung Pay
    W->>S: loadPaymentSheet(paymentMethods, transactionDetail)
    S-->>C: Show device binding screen or QR code
    C->>SW: Approve payment in Samsung Wallet
    SW-->>S: Return payment credential
    S-->>W: Return encrypted paymentCredential

    W->>M: Send complete paymentCredential and session ID
    M->>L: Process Samsung Pay credential
    L->>L: Decrypt with Lite private key
    L->>G: Authorize and capture payment
    G-->>L: Return payment result
    L-->>M: Return immediate payment result
    M-->>W: Return Samsung result status
    W->>S: notify(paymentResult)

    W-->>C: Show checkout result
    L->>M: Send payment lifecycle webhook
```

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

```html theme={null}
<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.

```js theme={null}
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()`.

```js theme={null}
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

```js theme={null}
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.

```js theme={null}
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()`:

```js theme={null}
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:

1. Lite processes the credential and confirms the payment was charged.
2. Samsung receives `CHARGED` through the result notification.
3. Lite sends you a payment-captured webhook.
4. 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.