stripe

Configure the Stripe payment method in WEBSALE: required settings, related modules and integration steps for the Stripe checkout in the frontend.

Configurations

The following settings are relevant for configuring the Stripe payment method:

---

Modules

The following modules are relevant for integrating the Stripe payment method in the checkout process:

• $wsStripe - Stripe payment methods module
• $wsCheckout - Checkout state, addresses, shipping, payment, problems, totals
• $wsActions - Generate and evaluate actions
• $wsAccount - Login status, email, addresses, loadAddress()
• $wsViews - Current URL, destination pages, view URLs
• $wsBasket - Basket and order overview
• $wsConfig - Configuration values, for example salutations and currency

---

Actions

The following actions are relevant for the integration of the Stripe payment method:

---

Additionally relevant information

The following additional content must be integrated for the payment method.

Frontend integration

Stripe provides its own JavaScript SDK that must be embedded in the template. It handles the display of the payment fields and the communication with Stripe.

HTML structure
The following HTML block must be placed in the template:

• #wsStripePaymentElement is the container in which Stripe automatically embeds the payment fields (for example credit card number or PayPal button)
• The form submits the payment process when “Pay with Stripe” is clicked

<div id="wsStripePaymentElement">
    
</div>
<form method="post" action="{{= $wsViews.current.url() }}" id="wsCheckoutStripeConfirmForm">
    <input type="hidden" name="wsact" value="{{= $cActionCheckoutConfirm.id }}">
    <input type="hidden" name="wscsrf" value="{{= $cActionCheckoutConfirm.csrf }}">
    <input type="hidden" name="wstarget" value="{{= $wsViews.viewUrl('confirm.htm') }}">
    <button class="btn btn-success btn-block wsStripeOrderBtn" {{if not $wsCheckout.isValid}}disabled{{/if}}>
      Pay with Stripe
    </button>
</form>

JavaScript
The following script block must be inserted directly after the HTML block. It must be enclosed in {{ autoescape "js" }} so that template variables in the JavaScript context are processed correctly.

The flow in the script is as follows:

1. Initialize Stripe - The SDK is started with the credentials from $wsStripe.configuration
2. Display payment fields - Stripe renders the payment selection (credit card, PayPal and others) into the #wsStripePaymentElement container. The Stripe address input fields are disabled because the customer’s address is already known in the shop and is passed automatically.
3. Trigger payment - When the form is submitted, the entered payment data is sent to Stripe together with the billing address from $wsAccount. Stripe returns a confirmation token for this.
4. Send token to the shop - The token is transmitted to the shop, which uses it to start the actual payment process with Stripe.
5. Process result - If the payment fails, an error message is displayed. If an additional confirmation is required, for example 3D Secure, Stripe handles this automatically.
6. Redirect - After a successful payment, the customer is redirected to the order confirmation page.

