SumUp QR Checkout System

A FastAPI application that generates printable QR codes for products. When scanned with a smartphone, these QR codes instantly trigger SumUp card reader checkouts. The app tracks the last transaction to enable cancellation via a separate QR code.

Features

• Product QR code generation with print-friendly layout
• Support for multiple SumUp card readers
• Custom reader names for better organization
• Automatic page breaks between reader sections when printing
• Instant checkout on SumUp card readers
• Transaction cancellation via a dedicated QR code
• Persistent storage of transaction IDs
• External transaction webhook integration
• Docker support for easy deployment

Setup

1. Clone the repository
2. Copy .env.example to .env and update the configuration values
3. Run with Docker Compose:

docker-compose up -d

Environment Variables

Configure the application by setting the following environment variables in the .env file:

Required Configuration

• SUMUP_API_KEY: Your SumUp API key
• SUMUP_MERCHANT_ID: Your SumUp merchant ID
• APP_BASE_URL: Base URL of your application (e.g., http://localhost:8000)
• CURRENCY: Currency code (e.g., EUR)
• RETURN_URL: URL to redirect after payment

Reader Configuration (Option 1: Single Reader)

• SUMUP_READER_ID: Your SumUp card reader ID

Reader Configuration (Option 2: Multiple Readers)

• SUMUP_READER_1: First SumUp card reader ID
• SUMUP_READER_1_NAME (optional): Name for the first reader (e.g., "Coffee Station")
• SUMUP_READER_2: Second SumUp card reader ID
• SUMUP_READER_2_NAME (optional): Name for the second reader (e.g., "Snack Bar")

You can add as many readers as needed by incrementing the number.

Optional Configuration

• PAGE_TITLE: Title shown on the page header (default: "Product QR Codes")
• WEBHOOK_URL: URL to send transaction data to an external system
• WEBHOOK_SECRET: Secret key for signing webhook payloads

Adding Products

Products are configured through environment variables:

PRODUCT_1_ID=coffee
PRODUCT_1_NAME=Coffee
PRODUCT_1_PRICE=3.50

PRODUCT_2_ID=sandwich
PRODUCT_2_NAME=Sandwich
PRODUCT_2_PRICE=6.00

Add as many products as needed by incrementing the number (PRODUCT_3_, PRODUCT_4_, etc.)

Endpoints

• /: View all product QR codes grouped by reader
• /checkout/{reader_id}/{product_id}: Trigger checkout for a specific product using a specific reader
• /cancel: Cancel the last transaction
• /cancel-qr: View the cancellation QR code
• /health: Health check endpoint (returns reader and product counts)

Webhook Integration

The application supports sending transaction data to an external system via webhooks. This feature helps maintain an external transaction ledger or integrate with other systems.

Configuration

Set the following environment variables in your .env file:

WEBHOOK_URL=https://your-ledger-system.example/api/transactions
WEBHOOK_SECRET=your-webhook-secret-key

The WEBHOOK_SECRET is optional but highly recommended for security.

Webhook Payload

When a transaction is processed, the application will send a POST request to the configured webhook URL with the following payload:

{
  "timestamp": 1635789012,
  "transaction_data": {
    "data": {
      "client_transaction_id": "12ea1235-3e2e-495b-a699-353194b23916",
      "checkout_reference": "ch_a1b2c3d4e5f6g7h8",
      ... other SumUp response data ...
    }
  },
  "merchant_id": "MQM3KGC5",
  "reader_id": "rdr_7H482YV9DY8Y7S6HXBPP99EPWK"
}

Security

If a WEBHOOK_SECRET is configured, the application will sign the webhook payload with HMAC-SHA256 and include the signature in the request headers:

• X-Webhook-Signature: HMAC-SHA256 signature of the request body
• X-Webhook-Timestamp: Unix timestamp when the webhook was sent

Your external system should verify this signature by:

1. Concatenating the request body as a string
2. Creating an HMAC-SHA256 signature using the shared secret
3. Comparing this signature with the one in the X-Webhook-Signature header

Architecture Documentation

This project includes comprehensive architecture documentation in the architecture_docs directory:

• projectRoadmap.md: Project goals, features, and future considerations
• architecture.md: System architecture, components, and technical decisions
• currentTask.md: Details about the latest implemented features
• codebaseSummary.md: Overview of key components and their interactions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.