Samsung Pay for web
Beta

Last updated: October 6, 2026

Accept Samsung Pay payments on your website with Flow, 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.

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

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.

Create a public key and a secret key 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, configure your webhook server.

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


1connect-src, https://*.checkout.com
2frame-src, https://*.checkout.com
3script-src, https://*.checkout.com
4img-src, https://*.checkout.com

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

When the customer is ready to pay, call the Create a Payment Session 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.
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.

post

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


1{
2  "amount": 6540,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "display_name": "Online shop",
6  "billing": {
7    "address": {
8      "country": "GB"
9    }
10  },
11  "customer": {
12    "name": "Jia Tsang",
13    "email": "jia.tsang@example.com"
14  },
15  "success_url": "https://example.com/payments/success",
16  "failure_url": "https://example.com/payments/failure"
17}


1{
2  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
4  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
5  "_links": {
6    "self": {
7      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

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.

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


1npm install @checkout.com/checkout-web-components --save

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


1<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.


1// Insert your public key here
2const publicKey = 'pk_sbox_o2nulev4vbo43i4qkb5p7lfijap';
3
4const checkout = await CheckoutWebComponents({
5  paymentSession,
6  publicKey,
7  environment: 'sandbox',
8});

For the full list of options, see the Flow library reference.

Use CheckoutWebComponents to create a samsungpay object.


1const samsungpayComponent = checkout.create("samsungpay");

Mount Flow to the website using the mount() method. The method takes an Element selector or an Element as an argument. For example, #flow-container or document.getElementById(#flow-container), respectively.


1if (await samsungpayComponent.isAvailable()) {
2  samsungpayComponent.mount('#samsungpay-container');
3}


1const samsungpayElement = document.getElementById('samsungpay-container');
2
3if (await samsungpayComponent.isAvailable()) {
4  samsungpayComponent.mount(samsungpayElement);
5}

Note

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

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.

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 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:


1const publicKey = 'pk_sbox_o2nulev4vbo43i4qkb5p7lfijap';
2
3const checkout = await CheckoutWebComponents({
4  paymentSession,
5  publicKey,
6  environment: 'sandbox',
7
8  onPaymentCompleted: async (_self, paymentResponse) => {
9    // Handle synchronous payments
10    await handlePayment(paymentResponse.id);
11  },
12});

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:

Sign in to the Dashboard.
Go to Payments > Processing > All payments.
Select the test payment to view its details.

Customize your Flow integration

Learn how to customize your Flow integration.

Flow library reference

See the configuration options and error handling steps for Flow.

Samsung Pay for web
Beta

How it works

Before you start

Content Security Policy

Create a new Payment Session
Server side

Information

Request example

Response example

Initialize and mount Flow
Client side

Note

Note

Use Flow in a WebView

Handle the payment response
Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

How it works

Before you start

Content Security Policy

Create a new Payment Session Server side

Information

Request example

Response example

Initialize and mount Flow Client side

Note

Note

Use Flow in a WebView

Handle the payment response Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Create a new Payment Session
Server side

Initialize and mount Flow
Client side

Handle the payment response
Client side