Dokumentation
Dokumentation
Express-Kasse

1Einführung

Express Checkout ermöglicht es Kunden, direkt von einer Produkt- oder Warenkorbseite über Wallet-Buttons (zum Beispiel PayPal, Apple Pay oder Google Pay) zu bezahlen, ohne ein separates Checkout-Formular zu durchlaufen.

2Integrationsschritte

Die Integration besteht aus fünf logischen Schritten:

Schritt Teil Erforderlich? Bedeutung für den Händler

1

Session erstellen (POST /api/v2.0/express-checkout/session/create)

Ja

Erstellen Sie pro Checkout-Versuch eine Session und speichern Sie die zurückgegebenen Identifikatoren.

2

Wallet-Widget anzeigen (iframe mit sessionToken)

Ja

Zeigen Sie dem Kunden die Wallet-Oberfläche an.

3

Versand-Callback (merchantShippingCallbackUrl)

Bedingt

Nur erforderlich, wenn versandpflichtige Artikel vorhanden sind und Versandoptionen dynamisch berechnet werden müssen.

4

Rückkehr zum Shop und Bestellung erstellen (GET merchantRedirectUrl)

Ja

Nach der Bestätigung durch den Kunden kehrt der Ablauf zu Ihrem Shop zurück. Erstellen Sie in diesem Schritt die Bestellung. Optional können Sie Session-Details abrufen (GET /api/v2.0/express-checkout/session), um die Bestellung mit finaler Adresse, Versandoption und Beträgen zu validieren oder anzureichern.

5

Session verarbeiten (POST /api/v2.0/express-checkout/session/process)

Ja

Rufen Sie diesen Endpoint nach der Rückkehr zu merchantRedirectUrl auf und leiten Sie den Browser anschließend zur redirectUrl aus der Antwort weiter.

Begriffe zur Weiterleitung:

  • merchantRedirectUrl ist die URL, über die der Ablauf den Kunden zu Ihrem Shop zurückführt.

  • redirectUrl wird von /express-checkout/session/process zurückgegeben und ist die nächste URL, zu der Ihr Shop den Kunden weiterleiten muss.

3Ablauf

Integrationsablauf für Express Checkout

3.11. Eine Express Checkout Session erstellen

  • Methode: POST

  • URL: /api/v2.0/express-checkout/session/create

  • Authentifizierung: HMAC-Token

Die vollständige Liste der Felder und ihrer Beschreibungen finden Sie unter API Client. Request-Modell: IExpressCheckoutSession.ICreate. Response-Modell: ExpressCheckoutSessionCreateResponse.

{
  "currency": "CHF",
  "authorizationEnvironment": "TEST",
  "merchantRedirectUrl": "https://your-shop.com/checkout/complete?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "merchantShippingCallbackUrl": "https://your-shop.com/api/shipping-options?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "lineItems": [
    {
      "uniqueId": "item-1",
      "sku": "SKU-001",
      "name": "Product Name",
      "type": "PRODUCT",
      "quantity": 1,
      "amountIncludingTax": 42.00,
      "shippingRequired": true,
      "currency": "CHF",
      "taxes": []
    }
  ]
}

In diesem Beispiel ist sessionUuid=550e8400-e29b-41d4-a716-446655440000 ein vom Händler erzeugter Korrelationswert. Der Shop muss sessionUuid dem zurückgegebenen sessionId zuordnen.

Die Antwort enthält:

  • sessionId — die ID der erstellten Session

  • sessionToken — Sicherheitstoken, der für die Verarbeitung benötigt wird

