Medusa.js

Cost+ über das offizielle costplus-medusa Plugin in Ihren Medusa.js v2 Shop integrieren

Integrieren Sie Cost+ als Zahlungsanbieter in Ihren Medusa.js v2 Shop. Das offizielle costplus-medusa Plugin registriert einen eigenen Medusa-Zahlungsanbieter für jede Cost+ Zahlungsmethode, verwendet den Hosted Payment Page Ablauf und verifiziert jede Statusänderung gegen die Cost+ API — vollständig PCI-DSS-konform.

Voraussetzungen

Aktives Cost+ Händlerkonto
Medusa.js 2.14.2 oder neuer
Node.js 22
PostgreSQL-Zugang über Medusas DATABASE_URL
Eine öffentlich erreichbare HTTPS Medusa-Backend-URL (für Webhooks erforderlich)
Ein Storefront-Checkout, der cart_id beim Initiieren der Zahlungssitzung übergibt

Unterstützte Zahlungsmethoden

Checkout-Name	Medusa-Anbieter-ID	Cost+-Bezeichner
Kredit- / Debitkarte	`pp_costplus-credit-card_costplus`	`credit-card`
Apple Pay	`pp_costplus-apple-pay_costplus`	`apple-pay`
Google Pay	`pp_costplus-google-pay_costplus`	`google-pay`
Vipps MobilePay	`pp_costplus-vipps-mobilepay_costplus`	`vipps-mobilepay`

Jeder Anbieter erstellt eine Cost+-Bestellung für genau eine Zahlungsmethode, sodass die Checkout-Optionen der Storefront mit dem Cost+ Hosted-Payment-Weiterleitungsablauf übereinstimmen.

1. Plugin installieren

Installieren Sie das Paket in Ihrem Medusa-Backend-Projekt:

npm install costplus-medusa

Sie können auch aus einem getaggten Git-Release installieren: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Plugin und Anbieter registrieren

Fügen Sie das Plugin und den Zahlungsanbieter zu Ihrer medusa-config.ts hinzu:

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

module.exports = defineConfig({
  plugins: [
    {
      resolve: "costplus-medusa",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "costplus-medusa/providers/costplus",
            id: "costplus",
            options: {},
          },
        ],
      },
    },
  ],
})

Starten Sie das Medusa-Backend neu, damit das neue Plugin und der Anbieter geladen werden.

3. Im Admin konfigurieren

Öffnen Sie im Medusa Admin Cost+ (Pfad /app/costplus) und konfigurieren Sie:

API-Schlüssel — Ihr Händler-API-Schlüssel aus dem Händlerportal (Websites → Ihre Website → Integration)
Checkout-Ablauf — Timeout in Minuten (an Cost+ als ISO-8601-Dauer gesendet, z. B. 5 → PT5M, Standard ist 5 Minuten)
Manuelle Erfassung — optional, autorisiert Kartenzahlungen ohne sofortige Erfassung
Debug-Logging — optional, protokolliert API-Anfragen und -Antworten zur Fehlerbehebung

Aktivieren Sie auf derselben Cost+ Admin-Seite die Checkout-Methoden, die Sie pro Region verfügbar machen möchten:

Cost+ Credit / Debit Card
Cost+ Apple Pay
Cost+ Google Pay
Cost+ Vipps MobilePay

Aktivieren Sie nur die Zahlungsmethoden, für die Sie freigeschaltet wurden und eine Bestätigung erhalten haben.

Das Umschalten der Methoden auf dieser Seite aktualisiert die regionalen Zahlungsanbieter-Verknüpfungen in Medusa für die Cost+-Anbieter, sodass der Standard-Store-API-Endpunkt /store/payment-providers?region_id=... nur die aktivierten Cost+-Methoden zurückgibt. Wenn alle Cost+-Methoden für eine Region deaktiviert sind, gibt die Store API keine Cost+-Anbieter für diese Region zurück.

4. Storefront-Integration

