Medusa

Allgemein

Medusa ist ein Open-Source-Commerce-Framework für Headless-Shops. Mit dem zahls.ch-Plugin akzeptierst du TWINT, Kredit- und Debitkarten, PostFinance und weitere Methoden über den gehosteten Checkout.

Funktionen

✅ Gehosteter Checkout (Redirect zur zahls.ch-Zahlungsseite)
✅ Captures für autorisierte / reservierte Transaktionen
✅ Rückerstattungen über zahls.ch-Transaktionen
✅ Webhooks für asynchrone Statusupdates
✅ Optionale HMAC-Signaturprüfung
✅ Keine Rohkartendaten im Medusa-Backend

Kompatibilität

Medusa v2.18.x
zahls.ch Gateway API

Setup

1. Plugin installieren

npm install @zahls/medusa-plugin

2. Zahlungsarten in zahls.ch aktivieren

Navigiere im Dashboard zu Zahlungsanbieter.
Aktiviere Payrexx Pay und/oder Payrexx Pay Plus sowie die gewünschten Zahlungsarten.
Wir empfehlen mindestens TWINT, Mastercard, Visa, Apple Pay, Google Pay und PostFinance.

Details: Aktivierung der Bezahldienste.

3. API-Schlüssel erstellen

Navigiere im Dashboard zu API und Integrationen.
Klicke auf API-Schlüssel hinzufügen.
Vergib einen Namen (z. B. «Medusa») und klicke auf Hinzufügen.
Kopiere den API-Schlüssel — du brauchst ihn im nächsten Schritt.

Weitere Informationen: API und Integrationen.

4. Medusa konfigurieren

Registriere das Plugin und den Payment Provider in medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  plugins: [
    {
      resolve: "@zahls/medusa-plugin",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@zahls/medusa-plugin/providers/zahls",
            id: "zahls",
            options: {
              apiKey: process.env.ZAHLS_API_KEY,
              instance: process.env.ZAHLS_INSTANCE,
              webhookSecret: process.env.ZAHLS_WEBHOOK_SECRET,
              successRedirectUrl: process.env.ZAHLS_SUCCESS_URL,
              failedRedirectUrl: process.env.ZAHLS_FAILED_URL,
              cancelRedirectUrl: process.env.ZAHLS_CANCEL_URL,
            },
          },
        ],
      },
    },
  ],
})

Setze die Umgebungsvariablen in deinem Medusa-Backend:

Variable	Pflicht	Beschreibung
`ZAHLS_API_KEY`	Ja	Instanz-API-Schlüssel aus API & Integrationen
`ZAHLS_INSTANCE`	Ja	Instanzname (`beispiel` für `beispiel.zahls.ch`)
`ZAHLS_WEBHOOK_SECRET`	Nein	Geheimnis für die HMAC-Prüfung
`ZAHLS_SUCCESS_URL`	Nein	Redirect nach erfolgreicher Zahlung
`ZAHLS_FAILED_URL`	Nein	Redirect nach fehlgeschlagener Zahlung
`ZAHLS_CANCEL_URL`	Nein	Redirect nach Abbruch

5. Provider in der Region aktivieren

Nach dem Start der Anwendung aktivierst du zahls.ch unter Medusa Admin → Settings → Regions für die gewünschte Region. Die Provider-ID lautet typischerweise pp_zahls_zahls.

6. Testzahlung

Lege eine Testbestellung im Storefront an.
Wähle zahls.ch als Zahlungsmethode — die Kundschaft wird zum gehosteten Checkout weitergeleitet.
Prüfe Status und Transaktion im zahls.ch-Dashboard.

Webhooks

Medusa nutzt die eingebaute Payment-Webhook-Route für asynchrone Statusupdates. Optional prüft das Plugin die HMAC-Signatur, wenn webhookSecret gesetzt ist.

Mehr dazu: Webhooks.

Marketing- und Kombinationsseiten

Medusa-Integration
Beispiel: TWINT für Medusa