Expand description
§SumUp Rust SDK
Official Rust SDK for the SumUp REST API.
§Quick Start
use sumup::Client;
#[tokio::main]
async fn main() {
// Create a client (reads SUMUP_API_KEY from environment)
let client = Client::default();
// Call an API endpoint
let checkouts = client
.checkouts()
.list(Default::default())
.await
.expect("list checkouts request failed");
println!("found {} checkouts", checkouts.len());
}§Configuration
§Authentication
Set your API key via environment variable or explicitly:
// From environment variable SUMUP_API_KEY
let client = Client::default();
// Explicit token
let client = Client::default()
.with_authorization(Authorization::api_key("your_api_key"));§Custom Configuration
use std::time::Duration;
let client = Client::default()
.with_authorization(Authorization::api_key("your_api_key"))
.with_timeout(Duration::from_secs(30));To customize reqwest directly, build a configured reqwest::Client and pass
it to Client::with_client. Start from Client::http_client_builder to
keep the SDK’s default headers:
let http_client = Client::http_client_builder()
.pool_max_idle_per_host(8)
.build()?;
let client = Client::default().with_client(http_client);§Making API Calls
The SDK organizes endpoints by tags:
// Create a checkout
let checkout = client.checkouts().create(checkouts::CreateRequest::builder()
.checkout_reference("unique-ref")
.amount(10.0)
.currency(Currency::EUR)
.merchant_code("MCODE")
.build())
.await
.expect("create checkout");
println!("created checkout {}", checkout.id.unwrap_or_default());
// Transactions with query parameters
use sumup::resources::transactions::ListParams;
let transactions = client
.transactions()
.list(
"MERCHANT_CODE",
ListParams::builder().limit(10).build(),
)
.await
.expect("list transactions");
let count = transactions.items.as_ref().map_or(0, |items| items.len());
println!("fetched {} historical transactions", count);§Request Builders
Build requests and query parameters with builder(). Omit optional fields to
leave them absent, or pass values directly without Some(...). For nullable
fields, use Nullable::Null to send an explicit null, or Nullable::Value
to send a value.
use sumup::readers::CreateRequest;
let request = CreateRequest::builder()
.name("Front desk")
.pairing_code("12345678")
.build();
assert!(request.metadata.is_none());Required fields must be set before calling build(). Omitting one is a
compile-time error:
use sumup::readers::CreateRequest;
let request = CreateRequest::builder().name("Front desk").build();
// Missing required pairing_code.§DateTime Support
The SDK supports both chrono (default) and
jiff for datetime types:
# Use chrono (default)
[dependencies]
sumup = "0.5"
# Use jiff instead
[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"] }§Error Handling
Failed calls return a SdkError. Use problem() to read typed Problem details
when the API provides them:
let client = Client::default();
if let Err(error) = client.checkouts().get("your-checkout-id").await {
if let Some(problem) = error.problem() {
eprintln!("{}: {}", problem.r#type, problem.detail.as_deref().unwrap_or("Request failed"));
}
eprintln!("{error}");
}Use SdkError::status, SdkError::headers, and SdkError::raw_body
to inspect the HTTP response. SdkError::body provides other typed error details.
§Features
- chrono (default): Use chrono for datetime types
- jiff: Use jiff for datetime types (mutually exclusive with chrono)
- reqwest-default-tls (default): Use reqwest’s default TLS backend
- reqwest-rustls-tls: Use reqwest’s rustls TLS backend
§Resources
Re-exports§
pub use auth::Authorization;pub use client::Client;pub use error::ApiErrorResponse;pub use error::ProblemDetails;pub use error::ResponseError;pub use error::SdkError;pub use error::SdkResult;pub use error::UnknownApiBody;pub use nullable::Nullable;pub use secret::Secret;pub use version::VERSION;pub use crate::resources::*;