Implementierungshinweise:

  • In der Praxis erforderlich: Geben Sie die bestellrelevanten Daten an (currency, lineItems, merchantRedirectUrl).

  • Erforderlich: Geben Sie authorizationEnvironment (TEST oder PRODUCTION) an. Diese Umgebung wird verwendet, um die Wallet-Verfügbarkeit und das Verarbeitungsverhalten der Session zu bestimmen.

  • Bedingt erforderlich: Geben Sie merchantShippingCallbackUrl an, wenn das Wallet Versandoptionen anfordern muss.

  • Erforderlich für zuverlässige Korrelation: Erzeugen Sie eine eigene sessionUuid, hängen Sie diese an merchantRedirectUrl und merchantShippingCallbackUrl an und speichern Sie eine Zuordnung sessionUuid <→ sessionId.

  • Identifikatoren passend speichern: Persistieren Sie sessionId für die spätere Verarbeitung. Halten Sie sessionToken verfügbar, bis das Widget gerendert wurde (persistente Speicherung ist optional).

3.22. Das Wallet-Widget anzeigen

Binden Sie das Wallet-iframe mit der Widget-URL in Ihre Seite ein, die mit dem sessionToken erstellt wird. Das Widget übernimmt die Adressauswahl, die Anzeige der Versandoptionen und die Zahlungsbestätigung.

Minimales Einbettungsbeispiel:

<script src="https://<scope-base-path>/assets/payment/express-checkout-handler.js"></script>

<div id="express-checkout-container"></div>

<script>
  window.ExpressCheckoutHandler.load('express-checkout-container', sessionToken, {
    maxColumns: 3,
    maxRows: 2,
    onError: function (error) {
      // Optionaler benutzerdefinierter Fehler-Hook.
      // error = { source, code, message }
      console.error('Express Checkout Wallet-Fehler', error);
      alert(error.message);
    }
  });
</script>

Implementierungshinweise:

  • Erforderlich: Rendern Sie das Widget mit der containerId und dem sessionToken aus der Session-Erstellung.

  • Optional (maxColumns): Steuert, wie viele Wallet-Buttons pro Zeile angezeigt werden. Der erlaubte Bereich ist 1 bis 6. Wenn der Wert nicht angegeben wird, verwendet das Widget den Standardwert 2.

  • Optional (maxRows): Steuert die maximale Anzahl der zunächst angezeigten Zeilen. Der erlaubte Bereich ist 1 bis 10. Wenn der Wert nicht angegeben wird, wird keine Zeilenbegrenzung angewendet (alle gerenderten Zeilen werden angezeigt).

  • Optional (onError): Callback, der aufgerufen wird, wenn ein Wallet-iframe einen Integrations- oder Laufzeitfehler meldet. Er erhält ein Objekt mit source, code und message. Wenn vorhanden, wird dieser Callback zum aktiven Hook für die Fehleranzeige. Wenn er fehlt, bleibt die Standard-Fehlerbehandlung des Widgets aktiv.

  • Operatives Logging: Fehler aus Wallet-iframes werden an das Backend gemeldet und für Diagnosezwecke protokolliert.

3.33. Die Zahlung verarbeiten

Nach der Wallet-Bestätigung und der Rückkehr zu Ihrer merchantRedirectUrl rufen Sie den Verarbeitungs-Endpoint auf, um die Transaktion zu erstellen und die Zahlung zu autorisieren.

  • Methode: POST

  • URL: /api/v2.0/express-checkout/session/process

  • Authentifizierung: HMAC-Token (wie bei allen REST-API-Aufrufen)

Die vollständige Liste der Felder und ihrer Beschreibungen finden Sie unter API Client. Request-Modell: IExpressCheckoutSessionProcessRequest. Response-Modell: ExpressCheckoutSessionProcessResponse.

{
  "sessionId": 123456,
  "merchantReference": "EC-MR-789",
  "successUrl": "https://your-shop.com/checkout/success",
  "failureUrl": "https://your-shop.com/checkout/failure"
}