<script src="https://js.stripe.com/basil/stripe.js"></script>
{{ autoescape "js" }}
<script>
    {{ var $stripeConfig = $wsStripe.configuration }}
    const stripe = Stripe("{{= $stripeConfig.publishableKey }}", {
        stripeAccount: "{{= $stripeConfig.targetAccount }}"
    });

    const appearance = {
        theme: 'stripe', // Appearance customizable, see Stripe Appearance API
    };

    const options = {
        mode: 'payment',
        amount: {{= $wsCheckout.getAmountInSmallestUnit($wsCheckout.sum.total) }},
        currency: '{{= lower($wsCheckout.sum.currency) }}',
        paymentMethodCreation: 'manual',
        appearance,
    };

    const elements = stripe.elements(options);

    // Disable Stripe address input fields – the address is
    // passed automatically below from $wsAccount when submitting
    const paymentElement = elements.create('payment', {
        fields: {
            billingDetails: {
                name: 'never',
                email: 'never',
                phone: 'never',
                address: {
                    line1: 'never',
                    line2: 'never',
                    city: 'never',
                    state: 'auto', // State is not present in our addresses
                    country: 'never',
                    postalCode: 'never'
                }
            }
        }
    });
    paymentElement.mount("#wsStripePaymentElement");

    document
        .querySelector("#wsCheckoutStripeConfirmForm")
        .addEventListener("submit", handleSubmit);

    async function handleSubmit(e) {
        e.preventDefault();
        setLoading(true);

        // Check whether the payment inputs are complete
        const {error: submitError} = await elements.submit();
        if (submitError) {
            showMessage(submitError.message);
            return;
        }

        // Send payment data + billing address to Stripe,
        // Stripe returns a confirmation token for this
        const {error, confirmationToken} = await stripe.createConfirmationToken({
            elements,
            params: {
                payment_method_data: {
                    billing_details: {
                        {{ foreach $addr in $wsAccount.addresses }}
                            {{if $addr.id==$wsCheckout.selectedBillAddress}}
                        address: {
                            city: "{{=$addr.city}}",
                            country: "{{=$addr.country}}",
                            line1: "{{=$addr.street}}",
                            line2: "",
                            postal_code: "{{=$addr.zip}}",
                        },
                        email: "{{ if $wsCheckout.guestMail }}{{= $wsCheckout.guestMail }}{{ else }}{{= $wsAccount.email }}{{ /if }}",
                        name: "{{=$addr.firstName}} {{=$addr.lastName}}",
                        phone: "{{= $addr.phone }}",
                            {{ /if }}
                        {{ /foreach }}
                    }
                }
            }
        });

        if (error) {
            showMessage(error.message);
            return;
        }

        // Send the confirmation token to the shop, which uses it to start the payment process
        var action = $('#wsCheckoutStripeConfirmForm').attr('action');
        var payload = $('#wsCheckoutStripeConfirmForm').serialize();
        payload += `&confirmationToken=${confirmationToken.id}`;

        const response = await fetch(action, {
            method: 'post',
            headers: {
                "Content-Type": "application/x-www-form-urlencoded",
            },
            body: payload
        });

        const dataContentType = response.headers.get("content-type");
        if (dataContentType && !dataContentType.includes("application/json")) {
            // Response is not JSON (e.g., if the terms and conditions were not accepted) – reload the page
            return;
        }

        const data = await response.json();
        const { success } = data;

        if (success === false) {
            // Payment declined – error details at: https://docs.stripe.com/testing#declined-payments
            const {error_code, decline_code} = data;
            showMessage(`Payment failed: ${error_code} ${decline_code}`);
            setLoading(false);
            return;
        }

        // If an additional confirmation is required (e.g., 3D Secure),
        // Stripe handles this automatically
        const { clientSecret, status } = data;
        if (status === "requires_action") {
            const { error } = await stripe.handleNextAction({ clientSecret });
            if (error) {
                showMessage(error.message);
                setLoading(false);
                return;
            }
        }

        setLoading(false);
        // Payment successful – redirect to the order confirmation
        window.location.href = "{{= $wsViews.viewUrl('confirm.htm', {wsPaymentStatus: 'refresh'}) }}";
    }

    // ------- UI helper functions -------

    function showMessage(messageText) {
        // TODO: display error message
    }

    function setLoading(isLoading) {
        let wsStripeOrderBtn = document.querySelectorAll(".wsStripeOrderBtn");
        wsStripeOrderBtn.forEach(btn => btn.disabled = isLoading);
        // TODO: show/hide loading indicator
    }
</script>
{{ /autoescape }}

Multi-page checkout: Google Pay and Apple Pay

The frontend integration described above assumes that the payment element is placed on the last page of the checkout, that is, on the order overview page.

In a checkout with multiple steps, it makes sense to load the widget already on the payment methods page so that the customer can enter their payment data directly when making the selection. This works for credit card and the other Stripe payment methods. Google Pay and Apple Pay behave differently and require a separate integration. The following section first explains why, and then shows how to integrate them.

Why wallets play a special role

For Stripe, Google Pay and Apple Pay are not separate payment methods; they are attached to the card payment method. As soon as card is allowed and the customer’s device supports a wallet, the payment element displays the wallet on its own. This results in three points that can cause problems in a multi-page checkout.

