Sumup

SumUp Payments for Medusa

A SumUp payment provider plugin for Medusa V2. Inspired by https://github.com/VariableVic/mollie-payments-medusa and mostly implemented by Claude.

[!WARNING] This plugin has not been tested on a live store. Please conduct thorough testing before using it in a production environment. I am not responsible for any missed or failed payments resulting from the use of this plugin. If you encounter any issues, please report them here.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
  • Configuration Options
  • Environment Variables
• Usage
• Client-Side Integration
• License

Features

• SumUp Checkout: Creates a hosted SumUp checkout session that customers complete via the SumUp Card Widget or a custom card form.
• Webhook Support: Receives real-time checkout status updates via SumUp webhooks.
• Refunds: Supports full and partial refunds via the SumUp Transactions API.
• Amount verification: A PAID checkout only authorizes/captures the session it was created for — its amount and currency must match the ones stored in the session data.
• No extra dependencies: Uses the native Node.js fetch API — no additional HTTP client needed.

Prerequisites

• Medusa server v2.3.0 or later
• Node.js v20 or later
• A SumUp merchant account with a valid API key and merchant code

[!NOTE] You can find your API key and merchant code in your SumUp Dashboard under Settings → Developer → API Keys.

Installation

Configuration

Add the provider to the @medusajs/payment module in your medusa-config.ts file:

Configuration Options

Per-session redirect URL

A payment session may override the redirect target by passing data.redirect_url (e.g. a locale-specific https://shop.example.com/us/checkout/complete). The override is accepted only when its host is the same as redirectUrl's host or appears in redirectUrlAllowedHosts, and its scheme is http/https; otherwise the checkout is rejected with INVALID_DATA. When omitted, redirectUrl is used.

[!IMPORTANT] The storefront's own origin must be an allowed redirect host. A typical storefront sends data.redirect_url = \${location.origin}/${countryCode}/checkout/complete`on every payment session. If the storefront's domain is **not** the host of the backend's configuredredirectUrl**and** is not listed inredirectUrlAllowedHosts`, session creation fails and customers cannot pay.

This bites most often when the backend redirectUrl env and the storefront domain drift apart between environments (e.g. a *.sslip.io or preview deploy, or a separate admin vs. storefront domain). Whenever you add a storefront origin, add it to redirectUrlAllowedHosts. Example:

Environment Variables

Add the following to your .env file:

Usage

Once installed and configured, the SumUp payment method will be available in your Medusa Admin. To enable it:

1. Log in to your Medusa Admin
2. Go to Settings → Regions
3. Add or edit a region and select SumUp from the payment providers dropdown

The provider ID for the SumUp checkout is:

pp_sumup_sumup

Client-Side Integration

SumUp checkouts are created server-side by Medusa. After a payment session is initiated, the session data will contain a SumUp checkout id that you pass to the SumUp Card Widget on your storefront to render the payment form.

Basic flow:

1. Customer reaches the payment step — Medusa creates a SumUp checkout via initiatePayment
2. Your storefront receives the checkout id from the payment session data
3. Render the SumUp Card Widget with the checkout ID
4. SumUp processes the payment and calls the Medusa webhook (/hooks/payment/sumup_sumup)
5. Because SumUp auto-captures, a PAID checkout is reported to Medusa as captured at authorize time — the order's payment is marked captured immediately on completion, without waiting for the webhook. The webhook (which the plugin always re-verifies against the SumUp API, since SumUp webhooks are unsigned) acts as a backstop that reconciles status if the browser flow is interrupted.

Example Card Widget integration:

For APMs (iDEAL, Bancontact, etc.), the redirectUrl option handles the post-payment redirect automatically.

License

MIT