stripe

Zahlungsart Stripe im Checkout einrichten: relevante Konfigurationen, Module wie $wsStripe und$wsCheckout sowie Aktionen für den Bestellprozess.

​

Konfigurationen

Folgende Einstellungen sind relevant für die Konfiguration der Zahlungsart stripe:

---

​

Module

Folgende Module sind relevant für die Integration der Zahlungsart stripe im Bestellprozess:

• $wsStripe - stripe-Zahlungsarten Modul
• $wsCheckout - Checkout-Zustand, Adressen, Versand, Zahlung, Probleme, Summen
• $wsActions - Aktionen erzeugen und auswerten
• $wsAccount - Login-Status, E-Mail, Adressen, loadAddress()
• $wsViews - Aktuelle URL, Zielseiten, View-URLs
• $wsBasket - Warenkorb und Bestellübersicht
• $wsConfig - Konfigurationswerte, zum Beispiel Anreden und Währung

---

​

Aktionen

Folgende Aktionen sind relevant für die Integration der Zahlungsart stripe:

---

​

Zusätzliche relevante Informationen

Folgende zusätzlichen Inhalte müssen für die Zahlungsart integriert werden.

​

Frontend-Integration

Stripe stellt ein eigenes JavaScript-SDK bereit, das in das Template eingebunden werden muss. Es übernimmt die Darstellung der Zahlungsfelder und die Kommunikation mit Stripe.

HTML-Struktur
Folgender HTML-Block muss im Template plaziert werden:

• #wsStripePaymentElement ist der Container, in den Stripe die Zahlungsfelder (beispielsweise Kreditkartennummer oder PayPal-Button) automatisch einbettet
• Das Formular sendet beim Klick auf “Mit Stripe bezahlen” den Bezahlvorgang ab

<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}}>
      Mit Stripe bezahlen
    </button>
</form>

JavaScript
Der folgende Script-Block muss direkt nach dem HTML-Block eingefügt werden. Er muss in {{ autoescape “js” }} eingeschlossen sein, damit Template-Variablen im JavaScript-Kontext korrekt verarbeitet werden.

Der Ablauf im Script ist folgender:

1. Stripe initialisieren - Das SDK wird mit den Zugangsdaten aus $wsStripe.configuration gestartet
2. Zahlungsfelder anzeigen - Stripe rendert die Zahlungsauswahl (Kreditkarte, PayPal und weitere) in den #wsStripePaymentElement-Container. Die Adresseingabefelder von Stripe werden dabei deaktiviert, weil die Adresse des Kunden bereits im Shop bekannt ist und automatisch übergeben wird.
3. Bezahlung auslösen - Beim Absenden des Formulars werden die eingegebenen Zahlungsdaten zusammen mit der Rechnungsadresse aus $wsAccount an Stripe geschickt. Stripe gibt dafür ein Confirmation-Token zurück.
4. Token an den Shop senden - Das Token wird an den Shop übermittelt, der damit den eigentlichen Zahlungsvorgang bei Stripe startet.
5. Ergebnis verarbeiten - Schlägt die Zahlung fehl, wird eine Fehlermeldung angezeigt. Ist eine zusätzliche Bestätigung nötig, beispielsweise 3D Secure, übernimmt Stripe das automatisch.
6. Weiterleitung - Nach erfolgreicher Zahlung wird der Kunde zur Bestellbestätigungsseite weitergeleitet.

<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', // Aussehen anpassbar, siehe 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);

    // Adresseingabefelder von Stripe deaktivieren – die Adresse wird
    // weiter unten beim Absenden automatisch aus $wsAccount übergeben
    const paymentElement = elements.create('payment', {
        fields: {
            billingDetails: {
                name: 'never',
                email: 'never',
                phone: 'never',
                address: {
                    line1: 'never',
                    line2: 'never',
                    city: 'never',
                    state: 'auto', // Bundesland ist in unseren Adressen nicht vorhanden
                    country: 'never',
                    postalCode: 'never'
                }
            }
        }
    });
    paymentElement.mount("#wsStripePaymentElement");

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

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

        // Prüfen ob die Zahlungseingaben vollständig sind
        const {error: submitError} = await elements.submit();
        if (submitError) {
            showMessage(submitError.message);
            return;
        }

        // Zahlungsdaten + Rechnungsadresse an Stripe schicken,
        // Stripe gibt dafür ein Confirmation Token zurück
        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;
        }

        // Confirmation Token an den Shop schicken, der startet damit den Zahlungsvorgang
        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")) {
            // Antwort ist kein JSON (z.B. wenn AGB nicht akzeptiert wurden) – Seite neu laden
            return;
        }

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

        if (success === false) {
            // Zahlung abgelehnt – Fehlerdetails unter: https://docs.stripe.com/testing#declined-payments
            const {error_code, decline_code} = data;
            showMessage(`Zahlung fehlgeschlagen: ${error_code} ${decline_code}`);
            setLoading(false);
            return;
        }

        // Falls eine zusätzliche Bestätigung nötig ist (z.B. 3D Secure),
        // übernimmt Stripe das automatisch
        const { clientSecret, status } = data;
        if (status === "requires_action") {
            const { error } = await stripe.handleNextAction({ clientSecret });
            if (error) {
                showMessage(error.message);
                setLoading(false);
                return;
            }
        }

        setLoading(false);
        // Zahlung erfolgreich – zur Bestellbestätigung weiterleiten
        window.location.href = "{{= $wsViews.viewUrl('confirm.htm', {wsPaymentStatus: 'refresh'}) }}";
    }

    // ------- UI-Hilfsfunktionen -------

    function showMessage(messageText) {
        // TODO: Fehlermeldung anzeigen
    }

    function setLoading(isLoading) {
        let wsStripeOrderBtn = document.querySelectorAll(".wsStripeOrderBtn");
        wsStripeOrderBtn.forEach(btn => btn.disabled = isLoading);
        // TODO: Lade-Indikator ein-/ausblenden
    }
