# JavaScript SDK

The [`@sumup/sdk`](https://github.com/sumup/sumup-ts) 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:

```bash
npm install @sumup/sdk
```

```bash
yarn add @sumup/sdk
```

```bash
pnpm add @sumup/sdk
```

```bash
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:

```ts
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

```ts
import SumUp from "@sumup/sdk";

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

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

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

createOnlineCheckout().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

### Cloud API Checkout

```ts
import SumUp from "@sumup/sdk";

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

async function createSoloCheckout() {
  const merchantCode = process.env.SUMUP_MERCHANT_CODE ?? "";
  const affiliateKey = process.env.SUMUP_AFFILIATE_KEY ?? "";
  const affiliateAppId = process.env.SUMUP_APP_ID ?? "";
  if (!affiliateKey || !affiliateAppId) {
    throw new Error(
      "Set SUMUP_AFFILIATE_KEY and SUMUP_APP_ID to use the Cloud API.",
    );
  }
  const { items: readers } = await client.readers.list(merchantCode);
  const solo = readers.find((reader) => reader.device.model === "solo");
  if (!solo) {
    throw new Error("Pair a Solo reader before using the Cloud API.");
  }

  const checkout = await client.readers.createCheckout(merchantCode, solo.id, {
    total_amount: {
      currency: "EUR",
      minor_unit: 2,
      value: 1500,
    },
  });

  console.log(checkout.data.client_transaction_id);
}

createSoloCheckout().catch((error) => {
  console.error(error);
  process.exit(1);
});
```