JavaScript methods

The Samsung Pay Web Checkout SDK exposes the following methods, which you can use to initiate and manage the checkout flow:

• isReadyToPay()
• loadPaymentSheet()
• notify()

isReadyToPay()

The isReadyToPay() method performs a series of checks to determine whether the Samsung Pay button should be displayed. It verifies device and platform compatibility, checks supported card brands, and, when used on a mobile website, detects whether the customer is using a Samsung device.

Syntax

isReadyToPay(paymentMethods)

Parameters

Field	Type	Required/Optional	Description
paymentMethods	Object	Required	Information used to verify device and browser compatibility with Samsung Pay. For details, see PaymentMethods.

Return value

Resolves to the Promise object that indicates whether Samsung Pay is supported. The object contains the following fields:

Field	Type	Required/Optional	Description
result	Boolean	Required	Whether the device supports Samsung Pay.
resultMessage	String	Optional	Message that explains the compatibility verification result; for example, "Invalid allowedBrands" or "Not supported device".

Example

const paymentMethods = {
  version: "2",
  serviceId: "dcc1cbb25d6a470bb42926",
  protocol: "PROTOCOL_3DS",
  allowedBrands: ["visa", "mastercard"]
};

paymentClient.isReadyToPay(paymentMethods)
  .then(response => {
    if (response.result) {
      console.log("Device is ready to pay with Samsung Pay.");
      // Proceed to load the payment sheet
    } else {
      console.error("Device is not ready:", response.resultMessage);
      // Hide Samsung Pay button or show an alternative payment method
    }
  })
  .catch(error => {
    console.error("Error checking readiness:", error);
  });

loadPaymentSheet()

The loadPaymentSheet() method initiates the Samsung Pay checkout flow. It detects the customer’s context (desktop browser, mobile browser, or Android WebView), displays the appropriate UI for payment authentication, and then returns the generated payment credentials.

Syntax

loadPaymentSheet(paymentMethods, transactionDetail, modalOptions)

Parameters

Field	Type	Required/Optional	Description
paymentMethods	Object	Required	Service-level configurations for the payment request. For details, see PaymentMethods.
transactionDetail	Object	Required	Transaction details for the purchase. For details, see TransactionDetail.
modalOptions	Object	Optional	Modal layout settings when the payment sheet is displayed on the desktop. If omitted, default values are used. For details, see ModalOptions.

Return value

• onSuccess: Resolves with the payment data returned from Samsung Pay. The data includes encrypted payment credentials, and other relevant information required for payment processing.
• onFailure: Rejects with an error object or message:
  • "user_cancel", "payment_error", "payment_timeout", "exceeded_retry_limit", "app_update_required"
  • "FAIL": Indicates a failure during the payment process with a message.

Example

const paymentMethods = {
  version: "2.0",
  serviceId: "your_service_id",
  protocol: "PROTOCOL_3DS",
  allowedBrands: ["visa", "mastercard"]
};

const transactionDetail = {
  orderNumber: "ORD12345",
  merchant: {
    name: "My Awesome Store",
    url: "https://myawesomestore.com",
    countryCode: "US"
},
  amount: {
    option: "FORMAT_TOTAL_PRICE_ONLY",
    currency: "USD", 
    total: "10.99"
  }
};

const modalOptions = {
  margin: {
    top: "10%",
    left: "auto",
    bottom: "10%",
    right: "auto"
  }
};

paymentClient.loadPaymentSheet(paymentMethod, transactionDetail, modalOptions)
  .then(paymentData => {
    console.log("Payment successful!", paymentData);
    // Send paymentData to your server to process with your payment gateway
  })
  .catch(error => {
    console.error("Payment failed or was cancelled:", error);
    // Handle the error (e.g., show a message to the customer)
  });

notify()

The notify() method informs the Samsung server of the payment status after the payment has processed through the payment gateway.

Syntax

notify(paymentResult)

Parameters

Field	Type	Required/Optional	Description
paymentResult	Object	Required	Status of the payment after the payment gateway has processed it. For details, see PaymentResult.

Return value

None

Example

const paymentResult = {
    "status": "CHARGED",
    "provider": "PG Name"
}
samsungPayClient.notify(paymentResult);