SumUp

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:

Configuration options

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.