Implementierungshinweise:

  • Erforderlich: Rufen Sie diesen Endpoint nach der Bestätigung und nachdem der Kunde vom Portal zu Ihrem Shop zurückgeleitet wurde auf.

  • Erforderlich: Geben Sie sessionId, eine nicht leere idempotente merchantReference sowie successUrl und failureUrl an.

  • Erforderlich: Leiten Sie den Browser an die in der Antwort zurückgegebene URL weiter.

  • Wichtig: Express Checkout verwendet keinen Fallback auf die Standard-Ergebnis-URL der Zahlungsseite. Der Verarbeitungsaufruf muss explizite Händler-Ergebnis-URLs enthalten.

  • Optional (empfohlen): Rufen Sie vor der Verarbeitung die Session-Details ab, um den finalen Betrag, die Adresse und die ausgewählte Versandoption zu validieren.

  • Empfohlen: Behandeln Sie Webhooks als Quelle der Wahrheit für den finalen asynchronen Status (AUTHORIZED / FAILED), während Browser-Weiterleitungen die Kundennavigation steuern.

Die Antwort enthält eine Ziel-URL für die Weiterleitung. Leiten Sie den Kunden dorthin weiter, um 3DS (falls erforderlich) fortzusetzen und den Ablauf abzuschließen.

4Optional: Session-Details vor der Verarbeitung lesen

Sie können die bestätigte Express Checkout Session vor der Verarbeitung abrufen. Dies ist nützlich, um die Shop-Bestellung anhand der finalen Kundenauswahl zu erstellen oder zu validieren.

  • Methode: GET

  • URL: /api/v2.0/express-checkout/session

  • Authentifizierung: HMAC-Token

Die vollständige Liste der Felder und ihrer Beschreibungen finden Sie unter API Client.

Typische Verwendung:

  1. Lösen Sie Ihre interne Checkout-Referenz zur gespeicherten sessionId auf

  2. Rufen Sie die Session-Details ab

  3. Erstellen oder validieren Sie Ihre Bestellung anhand der zurückgegebenen Adresse, der ausgewählten Versandoption und der Beträge

  4. Rufen Sie /express-checkout/session/process auf

5Optional: Shipping Options Provider API

Wenn Ihre Produkte versendet werden müssen, müssen Sie einen Callback-Endpoint implementieren, den wallee aufruft, um Versandoptionen abzurufen, wenn der Kunde seine Adresse ändert. Die URL dieses Endpoints wird pro Session über das Feld merchantShippingCallbackUrl in der Erstellungsanfrage bereitgestellt.

Der Callback-Vertrag verwendet die folgenden drei Modelle:

  • IExpressCheckoutShippingOptionRequest

    • Erforderlich: countryCode, currency, language, expressCheckoutId, spaceId, requestId

    • Optional: state, street, city, postalCode

  • IExpressCheckoutShippingOptionsResponse

    • shippingOptions: Liste von IExpressCheckoutShippingOption-Einträgen (geben Sie bei Erfolg mindestens einen Eintrag zurück, bei Fehler eine leere Liste). Die vollständige Liste der Felder und ihrer Beschreibungen finden Sie unter IExpressCheckoutShippingOption.

    • error: null bei Erfolg oder ein IExpressCheckoutShippingOptionsClientError-Objekt bei einem fachlichen Fehler

  • IExpressCheckoutShippingOptionsClientError

    • Felder: error (kurzer Typ), message (menschenlesbare Erklärung), timestamp (optionale Zeitangabe)

5.1Endpoint-Spezifikation

  • Methode: POST

  • URL: Ihre konfigurierte Callback-URL

  • Content-Type: application/json

5.2Anfrage

Wallee sendet die folgenden Felder in IExpressCheckoutShippingOptionRequest:

Feld Typ Erforderlich? Hinweise

expressCheckoutId

Long

Ja

Identifikator der Express Checkout Session.

spaceId

String

Ja

Identifikator des Händler-Spaces.

requestId

String

Ja

Korrelations-ID für die Nachverfolgung.

countryCode

String

Ja

Ländercode (ISO-3166 alpha-2).

currency

String

