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 {
checkout_reference: "unique-ref".to_string(),
amount: 10.0,
currency: Currency::EUR,
merchant_code: "MCODE".to_string(),
description: None,
return_url: None,
customer_id: None,
purpose: None,
valid_until: None,
redirect_url: None,
hosted_checkout: None,
})
.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 {
limit: Some(10),
..Default::default()
},
)
.await
.expect("list transactions");
let count = transactions.items.as_ref().map_or(0, |items| items.len());
println!("fetched {} historical transactions", count);§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
All SDK calls return a SdkResult whose error side is a SdkError. When the
SumUp API responds with a non-success status, the SDK builds an
SdkError::Api containing an endpoint-specific payload (e.g. a Unauthorized
enum variant). Any undocumented status codes fall back to
SdkError::Unexpected, which preserves the HTTP status and best-effort body
parsing. Requests rejected by local validation return SdkError::InvalidRequest.
You can inspect failures like this:
let client = Client::default();
match client.checkouts().list(Default::default()).await {
Ok(checkouts) => println!("retrieved {} checkouts", checkouts.len()),
Err(SdkError::Api(body)) => match body {
ListErrorBody::Unauthorized(details) => eprintln!("unauthorized: {:?}", details),
},
Err(SdkError::Unexpected(status, body)) => {
eprintln!("unexpected {} response: {}", status, body);
}
Err(SdkError::Network(err)) => panic!("network error: {}", err),
Err(SdkError::InvalidRequest(reason)) => eprintln!("invalid request: {}", reason),
}§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::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::*;