Wenn Sie eine Cost+-Zahlungssitzung initiieren, übergeben Sie die Medusa cart_id in data:

await sdk.store.payment.initiatePaymentSession(paymentCollection.id, {
  provider_id: "pp_costplus-credit-card_costplus",
  data: {
    cart_id: cart.id,
    return_url: `${origin}/${countryCode}/checkout/costplus/return?cart_id=${cart.id}`,
    failure_url: `${origin}/${countryCode}/checkout?step=payment&costplus_cancelled=1&cart_id=${cart.id}`,
  },
})

Nach Erstellung der Sitzung leiten Sie den Käufer zu payment_session.data.costplus_payment_url weiter.

Die Standard-Erfolgsroute ist /checkout/costplus/return?cart_id={cart_id} — diese Seite sollte den Complete-Cart-Endpoint von Medusa aufrufen und anschließend die Bestellbestätigungsseite anzeigen. Die Failure-URL sollte den Käufer zum Zahlungsschritt zurückführen, ohne den Warenkorb abzuschließen.

Die Verarbeitung von Rückkehr und Webhook verifiziert die Cost+-Bestellung immer mit GET /orders/{id}/, bevor der Zahlungsstatus zurück nach Medusa abgebildet wird.

Zahlungsmethoden über die Store API auflisten

Listen Sie die Zahlungsmethoden über die Store API von Medusa auf, anstatt die Cost+-Anbieter-IDs in Ihrem Storefront fest zu codieren. Wenn der Storefront /store/payment-providers cacht, verwenden Sie no-store oder invalidieren Sie den Cache nach Änderungen im Admin, damit deaktivierte Methoden sofort aus dem Checkout verschwinden.

Eine Referenzimplementierung finden Sie unter examples/nextjs/costplus-return/ im costplus-medusa-Repository — eine Next.js-DTC-Starter-Rückkehrseite, die einen Client-Handler mit einer Server Action kombiniert, sodass der Abschluss des Warenkorbs außerhalb des Seiten-Renderings erfolgt und zuverlässig auf /order/{id}/confirmed weiterleitet.

5. Webhooks

Das Plugin registriert automatisch einen Webhook-Endpoint unter /hooks/payment/{identifier}_costplus. Die Medusa-Backend-URL muss öffentlich über HTTPS erreichbar sein, damit Cost+ asynchrone Statusaktualisierungen liefern kann.

Wenn Bestellungen lange nach Ablauf des konfigurierten Timeouts noch ausstehend sind, deutet das auf ein Problem mit der Webhook-Zustellung oder dem Rückkehrablauf hin und nicht auf die Ablaufeinstellung selbst.

6. Sicherheit und Speicherung der Einstellungen

Der API-Schlüssel wird verschlüsselt, bevor er in der Medusa-Datenbank gespeichert wird. Setzen Sie in der Produktion COSTPLUS_SETTINGS_SECRET:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Falls COSTPLUS_SETTINGS_SECRET nicht gesetzt ist, greift das Plugin auf Medusas COOKIE_SECRET oder JWT_SECRET zurück.

Setzen Sie COSTPLUS_API_KEY in der Umgebung, um die Quelle des API-Schlüssels zu fixieren — wenn gesetzt, überschreibt die Admin-Seite den Wert nicht. Lassen Sie es leer, wenn Händler den Schlüssel im Admin verwalten sollen.

7. Testen und Live-Schaltung

Die Cost+-Umgebung wird durch den API-Schlüssel bestimmt — ein Sandbox-Website-Schlüssel läuft im Testmodus, ein Produktions-Website-Schlüssel im Live-Modus (keine separate Sandbox-URL). Führen Sie einige Testtransaktionen durch, um erfolgreiche, abgebrochene und abgelaufene Abläufe zu verifizieren, bevor Sie live gehen.

Support

Brauchen Sie Hilfe? Wenden Sie sich an unser Support-Team unter support@costplus.io.

Medusa.js

On this page