</script>
{{ /autoescape }}

​

Mehrseitiger Bestellablauf: Google Pay und Apple Pay

Bei der oben beschriebenen Frontend-Integration wird davon ausgegangen, dass das Payment-Element auf der letzten Seite des Bestellablaufs, also auf der Seite der Bestellübersicht, steht.

Bei einem Bestellablauf mit mehreren Schritten ist es sinnvoll, das Widget bereits auf der Seite mit den Zahlungsarten zu laden, damit der Kunde seine Zahlungsdaten direkt bei der Auswahl eingeben kann. Das funktioniert für Kreditkarte und die übrigen Stripe-Zahlungsarten. Google Pay und Apple Pay verhalten sich anders und benötigen eine eigene Integration. Der folgende Abschnitt erklärt zunächst, woran das liegt, und zeigt anschließend den Einbau.

​

Warum Wallets eine Sonderrolle haben

Für Stripe sind Google Pay und Apple Pay keine eigenen Zahlungsarten, sondern sie hängen an der Zahlungsart card. Sobald card erlaubt ist und das Gerät des Kunden ein Wallet unterstützt, blendet das Payment-Element das Wallet von sich aus ein. Daraus ergeben sich drei Punkte, die in einem mehrseitigen Bestellablauf zu Problemen führen können.

1. Der Wallet-Dialog schließt die Zahlung ab. Klickt der Kunde darin auf “Bezahlen”, autorisiert er die Zahlung sofort. Steht das Widget auf der Seite mit den Zahlungsarten, hat der Kunde bereits bezahlt, bevor er die Bestellbestätigung gesehen, die Versandart gewählt und die AGB bestätigt hat.
2. Der Betrag steht fest, sobald das Widget geladen ist. stripe.elements() erhält beim Aufruf die Parameter amount und currency und genau dieser Betrag erscheint im Wallet-Dialog. Ändert sich die Summe danach noch, beispielsweise durch eine andere Versandart oder Kosten der Zahlungsart, zeigt der Dialog weiterhin den alten Betrag an. Das lässt sich nur mit elements.update({ amount: ... }) korrigieren, und zwar bevor der Dialog geöffnet wird.
3. Der Wallet-Dialog erfordert eine unmittelbare Nutzeraktion. Browser öffnen den Apple-Pay- und Google-Pay-Dialog nur durch direkten Klick. Eine vorgeschaltete AJAX-Prüfung, wie sie auf einer Seite mit Zahlungsarten üblich ist, kostet diese Nutzeraktion und der Dialog öffnet sich nicht mehr.

Die Adresse aus dem Wallet hat bei Google Pay und Apple Pay Vorrang vor den billing_details, die das Template mitgibt. Deshalb kann bei Stripe eine andere Rechnungsadresse stehen als im Shop. Die Bestellung wird vom Shop weiterhin mit den im Checkout gewählten Adressen angelegt.

​

Empfohlener Einbau: Widget auf der Bestellübersicht

Am einfachsten ist es, das Payment-Element dort zu belassen, wo die Integration es vorsieht: auf der Bestellübersicht, also Schritt 3 im MultiPage Checkout. Auf der Zahlungsarten-Seite wählt der Kunde nur aus, das Widget wird dort nicht geladen. Damit fallen alle drei Punkte oben weg, weil Betrag, Versandart und AGB-Bestätigung zu diesem Zeitpunkt feststehen.

Wenn das Widget trotzdem früher angezeigt werden soll, damit der Kunde seine Zahlungsdaten bereits bei der Auswahl eingeben kann, muss die Zahlungsart schon vor dem Laden des Widgets feststehen. Dafür gibt es zwei Varianten. Beide beruhen darauf, dass im Shop eigene Zahlungsarten mit Stripe als Clearing-Service angelegt werden und das Template das Widget an die gewählte Zahlungsart klammert. Sie unterscheiden sich darin, wie weit diese Aufteilung geht.

​

Variante 1: eigene Zahlungsarten für Google Pay und Apple Pay

