SumUp Rust SDK

IMPORTANT: This SDK is under heavy development and subject to breaking changes.

The Rust SDK for the SumUp API.

Requirements

Rust 1.90.0 or higher. We follow Firefox MSRV policy.

Installation

Install with:

cargo add sumup

Quick Start

use sumup::Client;

#[tokio::main]
async fn main() {
    // Initialize the client (reads SUMUP_API_KEY from environment)
    let client = Client::default();

    // List existing checkouts
    let checkouts = client
        .checkouts()
        .list(Default::default())
        .await
        .expect("list checkouts");
    println!("retrieved {} checkouts", checkouts.len());
}

Authentication

use sumup::{Authorization, Client};

// Read SUMUP_API_KEY from the environment
let client = Client::default();

// Or set an explicit API key
let client = Client::default()
    .with_authorization(Authorization::api_key("your_api_key"));

Handling errors

API errors retain their HTTP status, headers, and original response bytes. Read typed Problem details directly when available:

if let Err(error) = client.checkouts().get("your-checkout-id").await {
    if let Some(problem) = error.problem() {
        println!("{}: {}", problem.r#type, problem.detail.as_deref().unwrap_or("Request failed"));
    }
    println!("{:?}", error.status());
}

Use status() and headers() to inspect the HTTP response, raw_body() for its original bytes, and body() for other typed error details.

HTTP Configuration

The SDK uses reqwest as its HTTP transport. You can provide a configured reqwest::Client for settings such as proxies, custom TLS roots, connection pooling, redirect policy, or request timeouts.

Start from Client::http_client_builder() to keep the SDK's default headers:

use sumup::Client;

let http_client = Client::http_client_builder()
    .pool_max_idle_per_host(8)
    .build()
    .expect("build reqwest client");

let client = Client::default().with_client(http_client);

Request Builders

Build requests and query parameters with builder():

use sumup::{Currency, checkouts};

let request = checkouts::CreateRequest::builder()
    .checkout_reference("order-123")
    .amount(10.0)
    .currency(Currency::EUR)
    .merchant_code("MCODE")
    .description("Coffee")
    .build();

Required fields must be set before build() compiles. Optional setters accept the value directly, without Some(...), nullable fields accept Nullable::Null or Nullable::Value(value). Struct literals and direct field updates are also supported.

Features

By default the SDK enables chrono datetime support and reqwest's default TLS backend:

[dependencies]
sumup = "0.5"

Use jiff for datetime types:

[dependencies]
sumup = { version = "0.5", default-features = false, features = ["jiff", "reqwest-default-tls"] }

Use rustls instead of reqwest's default TLS backend:

[dependencies]
sumup = { version = "0.5", default-features = false, features = ["chrono", "reqwest-rustls-tls"] }

Examples

You can find all examples under examples/. To run an example, use:

cargo run --example checkout_card_reader

For development instructions, see Contributing.