SumUp

Accept payments in Vendure with SumUp Hosted Checkout or the SumUp Payment Widget.

Requires Node.js 20 or later and Vendure ^3.6.4. Keep your SumUp API key on the server. SumUp collects the shopper's payment details.

Installation

npm install @sumup/vendure-plugin

Vendure Configuration

Register the plugin and payment handler:

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],  },}

Set returnUrl to your Vendure server's public /payments/sumup/webhook URL so SumUp can send payment updates. Set redirectUrl to the storefront page the shopper should return to after checkout.

Create the Payment Method

Create and enable a payment method in the Vendure Admin UI:

• Code: sumup
• Handler: sumup

You can override merchantCode, checkoutMode, returnUrl, redirectUrl, and paymentDescription in the payment method's handler arguments. Otherwise, the values from SumUpPlugin.init() apply.

Create a Checkout

Once the order is in ArrangingPayment, call addPaymentToOrder with method: "sumup":

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

The response includes the checkout details in payments[].metadata.public.

You can pass an empty metadata object to use the configured checkout mode. To supply your own checkout reference, set metadata.checkout_reference; otherwise, the plugin uses the order code. Use a new reference when creating a replacement checkout.

Hosted Checkout

Hosted Checkout is the default. You can also select it with metadata.checkout_mode: "hosted".

After addPaymentToOrder, redirect the shopper to:

payments[].metadata.public.hostedCheckoutUrl

Payment Widget

Set checkoutMode: "widget" in your configuration or pass metadata.checkout_mode: "widget" when creating the payment.

After addPaymentToOrder, read:

payments[].metadata.public.checkoutId

Use that checkoutId to mount the SumUp Payment Widget in your storefront.

Payment Status

Creating a checkout leaves the payment in SumUpPending and the order in ArrangingPayment. The order stays unpaid while the shopper completes checkout.

When SumUp sends an update, the plugin checks the checkout status with SumUp and updates the payment:

A fully paid order moves to PaymentSettled. Confirm the order's payment status before fulfilling it. Returning to redirectUrl or receiving a widget success event alone does not confirm payment.

Public Payment Metadata

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

Configuration Options

Contributing

See CONTRIBUTING.md for local development, tests, custom API clients, and releases.