@sumup/vendure-plugin

SumUp payment plugin for Vendure.

It creates SumUp checkouts from Vendure's PaymentMethodHandler flow and supports both:

• SumUp Hosted Checkout redirects
• widget-oriented storefront integrations that use a returned checkoutId

The plugin never handles raw card data inside your Vendure server.

Compatible with Vendure ^3.6.4.

What it provides

• a Vendure plugin: SumUpPlugin
• a payment handler: sumUpPaymentHandler
• a webhook/callback controller at POST /payments/sumup/webhook

The webhook endpoint is notification-only. When SumUp calls it, the plugin re-fetches the checkout from SumUp and updates the matching Vendure payment from the checkout state.

Installation

npm install @sumup/vendure-plugin

Vendure configuration

Register the plugin and payment handler in your Vendure config:

import { VendureConfig } from "@vendure/core"

import { SumUpPlugin, sumUpPaymentHandler } from "@sumup/vendure-plugin"

export const config: VendureConfig = {
  // ...
  plugins: [
    SumUpPlugin.init({
      apiKey: process.env.SUMUP_API_KEY!,
      merchantCode: process.env.SUMUP_MERCHANT_CODE!,
      checkoutMode: "hosted",
      returnUrl: "https://your-vendure.example/payments/sumup/webhook",
      redirectUrl: "https://storefront.example/checkout/sumup/return",
    }),
  ],
  paymentOptions: {
    paymentMethodHandlers: [sumUpPaymentHandler],
  },
}

returnUrl should be a publicly reachable URL that SumUp can call with checkout status updates. In most setups that should be your Vendure server's /payments/sumup/webhook route.

Create the Payment Method

Create a Payment Method in the Vendure Admin UI:

• Code: sumup
• Handler: sumup

Optional handler arguments:

• merchantCode
• checkoutMode
• returnUrl
• redirectUrl
• paymentDescription

Global defaults can be defined in SumUpPlugin.init() and overridden per payment method when needed.

Usage

Storefront flow

Once the order is in ArrangingPayment, call addPaymentToOrder with method: "sumup" and any SumUp-specific metadata you need.

mutation AddPaymentToOrder {
  addPaymentToOrder(
    input: {
      method: "sumup"
      metadata: {
        checkout_mode: "hosted"
        checkout_reference: "ORDER-1001"
      }
    }
  ) {
    ... on Order {
      id
      state
      payments {
        transactionId
        metadata
      }
    }
    ... on ErrorResult {
      errorCode
      message
    }
  }
}

The plugin stores SumUp data on the Vendure payment and exposes a safe subset through payments[].metadata.public.

Hosted Checkout

Use checkout_mode: "hosted" or set checkoutMode: "hosted" in plugin/payment-method config.

After addPaymentToOrder, redirect the shopper to:

payments[].metadata.public.hostedCheckoutUrl

Widget-oriented flow

Use checkout_mode: "widget" if your storefront will mount SumUp's checkout UI itself.

After addPaymentToOrder, read:

payments[].metadata.public.checkoutId

Use that checkoutId in your storefront's SumUp client integration. The plugin still treats the webhook callback or a later checkout lookup as the source of truth for final payment state.

Public payment metadata

The plugin exposes these fields in payments[].metadata.public:

Field	Description
checkoutId	SumUp checkout id
checkoutReference	Merchant checkout reference sent to SumUp
checkoutMode	hosted or widget
hostedCheckoutUrl	Hosted Checkout URL when SumUp returns one
redirectUrl	Redirect URL associated with the checkout

Configuration options

Option	Required	Description
apiKey	Yes	SumUp API key or access token. Keep it server-side.
merchantCode	Yes	SumUp merchant code that receives the payment.
defaultLanguageCode	No	Language used for the handler description shown in Vendure.
checkoutMode	No	Default checkout mode: hosted or widget. Defaults to hosted.
returnUrl	No	Backend callback URL used by SumUp for checkout status updates.
redirectUrl	No	URL the shopper is sent to after redirect-based payment flows.
paymentDescription	No	Default SumUp checkout description.
timeout	No	SumUp SDK request timeout in milliseconds.
maxRetries	No	SumUp SDK retry count.
supportedCurrencies	No	Override the built-in supported currency allowlist.
client	No	Inject a custom SumUp client implementation. Useful for tests.

Payment state mapping

The plugin maps SumUp checkout state to Vendure payment state like this:

• successful transaction or PAID checkout -> Settled
• PENDING -> Authorized
• FAILED -> Declined
• EXPIRED -> Cancelled
• anything else -> Created

Integration notes

• The plugin does not add Admin UI extensions.
• The plugin does not extend Vendure's GraphQL schema. It uses the standard addPaymentToOrder payment metadata flow described in Vendure's payment docs.

Notes

• For local end-to-end testing, see examples/docker.
• For contributor workflow, release checks, and publishing notes, see CONTRIBUTING.md.