Ja

Währungscode (ISO-4217).

language

String

Ja

Sprachcode (ISO-639).

state

String

Nein

Code für Bundesland, Kanton oder Provinz.

street

String

Nein

Straßenadresse.

city

String

Nein

Name der Stadt.

postalCode

String

Nein

Postleitzahl oder ZIP-Code.

 
{
  "expressCheckoutId": 123456,
  "spaceId": "84",
  "requestId": "21a2f7fe-51b7-4ed5-9f88-1fb128292986",
  "countryCode": "CH",
  "currency": "CHF",
  "language": "de",
  "state": "ZH",
  "street": "Beispielstrasse 5",
  "city": "Winterthur",
  "postalCode": "8400"
}

5.3Antwort (von Ihrem Shop zurückgegeben)

Geben Sie ein JSON-Objekt mit Versandoptionen oder einem Fehler zurück. Der Endpoint Ihres Shops muss IExpressCheckoutShippingOptionsResponse als HTTP-Response-Body an wallee zurückgeben.

Response-Vertrag:

  • Erfolgsfall: Geben Sie eine oder mehrere shippingOptions zurück und setzen Sie error auf null.

  • Fehlerfall: Geben Sie ein leeres shippingOptions-Array zurück und stellen Sie ein ausgefülltes error-Objekt bereit.

  • Keine HTTP-Codes ungleich 200 für fachliche Fehler verwenden: Behalten Sie HTTP 200 bei und kommunizieren Sie Fehler im Body.

  • HTTP-Codes ungleich 200 nur für technische Fehler verwenden: zum Beispiel ungültiges Payload-Format, Authentifizierungsfehler oder serverseitiger Ausfall.

5.3.1Felder der Versandoptionen

Feld Typ Erforderlich? Hinweise

id

String

Ja

Eindeutiger Identifikator der Versandoption.

label

String

Ja

Dem Kunden angezeigter Name.

description

String

Nein

Optionaler Beschreibungstext.

amountIncludingTax

Decimal

Ja

Gesamtbetrag für den Versand inklusive Steuern.

taxes

Array

Nein

Steuerzeilen mit title und rate (Prozent). Kann leer sein.

currency

String

Ja

ISO-4217-Währungscode. Muss der Session-Währung entsprechen.

5.3.2Fehlerfelder

Feld Typ Erforderlich? Hinweise

error

String

Ja

Kurzer Fehlertyp-Identifikator (zum Beispiel INVALID_ADDRESS, SERVICE_UNAVAILABLE).

message

String

Ja

Menschenlesbare Fehlerbeschreibung.

timestamp

String

Nein

Zeitpunkt, zu dem der Fehler aufgetreten ist.

5.3.3Erfolg 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Standardversand",
      "description": "Lieferung in 3-5 Werktagen",
      "amountIncludingTax": 9.99,
      "taxes": [
        { "title": "MwSt", "rate": 7.70 }
      ],
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Expressversand",
      "description": "Lieferung in 1-2 Werktagen",
      "amountIncludingTax": 19.99,
      "taxes": [
        { "title": "MwSt", "rate": 7.70 }
      ],
      "currency": "CHF"
    }
  ],
  "error": null
}

5.3.4Fehler 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "Die angegebene Lieferadresse ist für die Versandkostenberechnung nicht gültig",
    "timestamp": "2025-10-10T12:00:00Z"
  }
}

6Unterstützte Wallets

Wallet Status Hinweise

Bogus Pay

Verfügbar

Nur für Tests und Entwicklung.

PayPal

Verfügbar

Produktionsbereit in Express Checkout.

Apple Pay

Geplant

—

Google Pay

Geplant

—

7Testen mit Bogus Pay

Verwenden Sie für Tests Bogus Pay.

Es stellt simulierte Adressen, Testkarten und Bestätigungsabläufe bereit (einschließlich 3DS-Simulation).

Staging 2.207.2