Zum Inhalt

Dokumentation

Einführung

Ein paar Worte zur Einleitung:

Referenz

Library

Auf allen Seiten, die mit Amazon Pay interagieren, muss folgendes JavaScript von Amazon eingebunden werden:

<script src="https://static-eu.payments-amazon.com/checkout.js"></script>

Zur einfachen Einbindung empfehlen wir außerdem, die folgende JavaScript Klasse einzubinden. Wir werden sie in den weiteren Code-Beispielen verwenden. Natürlich könnt ihr auch eure eigenen Funktionen verwenden oder sie nach belieben anpassen.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
class ShopwareAmazonPayHeadlessHelper {
    renderButtons(selector, buttonData) {
        window.amazonPayButtonCount = window.amazonPayButtonCount || 0;
        const buttons = document.querySelectorAll(selector);
        if (!buttons || typeof amazon === 'undefined') {
            return;
        }
        buttons.forEach(button => {
            try {
                if (!button.getAttribute('render-id')) {
                    const id = 'amazon-pay-button-' + window.amazonPayButtonCount++;
                    button.setAttribute('render-id', id);
                    if (!button.id) {
                        button.id = id;
                    }
                    const buttonConfiguration = {
                        merchantId: buttonData.merchantId,
                        createCheckoutSessionConfig: {
                            payloadJSON: buttonData.payload,
                            signature: buttonData.signature,
                            publicKeyId: buttonData.publicKeyId,
                        },
                        sandbox: buttonData.sandbox,
                        ledgerCurrency: buttonData.ledgerCurrency,
                        checkoutLanguage: buttonData.checkoutLanguage,
                        productType: buttonData.productType,
                        placement: buttonData.placement,
                        buttonColor: buttonData.buttonColor
                    };
                    amazon.Pay.renderButton('#' + button.id, buttonConfiguration);
                }
            } catch (e) {
                console.warn(e);
            }
        });
    }

    initializePurePayment(sessionData) {
        try {
            const configuration = {
                merchantId: sessionData.merchantId,
                createCheckoutSessionConfig: {
                    payloadJSON: sessionData.payload,
                    signature: sessionData.signature,
                    publicKeyId: sessionData.publicKeyId,
                },
                sandbox: sessionData.sandbox,
                ledgerCurrency: sessionData.ledgerCurrency,
                checkoutLanguage: sessionData.checkoutLanguage,
                productType: sessionData.productType,
                placement: 'Cart'
            };
            amazon.Pay.initCheckout(configuration);
        } catch (e) {
            console.warn(e);
        }
    }
}

Express Checkout

Ein Überblick über den Ablauf der Integration:

Express Checkout - Button

Um den Express Checkout Button zu rendern, benötigen wir ein HTML-Element als Container, z.B.: 

<div class="amazon-pay-button"></div>

Als Nächstes erfragen wir vom Headless-Server die Daten, die wir für den Button benötigen. Dazu verwenden wir die Route /store-api/amazon-pay-checkout-button und senden die URL, auf die der Kunde nach dem Login bei Amazon zurückgeleitet werden soll. Diese URL ist neu anzulegen und Ihre Funktion wird im nächsten Abschnitt behandelt.

Um den Button zu rendern, müssen wir die Daten, die wir von unserem Server erhalten haben, an die JavaScript-Klasse übergeben. Dazu verwenden wir die Methode renderButtons der Klasse ShopwareAmazonPayHeadlessHelper, die wir oben eingebunden haben.

Die Methode erwartet als ersten Parameter einen CSS-Selektor, der das HTML-Element identifiziert, in dem der Button gerendert werden soll. Als zweiter Parameter wird ein Objekt erwartet, das die Daten enthält, die wir von unserem Server erhalten haben. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
fetch('https://[headless-domain]/store-api/amazon-pay-checkout-button', {
    method: 'POST',
    headers: {
        'sw-access-key': swAccessKey,
        'sw-context-token': contextToken,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        reviewReturnUrl: '[review-return-url]',
    })
})
    .then((response) => response.json())
    .then((data) => {
        if (data.merchantId) {
            (new ShopwareAmazonPayHeadlessHelper).renderButtons('.amazon-pay-button', data);
        }
    });

Express Checkout - Return URL

Nach der Rückkehr von Amazon Pay auf die von uns angegebene URL, wollen wir mit den erhaltenen Daten eine Shop-Session erzeugen, die die Kundendaten enthält. Diese Daten erhalten wir aus der amazonCheckoutSessionId, die von Amazon an die Return URL angehängt wird. Die nötige Verarbeitung erfolgt über die Route /store-api/amazon-pay-checkout-review, der wir die amazonCheckoutSessionId übergeben.

Die Return URL kann also eine leere Seite sein oder z.B. einen Loading-Spinner enthalten, der die Kund:innen darauf hinweist, dass die Daten verarbeitet werden. Im Erfolgsfall wird z.B. auf die Versandarten- oder "Jetzt kaufen"-Seite weitergeleitet. Die Session enthält an dieser Stelle alle notwendigen Kundendaten. Wir wollen außerdem die amazonCheckoutSessionId an die URL anhängen oder anderweitig speichern, weil wir sie im letzten Schritt noch einmal benötigen werden.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
fetch('https://[headless-domain]/store-api/amazon-pay-checkout-review', {
    method: 'POST',
    headers: {
        'sw-access-key': swAccessKey,
        'sw-context-token': contextToken,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        amazonCheckoutSessionId: urlParams.get('amazonCheckoutSessionId')
    })
})
    .then((response) => response.json())
    .then((data) => {
        if (data.success) {
            location.href = '[default-checkout-confirmation-page]'+'?amazonCheckoutSessionId='+urlParams.get('amazonCheckoutSessionId')
        } else {
            // handle error
        }
    });

