Skip to main content

SumUp Python SDK

pypi Documentation CI Status pypi download License

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...")
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...")
    merchant = await client.merchants.get(merchant_code=os.environ["SUMUP_MERCHANT_CODE"])
    print(f"Merchant: {merchant.merchant_code}")


asyncio.run(main())

Client Cleanup

Use clients directly as shown above, or use a context manager to close connections automatically when the block exits:

with Sumup(api_key="sup_sk_MvxmLOl0...") as client:
    merchant = client.merchants.get(merchant_code=os.environ["SUMUP_MERCHANT_CODE"])

For async code, use async with:

async def main():
    async with AsyncSumup(api_key="sup_sk_MvxmLOl0...") as client:
        merchant = await client.merchants.get(merchant_code=os.environ["SUMUP_MERCHANT_CODE"])

For long-running applications, reuse a client across requests and call client.close() or await client.aclose() during shutdown, after outstanding work finishes. A closed client cannot be reused.

Handling errors

Catch APIError to handle failed requests, or use a specific exception such as RateLimitError when your application needs to handle a failure differently.

When the API returns a Problem response, error.problem gives you typed fields such as type, title, and detail. It is None for other error responses.

from sumup import APIError, Sumup
from sumup.errors import APIStatusError, RateLimitError

with Sumup() as client:
    try:
        checkout = client.checkouts.get("your-checkout-id")
    except RateLimitError:
        print("Too many requests. Try again later.")
    except APIStatusError as error:
        if (problem := error.problem) is not None:
            print(problem.type, problem.detail)
        else:
            print(error)
    except APIError as error:
        print(error)

For errors returned by the API, error.status gives you the HTTP status, error.body holds the full error details, and error.response provides the original response, including its headers and text.

Use the same try/except pattern with AsyncSumup.

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.

Metadata

Release files for sumup 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sumup 0.4.3
File Size Uploaded Provenance Actions
sumup-0.4.3.tar.gz 105.1 kB With provenance Details for sumup-0.4.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sumup 0.4.3
File Interpreter ABI Platform Actions
sumup-0.4.3-py3-none-any.whl Python 3 none any Details for sumup-0.4.3-py3-none-any.whl

Total release size: 214.0 kB

Release files / sumup-0.4.3.tar.gz

Download URL sumup-0.4.3.tar.gz
Size 105.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a99a50eacf773ecd7aff7950bbc31475c5c50749ea603ffe0117ef985c249447
BLAKE2b-256 checksum
How to use checksums
bc8496c967af42830d8c31dac6943072ed2e1ffe00f742c80ac077b01c70b6b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / sumup-0.4.3-py3-none-any.whl

Download URL sumup-0.4.3-py3-none-any.whl
Size 108.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ee36858eabb4e8e0299cdaa4a40526e686a15198da73561c6db57bf6f9e66061
BLAKE2b-256 checksum
How to use checksums
7e84c7587bd2e939ba6b49214dfd4096c2399e51ec80fab7f3756fd410a8e26a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for sumup 0.4.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sumup-0.4.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page