1. The wallet dialog completes the payment. If the customer clicks “Pay” in it, they authorize the payment immediately. If the widget is on the payment methods page, the customer has already paid before they have seen the order confirmation, selected the shipping method and accepted the terms and conditions.
2. The amount is fixed as soon as the widget is loaded. stripe.elements() receives the parameters amount and currency when called, and exactly this amount appears in the wallet dialog. If the total changes afterwards, for example due to a different shipping method or payment method costs, the dialog still shows the old amount. This can only be corrected with elements.update({ amount: ... }), and only before the dialog is opened.
3. The wallet dialog requires a direct user action. Browsers only open the Apple Pay and Google Pay dialog through a direct click. A preceding AJAX check, as is common on a payment methods page, consumes this user action and the dialog no longer opens.

With Google Pay and Apple Pay, the address from the wallet takes precedence over the billing_details passed by the template. This means that Stripe may show a different billing address than the shop. The shop still creates the order with the addresses selected in the checkout.

Recommended integration: widget on the order overview

The simplest approach is to leave the payment element where the integration intends it to be: on the order overview, that is, step 3 in the MultiPage Checkout. On the payment methods page, the customer only makes a selection; the widget is not loaded there. This eliminates all three points above, because the amount, shipping method and acceptance of the terms and conditions are fixed at this point.

If the widget should nevertheless be displayed earlier so that the customer can enter their payment data during the selection, the payment method must be determined before the widget is loaded. There are two variants for this. Both are based on creating separate payment methods in the shop with Stripe as the clearing service, and on the template tying the widget to the selected payment method. They differ in how far this split goes.

Variant 1: separate payment methods for Google Pay and Apple Pay

In this variant, only the two wallets are separated from each other. All other Stripe payment methods remain combined in one payment method as before.

Configuration

In the configuration service, create a separate payment method for Google Pay and one for Apple Pay under payment.payment and store Stripe as the clearing service under onlineClearing for both. Together with the existing Stripe payment method, three entries are then available for selection, for example with the identifiers stripe, googlePay and applePay.

This way, the shop knows from the payment methods page onwards which wallet the customer has selected. The template can refer to this in the further process.

Payment methods page

On the “Payment methods” page, load the payment element as usual, but disable the wallets there. The customer therefore only enters their card or other payment data there. No wallet dialog can open.

const paymentElement = elements.create('payment', {
    // Google Pay und Apple Pay auf dieser Seite nicht anbieten
    wallets: {
        applePay: 'never',
        googlePay: 'never'
    },
    fields: {
        billingDetails: {
            // wie in der Integration oben
        }
    }
});
paymentElement.mount("#wsStripePaymentElement");

If Google Pay or Apple Pay was selected as the payment method, no widget is loaded on this page at all. Instead, tie the output to the selected payment method:

