IMPORTANT: This SDK is under development. We might still introduce minor breaking changes before reaching v1.

The Node.js SDK for the SumUp API.

To learn more, check out our API Reference and Developer Documentation. You can also find the full documentation of the SumUp Node.js SDK at sumup.github.io/sumup-ts.

Requirements

Node 18 or higher.

The package is published to both npm and JSR, so you can use it from modern JavaScript runtimes that provide the standard fetch, Headers, Request, and Response APIs.

Installation

Install the package with:

npm install @sumup/sdk
# or
yarn add @sumup/sdk
# or
pnpm add @sumup/sdk
# or
bun add @sumup/sdk
Copy

Install from jsr:

deno add jsr:@sumup/sdk
# or
npx jsr add @sumup/sdk
Copy

Supported Features

The SDK provides:

• Typed clients for all SumUp API endpoints.
• API key authentication and OAuth access token usage through the same client.
• ESM and CommonJS entry points.
• Base and per-request overrides for headers, authorization, host, timeout, retries, and abort signals.
• Access to both parsed data and the raw Response object via companion *WithResponse() methods.

Setup

Before making requests:

1. Create a SumUp API key, see Authorization guide in the SumUp Developer portal.
2. Export your credentials as environment variables.
3. Use your merchant code for merchant-scoped requests and examples.

export SUMUP_API_KEY="sup_sk_..."
export SUMUP_MERCHANT_CODE="MC123456789"
Copy

Usage

const { SumUp } = require("@sumup/sdk");

const client = new SumUp({
  apiKey: 'sup_sk_MvxmLOl0...'
});

const merchantCode = process.env.SUMUP_MERCHANT_CODE;

client.merchants.get(merchantCode)
  .then(merchant => console.info(merchant))
  .catch(error => console.error(error));
Copy

Or using ES modules and async/await:

import SumUp from "@sumup/sdk";

const client = new SumUp({
  apiKey: 'sup_sk_MvxmLOl0...',
});

const merchantCode = process.env.SUMUP_MERCHANT_CODE!;
const merchant = await client.merchants.get(merchantCode);
console.info(merchant);
Copy

Per-request options are available as the last argument to any SDK call. For example, you can override authorization, timeout, retries, or headers for a single request:

await client.checkouts.list(undefined, {
  timeout: 5_000,
});

await client.merchants.get(merchantCode, {
  authorization: `Bearer ${accessToken}`,
  headers: {
    "x-request-id": "req_123",
  },
  maxRetries: 1,
});
Copy

If you need the raw response metadata together with the parsed payload:

const { data, response } = await client.merchants.getWithResponse(merchantCode);

console.info(response.status, data);
Copy

Events

Receive signed event notifications and register callbacks for the changes your application needs:

import SumUp, { SIGNATURE_HEADER } from "@sumup/sdk";

const client = new SumUp({ apiKey: process.env.SUMUP_API_KEY });
const secret = process.env.SUMUP_EVENT_SECRET;
if (!secret) throw new Error("SUMUP_EVENT_SECRET is required");

const events = client.eventsHandler(secret, event => {
  console.info("Unhandled event", event.id, event.type);
});
events.on("members.updated", async event => {
  const member = await event.fetchObject();
  console.info("Member updated", member.id);
});

// Inside your HTTP handler, pass the unchanged request body and signature.
await events.handle(
  await request.arrayBuffer(),
  request.headers.get(SIGNATURE_HEADER) ?? "",
);
// Return a 2xx response after processing succeeds.
Copy

The handler verifies the signature before running callbacks and waits for them to finish.

For a standard Fetch Request, use await events.handleRequest(request) instead.

Make callbacks idempotent and use event.id to deduplicate deliveries. Return a 5xx response if processing fails so delivery can be retried. For queued processing, verify before storing the payload.

See the Node.js / Express, Deno, and Bun examples for complete receivers and error handling.

Examples

Install dependencies inside an example directory before running it:

cd examples/checkout
npm install
Copy

Available examples:

examples/checkout

Creates an online checkout and shows how to process it with card details.

Required environment variables:

export SUMUP_API_KEY="sup_sk_..."
export SUMUP_MERCHANT_CODE="MC123456789"
Copy

Run it with:

cd examples/checkout
npx tsx index.ts
Copy

examples/card-reader-checkout

Lists paired readers for a merchant and creates a terminal checkout on the first available reader.

Required environment variables:

export SUMUP_API_KEY="sup_sk_..."
export SUMUP_MERCHANT_CODE="MC123456789"
Copy

Run it with:

cd examples/card-reader-checkout
npx tsx index.ts
Copy

examples/oauth2

Runs a local Express app that implements the OAuth 2.0 Authorization Code flow with PKCE and then uses the returned access token with the SDK.

Required environment variables:

export CLIENT_ID="..."
export CLIENT_SECRET="..."
export REDIRECT_URI="http://localhost:8080/callback"
export PORT="8080"
Copy

Run it with:

cd examples/oauth2
npx tsx index.ts
Copy

Then open http://localhost:8080/login in your browser to start the flow.

Event receivers

Each example verifies raw request bytes and dispatches typed events. See its README for setup:

• Node.js / Express (default)
• Deno, using Deno.serve
• Bun, using Bun.serve

Support

For SDK reference material and API details:

• API reference: https://developer.sumup.com/api
• Developer documentation: https://developer.sumup.com
• Generated SDK docs: https://sumup.github.io/sumup-ts/

If you need to report a bug or request an enhancement, open an issue in this repository.