sumup 0.6.0

Rust SDK for the SumUp API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

<div align="center">

# SumUp Rust SDK

[![SumUp's crates.io badge](https://img.shields.io/crates/v/sumup.svg)](https://crates.io/crates/sumup)
[![SumUp's docs.rs badge](https://docs.rs/sumup/badge.svg)](https://docs.rs/sumup)
[![CI Status](https://github.com/sumup/sumup-rs/workflows/CI/badge.svg)](https://github.com/sumup/sumup-rs/actions/workflows/ci.yml)
[![Documentation][docs-badge]](https://developer.sumup.com)
[![License](https://img.shields.io/github/license/sumup/sumup-rs)](./LICENSE)

</div>

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

The [Rust](https://rust-lang.org/) SDK for the SumUp [API](https://developer.sumup.com).

## Requirements

Rust 1.90.0 or higher. We follow [Firefox MSRV policy](https://firefox-source-docs.mozilla.org/writing-rust-code/update-policy.html).

## Installation

Install with:

```sh
cargo add sumup
```

## Quick Start

```rust
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

```rust
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:

```rust
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:

```rust
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()`:

```rust
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:

```toml
[dependencies]
sumup = "0.5"
```

Use `jiff` for datetime types:

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

Use rustls instead of reqwest's default TLS backend:

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

## Examples

You can find all examples under [examples/](/examples/). To run an example, use:

```sh
cargo run --example checkout_card_reader
```

For development instructions, see [Contributing](CONTRIBUTING.md).

[docs-badge]: https://img.shields.io/badge/SumUp-documentation-white.svg?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgY29sb3I9IndoaXRlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogICAgPHBhdGggZD0iTTIyLjI5IDBIMS43Qy43NyAwIDAgLjc3IDAgMS43MVYyMi4zYzAgLjkzLjc3IDEuNyAxLjcxIDEuN0gyMi4zYy45NCAwIDEuNzEtLjc3IDEuNzEtMS43MVYxLjdDMjQgLjc3IDIzLjIzIDAgMjIuMjkgMFptLTcuMjIgMTguMDdhNS42MiA1LjYyIDAgMCAxLTcuNjguMjQuMzYuMzYgMCAwIDEtLjAxLS40OWw3LjQ0LTcuNDRhLjM1LjM1IDAgMCAxIC40OSAwIDUuNiA1LjYgMCAwIDEtLjI0IDcuNjlabTEuNTUtMTEuOS03LjQ0IDcuNDVhLjM1LjM1IDAgMCAxLS41IDAgNS42MSA1LjYxIDAgMCAxIDcuOS03Ljk2bC4wMy4wM2MuMTMuMTMuMTQuMzUuMDEuNDlaIiBmaWxsPSJjdXJyZW50Q29sb3IiLz4KPC9zdmc+