{{ if $wsCheckout.selectedPayment == "stripe" }}
   {{# Payment Element ohne Wallets, siehe oben #}}
{{ /if }}

Order overview

On the order overview, the Express Checkout Element is displayed instead of the Payment Element for Google Pay and Apple Pay. The wallet button is displayed and the payment is only triggered once all details are fixed.

{{ if $wsCheckout.selectedPayment == "googlePay" or $wsCheckout.selectedPayment == "applePay" }}
   <div id="wsStripeExpressCheckoutElement"></div>
   <div id="wsStripeExpressCheckoutHint" style="display: none;">
      {{# Hinweis, falls das Gerät das Wallet nicht unterstützt #}}
   </div>
{{ else }}
   <div id="wsStripePaymentElement"></div>
{{ /if }}

The Express Checkout Element is attached to the same elements instance as the Payment Element. With allowedPaymentMethodTypes: ['card'], only the two wallets remain. With paymentMethods, the wallet that was not selected is hidden.

const options = {
    mode: 'payment',
    amount: {{= $wsCheckout.getAmountInSmallestUnit($wsCheckout.sum.total) }},
    currency: '{{= lower($wsCheckout.sum.currency) }}',
    paymentMethodCreation: 'manual',
    // Apple Pay und Google Pay hängen an der Zahlungsart "card"
    allowedPaymentMethodTypes: ['card'],
    appearance,
};
const elements = stripe.elements(options);

const expressCheckoutElement = elements.create('expressCheckout', {
    // nur das Wallet anzeigen, das der Kunde gewählt hat
    paymentMethods: {
        applePay: '{{ if $wsCheckout.selectedPayment == "applePay" }}auto{{ else }}never{{ /if }}',
        googlePay: '{{ if $wsCheckout.selectedPayment == "googlePay" }}auto{{ else }}never{{ /if }}'
    },
    // Wallets geben die E-Mail-Adresse sonst nicht heraus
    emailRequired: true
});

// Unterstützt das Gerät kein Wallet, bleibt sonst eine leere Fläche stehen
expressCheckoutElement.on('availablepaymentmethodschange', ({ paymentMethods }) => {
    if (!paymentMethods) {
        document.querySelector("#wsStripeExpressCheckoutHint").style.display = "block";
    }
});

expressCheckoutElement.on('confirm', async (event) => {
    const {error: submitError} = await elements.submit();
    if (submitError) {
        showMessage(submitError.message);
        return;
    }

    const {error, confirmationToken} = await stripe.createConfirmationToken({
        elements,
        params: {
            // Rechnungsadresse wie in der Integration oben mitgeben
        }
    });

    if (error) {
        showMessage(error.message);
        return;
    }

    // Ab hier identisch zur Integration oben: Confirmation Token an den Shop
    // schicken, Antwort auswerten und auf die Bestellbestätigung weiterleiten
});

expressCheckoutElement.mount("#wsStripeExpressCheckoutElement");

Variant 2: create each Stripe payment method individually

This variant goes one step further. Instead of only separating the wallets, you create each Stripe payment method once in the shop, for example credit card, SEPA direct debit, Klarna and PayPal, each with Stripe as the clearing service. The customer thus selects the specific payment method on the payment methods page, and the widget only loads that one.

This is controlled via allowedPaymentMethodTypes. The option accepts the Stripe identifiers of the payment methods, for example card, sepa_debit, klarna or paypal. The template sets the matching identifier for the selected payment method:

{{ if $wsCheckout.selectedPayment == "stripeCard" }}{{ var $stripeType = "card" }}{{ /if }}
{{ if $wsCheckout.selectedPayment == "stripeSepa" }}{{ var $stripeType = "sepa_debit" }}{{ /if }}
{{ if $wsCheckout.selectedPayment == "stripeKlarna" }}{{ var $stripeType = "klarna" }}{{ /if }}

const options = {
    mode: 'payment',
    amount: {{= $wsCheckout.getAmountInSmallestUnit($wsCheckout.sum.total) }},
    currency: '{{= lower($wsCheckout.sum.currency) }}',
    paymentMethodCreation: 'manual',
    // nur die Zahlungsart laden, die der Kunde gewählt hat
    allowedPaymentMethodTypes: ['{{= $stripeType }}'],
    appearance,
};
const elements = stripe.elements(options);

The same applies to Google Pay and Apple Pay as in variant 1: both are attached to card, receive allowedPaymentMethodTypes: ['card'] and are shown and hidden via wallets or paymentMethods. The integration on the payment methods page and the order overview is identical to variant 1.

Which variant makes sense when

Variant 1 is the smaller change. It is worthwhile if the shop continues to offer the Stripe widget as one payment method and only wants to solve the problem with the wallets.

Variant 2 is worthwhile if the customer should already see the specific payment method in the shop’s payment method selection instead of selecting it in the Stripe widget. However, the configuration effort is higher, because each payment method must be created and maintained individually.

Check before going live

• Register the domain. Google Pay and Apple Pay only appear on domains that are registered with Stripe as a payment method domain, separately for test mode and live mode.
• HTTPS. The Express Checkout Element works with an iframe and requires delivery via https://.
• Amount in the wallet dialog. Compare the amount in the Apple Pay or Google Pay dialog with the order total, especially if the shipping method or payment method costs change the total.
• Devices without a wallet. Test the case where the wallet is not available, and make sure that the customer can then select a different payment method.
• Billing address. Check in the Stripe dashboard which address arrives with the payment if the wallet provides its own address.

---

Further links

• General documentation for the Stripe frontend: https://docs.stripe.com/js
• Express Checkout Element (Google Pay and Apple Pay): https://docs.stripe.com/elements/express-checkout-element
• Registering a domain for wallets: https://docs.stripe.com/payments/payment-methods/pmd-registration
• MultiPage Checkout