# Samsung Pay for web

Accept Samsung Pay payments on your website with [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website.md), our pre-built, customizable payment user interface.

Flow lets you accept payments using Checkout.com's global network of payment methods with a single integration.

To enable payments on your website, set up your client-side and server-side configuration.

---

## How it works

1. The customer lands on the checkout page.
2. You perform a server-side request to create a payment session.
3. You use the payment session data on the client side to mount Flow.
4. Flow checks whether Samsung Pay is available on the customer's device, and displays the Samsung Pay button only if it is.
5. When the customer selects the Samsung Pay button, Flow opens the Samsung Pay payment screen with the amount and currency from the payment session.
6. Samsung returns the encrypted payment credential, and Flow submits the payment request.
7. Flow notifies Samsung of the payment result.
8. You receive a webhook notifying you of the payment status.

---

## Before you start

To offer Samsung Pay with Flow, contact your account manager to enable Samsung Pay on your account, and to get your Checkout.com entity ID.

You also need a Checkout.com [test account](https://www.checkout.com/get-test-account).

Create a [public key and a secret key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md) in the Dashboard, with the following key scopes:

- Public key – `payment-sessions:pay` and `vault-tokenization`
- Secret key – `payment-sessions`

To receive webhooks for the [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway), [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).

### Content Security Policy

If you have a Content Security Policy (CSP) on your website, Checkout.com requires the following directives:

```
connect-src, https://*.checkout.com
frame-src, https://*.checkout.com
script-src, https://*.checkout.com
img-src, https://*.checkout.com
```

Samsung's Web Checkout SDK loads from `https://img.mpay.samsung.com`. Allow this domain in your `script-src` directive.

---

## Create a new Payment Session `Server side`

When the customer is ready to pay, call the [Create a Payment Session](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) endpoint to securely create a `PaymentSession` object.
The `PaymentSession` contains the information required to handle all steps of the payment flow.

In your request:

- Provide the `amount` in the minor currency unit. Flow converts it to the major-unit format Samsung requires. For example, `6540` becomes `65.40`.
- Set `currency` to the selected country's [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md).
- Provide the `success_url` and `failure_url`.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payment-sessions`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payment-sessions`

### Request example

```json
{
  "amount": 6540,
  "currency": "GBP",
  "reference": "ORD-123A",
  "display_name": "Online shop",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Jia Tsang",
    "email": "jia.tsang@example.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
    }
  }
}
```

If Samsung Pay is enabled on your account, the payment session includes the Samsung Pay configuration that Flow needs. This configuration covers your merchant details, the supported card networks, and the order information.

---

## Initialize and mount Flow `Client side`

You can install the `@checkout.com/checkout-web-components` package via npm:

```bash
npm install @checkout.com/checkout-web-components --save
```

Alternatively, you can load the package directly via a script:

```html
<script src="https://checkout-web-components.checkout.com/index.js" />
```

> **Note**
>
> To remain PCI compliant, always load the script directly from `https://checkout-web-components.checkout.com`. Do not download or host the script yourself, or include it in a bundle.

The client side initializes an instance of `CheckoutWebComponents` with configuration information and the payment session data retrieved when you created the payment session.

```javascript
// Insert your public key here
const publicKey = 'pk_sbox_o2nulev4vbo43i4qkb5p7lfijap';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',
});
```

For the full list of options, see the [Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md#Initialization).

Use `CheckoutWebComponents` to create a `samsungpay` object.

```javascript
const samsungpayComponent = checkout.create("samsungpay");
```

Mount Flow to the website using the `mount()` method. The method takes an [Element selector](https://developer.mozilla.org/en-US/docs/Web/API/Element) or an [Element](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors) as an argument. For example, `#flow-container` or `document.getElementById(#flow-container)`, respectively.

**Mount Flow to a Selector**

```javascript
if (await samsungpayComponent.isAvailable()) {
  samsungpayComponent.mount('#samsungpay-container');
}
```

**Mount Flow to an Element**

```javascript
const samsungpayElement = document.getElementById('samsungpay-container');

if (await samsungpayComponent.isAvailable()) {
  samsungpayComponent.mount(samsungpayElement);
}
```

> **Note**
>
> You cannot embed Flow within an iframe or onto a Shadow DOM.

### Use Flow in a WebView

If you integrate Flow within a WebView, make sure your WebView:

- Enables JavaScript.
- Enables DOM storage.
- Intercepts Samsung-specific deep links, such as `samsungpay://`, and launches them using the platform's native intent mechanism.

---

## Handle the payment response `Client side`

Samsung Pay is a synchronous payment method. The customer approves the payment in the Samsung Pay payment screen, and Flow returns the result without redirecting the customer.

The `onPaymentCompleted` event triggers when a payment is successfully completed. You can use the event data to notify the customer of the payment status.

If you've configured your webhook server, we also send a [Gateway](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway) webhook to your server. Wait for the webhook callback before you start your order fulfillment process. The `PaymentSession` ID is returned in the webhook payload's `data.metadata.cko_payment_session_id` field.

Add the event handler to the Flow initialization code:

```javascript
const publicKey = 'pk_sbox_o2nulev4vbo43i4qkb5p7lfijap';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',

  onPaymentCompleted: async (_self, paymentResponse) => {
    // Handle synchronous payments
    await handlePayment(paymentResponse.id);
  },
});
```

---

## Test the integration

Before you test, make sure you've registered your domain with Samsung and that Samsung Pay is enabled on your account.

Test that Samsung Pay appears in your checkout and that you can complete a payment. Then check the status of the payment:

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Payments_ > _Processing_ > _All payments_.
3. Select the test payment to view its details.

---

## Next steps

**[Customize your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md)**

Learn how to customize your Flow integration.

**[Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference.md)**

See the configuration options and error handling steps for Flow.