Usage Examples

This page provides practical examples demonstrating how to interact with the SumUp API using the Node.js SDK. These examples highlight common use cases and demonstrate the recommended way to initialize the client and make API calls. For details on installation and basic setup, refer to the [Getting Started] page. For a comprehensive overview of the SumUp client and its available resources, see the [SumUp Client API Reference].

All examples rely on environment variables for sensitive information like API keys and merchant codes.

Prerequisites

Before running these examples, ensure you have:

• Node.js 18 or higher installed.
• The @sumup/sdk installed (e.g., npm install @sumup/sdk).
• An API key from your SumUp Developer Portal.
• Your SumUp Merchant Code (required for some operations).

You'll need to set the following environment variables:

• SUMUP_API_KEY: Your SumUp secret API key (e.g., sup_sk_MvxmLOl0...).
• SUMUP_MERCHANT_CODE: Your SumUp merchant code (e.g., S0M3M3RCH4NT).

You can set these variables in your shell before running the script:

1. Basic Checkout Example

This example demonstrates how to create a new checkout, retrieve merchant information, and then simulate processing the checkout with card details. It showcases interactions with the merchant and checkouts API resources.

Explanation

1. Client Initialization: The SDK client is initialized using process.env.SUMUP_API_KEY, ensuring your API key is not hardcoded.
2. Get Merchant Information: It fetches and logs the authenticated merchant's details, demonstrating a simple GET request. It also shows how to get the raw Response object using .withResponse().
3. Create Checkout: A new checkout is created with a specified amount, currency, and a unique checkout_reference. The merchant_code is essential here, also fetched from environment variables.
4. Process Checkout: It then simulates processing this checkout using dummy card data. Note: In a real-world scenario, card data should be handled securely and never directly in your backend like this. This part of the example is purely illustrative of the SDK's method signature.

Code (examples/checkout/index.ts)

How to Run

Save the code above as checkout-example.ts in your project's root directory. Make sure SUMUP_API_KEY and SUMUP_MERCHANT_CODE are set in your environment. Then, run it using tsx (which you might need to install globally via npm install -g tsx if not already available, or use npx tsx):

2. Card Reader Checkout Example

This example demonstrates how to interact with SumUp card readers to create a checkout. It involves listing available readers and initiating a checkout specific to a reader.

Explanation

1. Client Initialization: Similar to the previous example, the client is initialized with the API key from environment variables.
2. Check Merchant Code: It verifies that the SUMUP_MERCHANT_CODE environment variable is set.
3. List Card Readers: It fetches a list of card readers paired with the specified merchant.
4. Handle No Readers: If no readers are found, it warns the user to pair a reader first.
5. Create Card Reader Checkout: It then creates a checkout targeting the first available card reader, specifying the total amount and currency. The currency must match the merchant account's currency.

Code (examples/card-reader-checkout/index.ts)

How to Run

Save the code above as card-reader-example.ts in your project's root directory. Make sure SUMUP_API_KEY and SUMUP_MERCHANT_CODE are set in your environment, and you have at least one card reader paired with your SumUp merchant account. Then, run it using tsx: