Sign up

Medusa

How to connect zahls.ch as a payment provider in Medusa v2 with the official @zahls/medusa-plugin npm package.

Overview

Medusa is an open-source commerce framework for headless shops. With the zahls.ch plugin you accept TWINT, credit and debit cards, PostFinance, and more via the hosted checkout.

Features

  • ✅ Hosted checkout (redirect to the zahls.ch payment page)
  • ✅ Captures for authorized / reserved transactions
  • ✅ Refunds through zahls.ch transactions
  • ✅ Webhooks for asynchronous status updates
  • ✅ Optional HMAC signature verification
  • ✅ No raw card data in the Medusa backend

Compatibility

  • Medusa v2.18.x
  • zahls.ch Gateway API

Setup

1. Install the plugin

npm install @zahls/medusa-plugin

2. Activate payment methods in zahls.ch

  1. In the dashboard, go to Payment providers.
  2. Activate Payrexx Pay and/or Payrexx Pay Plus plus the payment methods you need.
  3. We recommend at least TWINT, Mastercard, Visa, Apple Pay, Google Pay, and PostFinance.

Details: Activating payment services.

3. Create an API key

  1. In the dashboard, go to API and integrations.
  2. Click Add API key.
  3. Choose a name (e.g. “Medusa”) and click Add.
  4. Copy the API key — you need it in the next step.

More information: API and integrations.

4. Configure Medusa

Register the plugin and 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,
            },
          },
        ],
      },
    },
  ],
})

Set the environment variables in your Medusa backend:

VariableRequiredDescription
ZAHLS_API_KEYYesInstance API secret from API & Integrations
ZAHLS_INSTANCEYesInstance name (example for example.zahls.ch)
ZAHLS_WEBHOOK_SECRETNoSecret for HMAC verification
ZAHLS_SUCCESS_URLNoRedirect after successful payment
ZAHLS_FAILED_URLNoRedirect after failed payment
ZAHLS_CANCEL_URLNoRedirect after cancellation

5. Enable the provider for a region

After the application starts, enable zahls.ch under Medusa Admin → Settings → Regions for the relevant region. The provider identifier is typically pp_zahls_zahls.

6. Test payment

  1. Place a test order in the storefront.
  2. Choose zahls.ch as the payment method — the customer is redirected to the hosted checkout.
  3. Check status and transaction in the zahls.ch dashboard.

Webhooks

Medusa uses its built-in payment webhook route for asynchronous status updates. Optionally the plugin verifies the HMAC signature when webhookSecret is set.

More: Webhooks.

Marketing and combo pages

Related