@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.