Open

JavaScript SDK

Use the official TypeScript client to talk to every SumUp public API.

The @sumup/sdk(Opens in a new tab) package wraps SumUp API, ships TypeScript declarations, and works in modern JavaScript runtimes and platforms, including Node.js 18+, Cloudflare Workers, Vercel, and other ESM-friendly environments.

Installation

Install the package with your preferred JavaScript package manager:

1
npm install @sumup/sdk

1
yarn add @sumup/sdk

1
pnpm add @sumup/sdk

1
ant i land:@sumup/sdk

Configure Authentication

The client reads the SUMUP_API_KEY environment variable automatically, so deploying with SUMUP_API_KEY=sup_sk_MvxmLOl0... is enough for most server workloads. You can also pass the secret explicitly:

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

If you use OAuth, exchange the authorization code for an access token and pass it as the accessToken option instead of apiKey.

Examples

Online Payment Checkout

1
import SumUp from "@sumup/sdk";
2

3
const client = new SumUp({ apiKey: process.env.SUMUP_API_KEY ?? "" });
4

5
async function createOnlineCheckout() {
6
  const checkout = await client.checkouts.create({
7
    amount: 2500,
8
    checkout_reference: "ORDER-1001",
9
    currency: "EUR",
10
    merchant_code: process.env.SUMUP_MERCHANT_CODE ?? "",
11
    pay_to_email: process.env.SUMUP_PAY_TO_EMAIL ?? "",
12
    description: "Online payment via Payment Widget",
13
  });
14

15
  console.log(checkout.id);
16
  // Return checkout.id to your webpage so the SumUp Payment Widget can complete the payment.
17
}
18

19
createOnlineCheckout().catch((error) => {
20
  console.error(error);
21
  process.exit(1);
22
});

Cloud API Checkout

1
import SumUp from "@sumup/sdk";
2

3
const client = new SumUp({ apiKey: process.env.SUMUP_API_KEY ?? "" });
4

5
async function createSoloCheckout() {
6
  const merchantCode = process.env.SUMUP_MERCHANT_CODE ?? "";
7
  const affiliateKey = process.env.SUMUP_AFFILIATE_KEY ?? "";
8
  const affiliateAppId = process.env.SUMUP_APP_ID ?? "";
9
  if (!affiliateKey || !affiliateAppId) {
10
    throw new Error(
11
      "Set SUMUP_AFFILIATE_KEY and SUMUP_APP_ID to use the Cloud API.",
12
    );
13
  }
14
  const { items: readers } = await client.readers.list(merchantCode);
15
  const solo = readers.find((reader) => reader.device.model === "solo");
16
  if (!solo) {
17
    throw new Error("Pair a Solo reader before using the Cloud API.");
18
  }
19

20
  const checkout = await client.readers.createCheckout(merchantCode, solo.id, {
21
    total_amount: {
22
      currency: "EUR",
23
      minor_unit: 2,
24
      value: 1500,
25
    },
26
  });
27

28
  console.log(checkout.data.client_transaction_id);
29
}
30

31
createSoloCheckout().catch((error) => {
32
  console.error(error);
33
  process.exit(1);
34
});

Edit page