Pain001.Sdk
0.0.88
dotnet add package Pain001.Sdk --version 0.0.88
NuGet\Install-Package Pain001.Sdk -Version 0.0.88
<PackageReference Include="Pain001.Sdk" Version="0.0.88" />
<PackageVersion Include="Pain001.Sdk" Version="0.0.88" />
<PackageReference Include="Pain001.Sdk" />
paket add Pain001.Sdk --version 0.0.88
#r "nuget: Pain001.Sdk, 0.0.88"
#:package Pain001.Sdk@0.0.88
#addin nuget:?package=Pain001.Sdk&version=0.0.88
#tool nuget:?package=Pain001.Sdk&version=0.0.88
<p align="center"> <img src="https://cloudcdn.pro/pain001/v1/logos/pain001.svg" alt="pain001-sdk-dotnet logo" width="128" /> </p>
<h1 align="center">pain001-sdk-dotnet</h1>
<p align="center"> A typed .NET client for the pain001 REST API: validate, generate and check ISO 20022 pain.001 and pain.008 payment files from C#. </p>
<p align="center"> <a href="https://github.com/sebastienrousseau/pain001-sdk-dotnet/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/pain001-sdk-dotnet/ci.yml?style=for-the-badge&logo=github" alt="Build" height="28" /></a> <a href="https://www.nuget.org/packages/Pain001.Sdk"><img src="https://img.shields.io/nuget/v/Pain001.Sdk?style=for-the-badge&color=fc8d62&logo=nuget" alt="Registry" height="28" /></a> <a href="https://sebastienrousseau.github.io/pain001-sdk-dotnet/api/"><img src="https://img.shields.io/badge/docs-API%20reference-blue?style=for-the-badge&labelColor=555555&logo=dotnet" alt="Docs" height="28" /></a> <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/pain001-sdk-dotnet"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/pain001-sdk-dotnet?style=for-the-badge&label=OpenSSF%20Scorecard&logo=openssf" alt="OpenSSF Scorecard" height="28" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" height="28" /></a> <a href="https://github.com/sebastienrousseau/pain001-sdk-dotnet/blob/main/docs/POLICIES.md"><img src="https://img.shields.io/badge/.NET-10-93450a.svg?style=for-the-badge&logo=dotnet" alt=".NET 10 or later" height="28" /></a> </p>
<p align="center"> <img src="https://raw.githubusercontent.com/sebastienrousseau/pain001-sdk-dotnet/main/.github/demo.gif" alt="The Basic example using the .NET SDK against pain001 serve on loopback: health check, validation of the conformance kit's synthetic CSV, and generation of an XSD-valid pain.001.001.09 file" width="100%" /> </p>
Contents
Getting started
- Install: NuGet (
Pain001.Sdk), or a project reference from source - Requirements: toolchain floor, platforms
- Quick Start: generate a pain.001 file from a CSV in a few lines
The pain001-sdk-dotnet ecosystem
- The pain001-sdk-dotnet ecosystem: the pain001 server, its five SDKs and the conformance kit
Library reference
- Capabilities at a glance: the current surface by theme
- Ecosystem comparison: short matrix; full table at
docs/COMPARISON.md - Benchmarks: headline numbers; full table at
docs/BENCHMARKS.md - Features: module-level capability list
- Configuration: core options
- Examples: runnable example index
Operational
- When not to use pain001-sdk-dotnet: limitations
- Development: make targets, fuzzing, CI
- Security: guarantees and compliance
- Documentation: all reference docs
- Stability guarantees: SemVer axis, output stability, minimum toolchain discipline
- License
Install
As a .NET library
<PackageReference Include="Pain001.Sdk" Version="0.0.88" />
Or dotnet add package Pain001.Sdk --version 0.0.88. 0.0.88 is the
first release; until it is on NuGet, reference the project from a
clone:
<ProjectReference Include="path/to/pain001-sdk-dotnet/src/Pain001.Sdk/Pain001.Sdk.csproj" />
The SDK calls a running pain001 server, the Python package pain001
with its api extra:
pip install 'pain001[api]==0.0.88'
pain001 serve --host 127.0.0.1 --port 8000
Requirements
- .NET 10 (
net10.0), the supported LTS release (to November 2028). .NET 8 and .NET 9 reached end of support on 10 November 2026 and are not targeted (policy). - No other package: the library depends on the base class library only.
- A pain001 server reachable over HTTP. CI tests against pain001 0.0.88, the latest released core.
- CI builds and tests on Linux, Windows and macOS.
Quick Start
using Pain001.Sdk;
using var client = new Pain001Client(new Uri("http://127.0.0.1:8000"));
string csv = await File.ReadAllTextAsync("payments.csv");
try
{
UiGenerateResponse result = await client.GenerateAsync(csv, "payments.csv", MessageTypes.Pain001V09);
await File.WriteAllTextAsync("payments.xml", result.Xml);
}
catch (Pain001GenerationRefusedException refused)
{
foreach (RowError row in refused.Response.ValidationErrors ?? [])
{
Console.Error.WriteLine($"{row.Field}: {row.Message}");
}
}
The client posts the file's text to POST /api/v1/ui/generate; the
server parses it in memory, validates every row and returns the XML
inline. When the server refuses the data (a row fails validation or a
scheme rule), GenerateAsync raises Pain001GenerationRefusedException,
whose Response holds the findings; any other status outside 2xx raises
Pain001ApiException with the HTTP status and the server's detail.
The pain001-sdk-dotnet ecosystem
The pain001 server is the one engine. Each SDK is a thin typed client for its REST API, and the same conformance kit, vendored into every SDK, proves each client against a running server.
| Component | Purpose | Use case |
|---|---|---|
| pain001 | The engine: generates and validates pain.001 and pain.008, and serves the REST API | Run pain001 serve for this SDK to call |
| pain001-sdk-dotnet | This repository: the .NET client | Call the API from C#, F# or any .NET language |
| pain001-sdk-go, -java, -rust, -cpp | The same client surface in Go, Java, Rust and C++ | Call the API from those languages |
conformance/ |
The shared conformance kit, vendored from core | Prove this client against the server it describes |
Capabilities at a glance
| Area | Capability | Status |
|---|---|---|
| Health | HealthAsync: server status and version |
Available |
| Validation | ValidateAsync: row counts, row errors and scheme violations for a CSV, JSON or JSON Lines file |
Available |
| Generation | GenerateAsync: the XML document for a payment file; refusals with their findings |
Available |
| Checking | CheckAsync: the XSD, MDR, scheme and Schematron ladder on an existing document |
Available |
| Faces | FacesAsync, ProjectFaceAsync: project a pain.001 into another format, with a loss report |
Available |
| Low level | RequestAsync: any method and path, status and raw JSON |
Available |
| Resilience | Per-request timeout, cancellation, opt-in RetryPolicy for GET calls |
Available |
| Publication | NuGet package Pain001.Sdk |
Release workflow ready; first publication with 0.0.88 |
Ecosystem comparison
The suite's five SDKs share one method surface and run core's
conformance kit against a live pain001 serve in CI. Core's CI also
generates a Python client from the OpenAPI document, which it imports
but does not run against the kit.
| Project | Language (minimum) | Conformance kit in CI | Types |
|---|---|---|---|
| pain001-sdk-go | Go 1.26 | Yes | Hand-written |
| pain001-sdk-java | Java 17 | Yes | Hand-written |
| pain001-sdk-rust | Rust 1.85 | Yes | Hand-written (serde) |
| pain001-sdk-dotnet | .NET 10 | Yes | Hand-written |
| pain001-sdk-cpp | C++17 | Yes | Hand-written |
| openapi-generator client (core CI artifact) | Python | No, CI imports it only | Generated |
| Raw HTTP | Any | No | None |
See docs/COMPARISON.md for the evidence and complete matrix.
Benchmarks
What the SDK itself costs per call (request building and response
decoding with the kit's fixtures, no network) and one loopback round
trip to pain001 serve 0.0.87, measured with BenchmarkDotNet. The
client's own cost is microseconds; the round trip is the server's work.
| Scenario | Result | Environment |
|---|---|---|
GenerateAsync, client side |
30.9 μs, 28.7 KB allocated | Apple A18 Pro, macOS 27.2, .NET 10.0.15 |
ProjectFaceAsync, client side |
50.1 μs, 49.3 KB allocated | Apple A18 Pro, macOS 27.2, .NET 10.0.15 |
HealthAsync, client side |
1.9 μs, 2.8 KB allocated | Apple A18 Pro, macOS 27.2, .NET 10.0.15 |
GenerateAsync, loopback round trip |
55.6 ms mean, 49.7 ms median | Same machine, pain001 serve 0.0.87 on 127.0.0.1 |
ValidateAsync, loopback round trip |
11.8 ms mean, 10.0 ms median | Same machine, pain001 serve 0.0.87 on 127.0.0.1 |
See docs/BENCHMARKS.md for methodology and full results.
Features
Pain001Client: one async method per endpoint, each taking aCancellationToken. Construct it with your ownHttpClient(forIHttpClientFactory) or with a base address alone.- Typed responses:
HealthResponse,ValidationResponse,UiGenerateResponse,CheckResponse,FaceInfo,FaceResponseandLossReport, mapped from the server's snake_case JSON. Row errors in a payment file areRowError(field,message,value); the items of an HTTP 422detaildeserialize asValidationError. MessageTypes: constants for the 13 message types the server lists. Every method takes the message type as a string, so a newer server's types work before this list knows them.- Errors by cause (ADR 0003):
Pain001ApiException(a status outside 2xx, withStatusCodeandDetail);Pain001GenerationRefusedException, derived from it, for a refused generate call, with the findings inResponse;Pain001NoDocumentExceptionfor a 2xx generate answer without the XML, so a returned result always has it. Messages never carry the detail or a finding. RetryPolicy: opt-in retries forGETcalls only, off by default (ADR 0004).RequestAsync: the low-level call the conformance runner uses. It returns any status instead of throwing.- No logging, and no third-party runtime dependency.
Configuration
var options = new Pain001ClientOptions
{
BaseAddress = new Uri("https://pain001.internal.example"),
ApiKey = Environment.GetEnvironmentVariable("PAIN001_API_KEY"),
Timeout = TimeSpan.FromSeconds(10),
Retry = new RetryPolicy { MaxAttempts = 3 },
};
using var client = new Pain001Client(httpClient, options);
| Option | Default | Meaning |
|---|---|---|
BaseAddress |
http://127.0.0.1:8000 |
The server's absolute address; a path prefix is kept |
ApiKey |
none | Sent as Authorization: Bearer <key> |
Timeout |
30 seconds | Per request; exceeding it raises TimeoutException |
Retry |
none | A RetryPolicy for GET calls only (health, faces, a raw GET): MaxAttempts (3), InitialDelay (200 ms), MaxDelay (5 s); retries 429, 503 and connection errors with jittered exponential backoff, honouring Retry-After. A POST is never retried |
TimeProvider |
TimeProvider.System |
The clock for retry waits and Retry-After dates |
The client never changes the settings of an HttpClient you pass in,
and does not dispose it.
Examples
Each example is a console project that checks its own result. CI runs
every one against pain001 serve (scripts/run-examples.sh); run them
from the repository root, with PAIN001_BASE_URL pointing at a server
(default http://127.0.0.1:8000) and, optionally, PAIN001_API_KEY.
| Example | Shows | Run it |
|---|---|---|
Basic |
Health, validation and generation in one go: the README demo | dotnet run --project examples/Basic |
Health |
HealthAsync: server status and version |
dotnet run --project examples/Health |
Validate |
ValidateAsync: row counts, a rejected IBAN (HTTP 400), the uk-chaps scheme's violations |
dotnet run --project examples/Validate |
Generate |
GenerateAsync: write the XML to a file |
dotnet run --project examples/Generate -- out.xml |
Check |
CheckAsync: the validation ladder on an existing document |
dotnet run --project examples/Check |
Faces |
FacesAsync: the faces and their bindings |
dotnet run --project examples/Faces |
ProjectFace |
ProjectFaceAsync: a face payload and its loss report |
dotnet run --project examples/ProjectFace -- berlin_group |
RawRequest |
RequestAsync: any method and path, status returned, never thrown |
dotnet run --project examples/RawRequest |
ErrorHandling |
Pain001GenerationRefusedException, Pain001ApiException and Pain001NoDocumentException, caught in the right order |
dotnet run --project examples/ErrorHandling |
Timeouts |
Timeout, a CancellationToken and the opt-in RetryPolicy |
dotnet run --project examples/Timeouts |
ApiKey |
ApiKey sent as a bearer token; a wrong key refused with HTTP 401 |
PAIN001_API_KEY=... dotnet run --project examples/ApiKey |
When not to use pain001-sdk-dotnet
- You cannot run the pain001 server. This SDK does not generate or
validate anything itself; every call goes to
pain001 serve. - You need a framework older than .NET 10. The package targets
net10.0only. - You need payment calls retried. The opt-in
RetryPolicycoversGETcalls only; the SDK never resends aPOST(validate, generate, check, a face projection). Add your own policy if you need one, knowing a retried generation is a second request. - You want an offline ISO 20022 library. Use the server, or a library that builds the XML in process; this is a client.
Development
make check # format, build (analysers, complexity), 100% coverage, audit, versions, Halstead
make conformance # the kit and typed tests; needs PAIN001_BASE_URL
make examples # run every example against PAIN001_BASE_URL
make bench # BenchmarkDotNet; loopback too when PAIN001_BASE_URL is set
make regression # all of it against a server it installs and starts
make docs # the manual, strict, with the API reference
make docs-lint # markdownlint, codespell, REUSE
The build treats warnings as errors with the latest-recommended .NET
analysers; CA1502 and SonarAnalyzer hold every method to cyclomatic
complexity 10, cognitive complexity 15 and 60 lines, and
scripts/halstead.py to Halstead difficulty 30. Unit tests run under
coverlet and fail below 100 % line and branch coverage; FsCheck
properties drive every method with arbitrary server answers. There are
no fuzz targets: the client parses only JSON, through
System.Text.Json, and the properties cover its decoding. CI runs
format, build and tests on Linux, Windows and macOS, the
vulnerable-package audit, the conformance kit, every example and a
benchmark smoke run against a hash-pinned pain001 serve.
DEVELOPMENT.md maps every gate to its local command.
Security
The SDK logs nothing and never puts a request body in an exception
message, because request bodies hold payment data: an exception's
message names the status (and, for a refusal, the count of findings),
while the server's detail stays in Detail and Response. It has no
third-party runtime dependency, sends the API key only as a bearer
token to the configured server, bounds every request with a timeout,
and never retries a POST. A response that is not JSON, or not valid
UTF-8, becomes a string, never an exception from inside the parser.
Report vulnerabilities according to SECURITY.md.
Documentation
- User manual,
built from
docs/. - API reference, generated from the XML documentation comments, which also ship in the package for IDE tooltips.
- Developer docs: toolchain, every CI gate, test layout, release model.
- Ecosystem map: the suite's SDKs side by side.
conformance/README.md: the conformance kit and its case format.
Stability guarantees
The version is 0.0.x and moves by 0.0.1 in lockstep with the pain001
suite; before 1.0 any release may change the API, and the
CHANGELOG says how. Each release runs package validation
(ApiCompat) against the previous published package, so no break is
accidental. Output stability: the same server answer decodes to the same
records and raises the same exception types; a change to that mapping
is breaking even when no signature moves. SDK version 0.0.N vendors the
conformance kit from core 0.0.N, and CI fails if any case fails against
the server. The net10.0 floor moves only with a release that says so
(policy).
License
Dual-licensed under Apache-2.0 or MIT, at your option. See LICENSE. Every file carries its licence in machine-readable form (REUSE, checked in CI).
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.0.88 | 50 | 11/15/2026 |