Request payment from the customer

Use the following steps to integrate W3C Payment Request into your website.

Step 1: Confirm browser support

Run a feature detection check to confirm that the browser in use supports the W3C Payment Request API. If support is not available, fall back to your existing checkout flow so that the customer can still complete their purchase.

if (window.PaymentRequest) {
    // Use Payment Request API
} else {
    // Fall back to traditional checkout
    window.location.href = ‘/checkout/traditional’;
}

Step 2: Create the PaymentRequest object

Create a PaymentRequest object by calling the PaymentRequest constructor. The constructor accepts the following parameters:

• methodData: List of payment methods supported by your website (for example, Samsung Pay, Visa, and Mastercard)
• details: Transaction details of the purchase, such as the total amount, taxes, and fees
• options: Optional parameters used to collect additional customer information, such as shipping address or payer contact details

var request = new PaymentRequest(
    methodData, // Required payment method data
    details, // Required information about transaction
    options // Optional parameters for shipping etc.
);

Step 3: Configure supported payment methods

The methodData parameter defines the set of payment methods your website supports. To enable Samsung Pay, you must include it as a supported payment method within this parameter.

How you configure methodData determines which payment experience (standard or branded) is presented. To implement the branded Samsung Pay model, Samsung Pay must be specified as the only supported payment method. If additional payment methods are included, the standard W3C model is used.

The methodData parameter supports the following fields:

Field	Type	Required/Optional	Description
supportedMethods	string[]	Required	Specifies the payment methods supported by the website. To support Samsung Pay, use https://spay.samsung.com. If you are using the standard payment experience, you can include basic-card to support credit and debit cards saved in the browser. When basic-card is used, card details are returned directly from the browser to the website. Before enabling this method, ensure that your website and payment gateway (PG) can securely handle generic card data and meet applicable PCI compliance requirements.
data	object	Required	Samsung Pay–specific parameters.
data.version	string	Required	Data structure version. Always set to 1.
data.productID	string	Required	Unique service ID created during onboarding with Samsung.
data.merchantGatewayParameter	object	Conditional	User ID registered with the payment gateway. The user ID is required for the gateway token mode and for mada brand tokens. The maximum user ID length is 15 characters for mada token brands.
data.paymentProtocol	string	Optional	Payment protocol used for the transaction. The default (and only supported) value is PROTOCOL_3DS.
data.allowedCardNetworks	string[]	Required	Card networks accepted by the merchant and supported by the payment gateway.
data.merchantName	string	Required	Merchant name displayed on the payment sheet. Must exactly match the name registered in the Samsung Pay Portal.
data.orderNumber	string	Optional	Merchant-defined external reference identifier for the transaction.
data.isRecurring	boolean	Optional	Whether the transaction is a recurring payment. The default value is false.
data.billingAddressRequired	boolean	Optional	Whether the customer is required to provide a billing address. The default value is false.

The following examples show how to construct the methodData parameter for each token mode:

• Network token mode

  var methodData = [
      {
          supportedMethods: ['https://spay.samsung.com'],
          data: {
              'version': '1', // Always 1 until further notice
              'productId': '2bc3e6da781e4e458b18bc', // Service ID from portal 
              'allowedCardNetworks': ['mastercard', 'visa'],
              'merchantName': 'Shop Samsung (demo)',
              // merchantName must be identical to merchant name on portal 
              'orderNumber': '1233123',
          }
      }]
  

• Gateway token mode

  var methodData = [
      {
          supportedMethods: ['https://spay.samsung.com'],
          data: {
              'version': '1', // Always 1 until further notice
              'productId': '7qr7h9ws1872bc3e6da781', // Service ID from portal 
              'merchantGatewayParameter': { "userId": "acct_ 17irF7F6yPzJ7wOR" },
              'allowedCardNetworks': ['mastercard', 'visa'],
              'merchantName': 'Shop Samsung (demo)',
              //merchantName must be identical with merchant name on portal 
              'orderNumber': '1233123',
          }
      }]
  

Step 4: Define transaction details

The details parameter defines the transaction information presented to the customer during checkout. It includes the total amount to be charged and, optionally, a breakdown of how that total is calculated. This parameter is intended to summarize the key components of the order, such as its subtotal, discounts, taxes, and shipping costs, rather than represent an exhaustive line-item invoice.

The details parameter supports the following fields:

Field	Type	Required/Optional	Description
total	object	Required	Final amount and currency to be charged to the customer.
displayItems	object[]	Optional	Breakdown of the components used to calculate the total amount, such as subtotal, discounts, taxes, and shipping costs.

For a complete list of supported fields and formats, refer to the W3C Payment Request API specification.

var details = {
    displayItems: [
        {
            label: "Total of all items",
            amount: { currency: "USD", value: "65.00" }, // US$65.00
        },
        {
            label: "Friends & family discount",
            amount: { currency: "USD", value: "-10.00" }, // -US$10.00 
            pending: true // The price is not yet determined
        }
    ],
    total: {
        label: "Total",
        amount: { currency: "USD", value: "55.00" }, // US$55.00
    }
}

Step 5: Configure payment request options

The options parameter is optional and allows you to request additional information from the customer as part of the payment flow. Depending on your requirements, this may include shipping address information for physical goods or contact details for guest customers. When specified, these options determine which fields the browser prompts the customer to provide during checkout.

The options parameter supports the following fields:

Field	Type	Required/Optional	Description
requestPayerName	boolean	Optional	Whether the payer’s name is requested.
requestPayerEmail	boolean	Optional	Whether the payer’s email address is requested.
requestPayerPhone	boolean	Optional	Whether the payer’s phone number is requested.
requestShipping	boolean	Optional	Whether a shipping address is requested.
shippingType	string	Optional	Label shown to the customer for the shipping address. Supported values are shipping, pickup, and delivery. This value is for display purposes only.

var options = {
    requestPayerEmail: false,
    requestPayerName: true,
    requestPayerPhone: false,
    requestShipping: true,
    shippingType: "delivery"
}

Step 6: Check payment method availability

If you call the show() method when none of the payment methods specified in the payment request are available on the device, the returned promise is rejected with the following error:

DOMException: The payment method is not supported

To avoid this scenario, check in advance whether the customer has an available payment method that can fulfill the current payment request. Use the canMakePayment() method to determine whether at least one of your supported payment methods is available on the customer's device before calling show().

const paymentRequest = new PaymentRequest(supportedPaymentMethods, transactionDetails, options);

// If canMakePayment() isn’t available, default to assume the method is supported
const canMakePaymentPromise = Promise.resolve(true);

// Feature detect canMakePayment()
if (request.canMakePayment) {
    canMakePaymentPromise = paymentRequest.canMakePayment();
}

canMakePaymentPromise.then((result) => {
    if (!result) {
        // The customer does not have a supported payment method
        // TODO: Redirect to traditional checkout flow
        return;
    }
    // TODO: The customer has a payment - call show()
})
    .catch((err) => {
        // TODO: Either fall back to traditional checkout or call show()
    });

Step 7: Display the payment sheet

Call the show() method to display the payment sheet. This method invokes the browser’s native UI, allowing the customer to review the purchase details, update information if needed, and confirm the payment. The method returns a promise that resolves when the customer completes or cancels the payment request.

request.show().then(function (paymentResponse) {
    // Process paymentResponse here 
    paymentResponse.complete("success");
}).catch(function (err) {
    console.error("Uh oh, something bad happened", err.message);
});

To handle the payment response, see Process the payment data.