Express Checkout - Handle Payment

Der übliche Aufruf an den Endpunkt /store-api/handle-payment wird noch um den Parameter amazonPayCheckoutId erweitert. Dieser Parameter enthält die amazonCheckoutSessionId, die wir im letzten Schritt gespeichert haben. Das könnte in etwa so aussehen:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
fetch('https://[headless-domain]/store-api/handle-payment', {
    method: 'POST',
    headers: {
        'sw-access-key': swAccessKey,
        'sw-context-token': contextToken,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        'orderId': orderId,
        'finishUrl': '[shop-success-domain]',
        'errorUrl': '[shop-error-domain]',
        'amazonPayCheckoutId': urlParams.get('amazonCheckoutSessionId')
    })
})
    .then(paymentResponse => paymentResponse.json())
    .then(paymentData => {
//        if (paymentData.redirectUrl) {
//            location.href = paymentData.redirectUrl;
//        } else {
//           // handle error
//        }
    });

Pure Payment

Ein Überblick über den Ablauf der Integration:

Pure Payment - Handle Payment

Den üblichen Aufruf an den Endpunkt /store-api/handle-payment erweitern wir um den Parameter amazonPayInitializePurePaymentUrl erweitert. Diese URL ist neu anzulegen und Ihre Funktion wird im nächsten Abschnitt behandelt.

Der amazonPayInitializePurePaymentUrl Parameter kann bei jedem handle-payment-Aufruf gesendet werden. Das Plugin erkennt selbst, ob Amazon Pay als Zahlungsart gewählt wurde und verarbeitet oder ignoriert die URL entsprechend.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
fetch('https://[headless-domain]/store-api/handle-payment', {
    method: 'POST',
    headers: {
        'sw-access-key': swAccessKey,
        'sw-context-token': contextToken,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        'orderId': orderId,
        'finishUrl': '[shop-success-domain]',
        'errorUrl': '[shop-error-domain]',
        'amazonPayInitializePurePaymentUrl': '[amazon-pay-initialize-pure-payment-url]'
    })
})
    .then(paymentResponse => paymentResponse.json())
    .then(paymentData => {
//        if (paymentData.redirectUrl) {
//            location.href = paymentData.redirectUrl;
//        } else {
//           // handle error
//        }
    });

Pure Payment - Initialize Pure Payment URL

Auf dieser neu anzulegenden Seite initialisieren wir die Weiterleitung an Amazon per JavaScript. Dazu binden wir das Amazon Pay JS ein und verwenden wir die Methode initializePurePayment der Klasse ShopwareAmazonPayHeadlessHelper, die wir oben eingebunden haben.
Auch diese URL kann wieder eine leere Seite (evtl. mit Loading-Spinner) sein. Wir übergeben dabei die orderTransactionId, die automatisch an die URL angehängt wurde und eine returnUrl, die wir ebenfalls neu festlegen. Auf diese Seite wird der Kunde nach der erfolgreichen Zahlung zurückgeleitet und die Zahlung bestätigt. An die returnUrl wird die orderTransactionId angehängt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
fetch('https://[headless-domain]/store-api/amazon-pay-pure-payment', {
    method: 'POST',
    headers: {
        'sw-access-key': swAccessKey,
        'sw-context-token': contextToken,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        returnUrl: '[amazon-pay-finalize-pure-payment-url]?orderTransactionId=' + urlParams.get('orderTransactionId'),
        orderTransactionId: urlParams.get('orderTransactionId')
    })
})
    .then((response) => response.json())
    .then((data) => {
        if (data.merchantId) {
            (new ShopwareAmazonPayHeadlessHelper).initializePurePayment(data);
        }
    });

Pure Payment - Finalize Pure Payment URL

Auf dieser neu anzulegenden Seite bestätigen wir die Zahlung mit dem Store-API Endpunkt store-api/amazon-pay-pure-payment-finalize und leiten den Kunden auf die Success-Seite weiter.
Auch diese URL kann wieder eine leere Seite (evtl. mit Loading-Spinner) sein.

An den Endpunkt senden wir die orderTransactionId, die wir im vorherigen Schritt an diese URL angehängt haben und die amazonCheckoutSessionId, die von Amazon hinzugefügt wurde.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
fetch('https://[headless-domain]/store-api/amazon-pay-pure-payment-finalize', {
    method: 'POST',
    headers: {
        'sw-access-key': swAccessKey,
        'sw-context-token': contextToken,
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        orderTransactionId: urlParams.get('orderTransactionId'),
        amazonCheckoutSessionId: urlParams.get('amazonCheckoutSessionId')
    })
})
    .then((response) => response.json())
    .then((data) => {
        if (data.success) {
            location.href = '[shop-success-domain]';
        } else {
            // handle error
        }
    });

Hilfe

Sollten noch Fragen offen sein oder unerwartete Probleme auftauchen, kontaktiert uns gern unter headless-amazon-pay@onlineshop.consulting.