SumUp Python SDK

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

The Python SDK for the SumUp API.

Installation

Install the latest version of the SumUp SDK:

pip install sumup
# or
uv add sumup

Usage

Synchronous Client

import os

from sumup import Sumup

client = Sumup(api_key="sup_sk_MvxmLOl0...")

# Get merchant profile
merchant = client.merchants.get(merchant_code=os.environ["SUMUP_MERCHANT_CODE"])
print(f"Merchant: {merchant.merchant_code}")

Async Client

import asyncio
import os

from sumup import AsyncSumup


async def main():
    client = AsyncSumup(api_key="sup_sk_MvxmLOl0...")

    # Get merchant profile
    merchant = await client.merchants.get(merchant_code=os.environ["SUMUP_MERCHANT_CODE"])
    print(f"Merchant: {merchant.merchant_code}")


asyncio.run(main())

Creating a Checkout

import os
import uuid

from sumup import Sumup

client = Sumup(api_key="sup_sk_MvxmLOl0...")
merchant_code = os.environ["SUMUP_MERCHANT_CODE"]

# Create a checkout
checkout = client.checkouts.create(
    amount=10.00,
    currency="EUR",
    checkout_reference=str(uuid.uuid4()),
    merchant_code=merchant_code,
    description="Test payment",
    redirect_url="https://example.com/success",
    return_url="https://example.com/webhook",
)

print(f"Checkout ID: {checkout.id}")
print(f"Checkout Reference: {checkout.checkout_reference}")

Creating a Reader Checkout

from sumup import Sumup

client = Sumup(api_key="sup_sk_MvxmLOl0...")

# Create a reader checkout
reader_checkout = client.readers.create_checkout(
    reader_id="your-reader-id",
    merchant_code="your-merchant-code",
    total_amount={
        "value": 1000,  # 10.00 EUR (amount in cents)
        "currency": "EUR",
        "minor_unit": 2,
    },
    description="Coffee purchase",
    return_url="https://example.com/webhook",
)

print(f"Reader checkout created: {reader_checkout}")

Handling Events

Create a handler with your event signing secret and register typed callbacks:

import os

from sumup import Sumup
from sumup.events import EventNotification, ReaderCreatedEvent

client = Sumup(api_key=os.environ["SUMUP_API_KEY"])


def fallback(event: EventNotification) -> None:
    print(f"Received {event.type}")


events = client.events_handler(os.environ["SUMUP_EVENT_SECRET"], fallback)


@events.on_reader_created
def reader_created(event: ReaderCreatedEvent) -> None:
    reader = event.fetch_object()
    print(f"Reader paired: {reader.id}")


# In your HTTP route, pass the unchanged body and the complete
# X-SumUp-Webhook-Signature header value:
events.handle(raw_body, signature)

You can also register an existing function with events.on_reader_created(callback).

Send a 2xx response after handling succeeds. Reject EventSignatureError and EventPayloadError with 400; return 500 for EventCallbackError so processing can be retried. Make callbacks idempotent and configure body limits in your server.

Use AsyncSumup with async callbacks, await events.handle(...), and await event.fetch_object_async() for async servers. For parsing without callbacks, use client.parse_event_notification(body, signature, secret).

See the runnable Flask and FastAPI examples for complete HTTP routes and error handling.

Version Support Policy

sumup-py maintains compatibility with Python versions that have not passed end-of-life. As of June 8, 2026, that means Python 3.10 through 3.14. See Status of Python versions.