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

Install from jsr:

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

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 .withResponse().

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"

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));

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);

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,
});

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

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

console.info(response.status, data);

Examples

Install dependencies inside an example directory before running it:

cd examples/checkout
npm install

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"

Run it with:

cd examples/checkout
npx tsx index.ts

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"

Run it with:

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

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"

Run it with:

cd examples/oauth2
npx tsx index.ts

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

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.