Bei dieser Variante werden lediglich die beiden Wallets voneinander getrennt. Alle übrigen Zahlungsarten von Stripe bleiben wie bisher in einer Zahlungsart zusammen.

Konfiguration

Legen Sie im Konfigurationsdienst unter payment.payment je eine eigene Zahlungsart für Google Pay und Apple Pay an und hinterlegen Sie bei beiden Stripe als Clearing-Service unter onlineClearing. Neben der bestehenden Stripe-Zahlungsart stehen dann drei Einträge zur Auswahl, beispielsweise mit den Kennungen stripe, googlePay und applePay.

Damit weiß der Shop ab der Zahlungsarten-Seite, welches Wallet der Kunde gewählt hat. Das Template kann sich im weiteren Verlauf darauf beziehen.

Zahlungsarten-Seite

Auf der Seite “Zahlungsarten” laden Sie das Payment-Element wie gewohnt, schalten die Wallets dort aber ab. Der Kunde gibt dort also nur seine Karten- oder anderen Zahlungsdaten ein. Es kann sich kein Wallet-Dialog öffnen.

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");

Wurde Google Pay oder Apple Pay als Zahlungsart gewählt, wird auf dieser Seite gar kein Widget geladen. Binden Sie die Ausgabe stattdessen an die gewählte Zahlungsart:

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

Bestellübersicht

In der Bestellübersicht wird für Google Pay und Apple Pay statt des Payment Elements das Express Checkout Element angezeigt. Es wird der Wallet-Button angezeigt und die Zahlung wird erst ausgelöst, wenn alle Angaben feststehen.

{{ 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 }}

Das Express-Checkout-Element hängt an derselben elements-Instanz wie das Payment Element. Über allowedPaymentMethodTypes: ['card'] bleiben nur die beiden Wallets übrig. Über paymentMethods wird das nicht gewählte Wallet ausgeblendet.

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");

​

Variante 2: jede Stripe-Zahlungsart einzeln anlegen

Diese Variante geht einen Schritt weiter. Anstatt nur die Wallets abzutrennen, legen Sie jede Stripe-Zahlungsart einmal im Shop an, beispielsweise Kreditkarte, SEPA-Lastschrift, Klarna und PayPal, jeweils mit Stripe als Clearing-Service. Der Kunde wählt damit bereits auf der Zahlungsarten-Seite die konkrete Zahlungsart aus, und das Widget lädt nur noch diese eine.

Gesteuert wird das über allowedPaymentMethodTypes. Die Option nimmt die Stripe-Kennungen der Zahlungsarten entgegen, beispielsweise card, sepa_debit, klarna oder paypal. Das Template setzt die passende Kennung zur gewählten Zahlungsart:

{{ 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);

Für Google Pay und Apple Pay gilt dasselbe wie in Variante 1: Beide hängen an card und erhalten allowedPaymentMethodTypes: ['card'] und werden über wallets bzw. paymentMethods ein- und ausgeblendet. Der Einbau auf Zahlungsarten-Seite und Bestellübersicht ist identisch zu Variante 1.

​

Welche Variante wann sinnvoll ist

Variante 1 ist der kleinere Eingriff. Sie lohnt sich, wenn der Shop das Stripe-Widget weiterhin als Zahlungsart führt und nur das Problem mit den Wallets lösen möchte.

Variante 2 lohnt sich, wenn der Kunde bereits in der Zahlungsartenauswahl des Shops die konkrete Zahlungsart sehen soll, statt sie erst im Stripe-Widget auszuwählen. Der Konfigurationsaufwand ist jedoch höher, weil jede Zahlungsart einzeln angelegt und gepflegt werden muss.

​

Vor dem Livegang prüfen

• Domain registrieren. Google Pay und Apple Pay erscheinen nur auf Domains, die bei Stripe als Payment Method Domain registriert sind, und zwar getrennt für Testmodus und Livemodus.
• HTTPS. Das Express Checkout Element arbeitet mit einem iframe und setzt eine Auslieferung über https:// voraus.
• Betrag im Wallet-Dialog. Vergleichen Sie den Betrag im Apple-Pay- beziehungsweise Google-Pay-Dialog mit der Bestellsumme, insbesondere wenn Versandart oder Kosten der Zahlungsart die Summe verändern.
• Geräte ohne Wallet. Testen Sie den Fall, dass das Wallet nicht verfügbar ist, und stellen Sie sicher, dass der Kunde dann eine andere Zahlungsart wählen kann.
• Rechnungsadresse. Prüfen Sie im Stripe-Dashboard, welche Adresse bei der Zahlung ankommt, wenn das Wallet eine eigene Adresse liefert.

---

​

Weiterführende Links

• Generelle Doku für das Stripe Frontend: https://docs.stripe.com/js
• Express Checkout Element (Google Pay und Apple Pay): https://docs.stripe.com/elements/express-checkout-element
• Domain für Wallets registrieren: https://docs.stripe.com/payments/payment-methods/pmd-registration
• MultiPage Checkout