Pain001.Sdk 0.0.88

dotnet add package Pain001.Sdk --version 0.0.88
                    
NuGet\Install-Package Pain001.Sdk -Version 0.0.88
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Pain001.Sdk" Version="0.0.88" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Pain001.Sdk" Version="0.0.88" />
                    
Directory.Packages.props
<PackageReference Include="Pain001.Sdk" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Pain001.Sdk --version 0.0.88
                    
#r "nuget: Pain001.Sdk, 0.0.88"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Pain001.Sdk@0.0.88
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Pain001.Sdk&version=0.0.88
                    
Install as a Cake Addin
#tool nuget:?package=Pain001.Sdk&version=0.0.88
                    
Install as a Cake Tool

<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

Library reference

Operational


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 a CancellationToken. Construct it with your own HttpClient (for IHttpClientFactory) or with a base address alone.
  • Typed responses: HealthResponse, ValidationResponse, UiGenerateResponse, CheckResponse, FaceInfo, FaceResponse and LossReport, mapped from the server's snake_case JSON. Row errors in a payment file are RowError (field, message, value); the items of an HTTP 422 detail deserialize as ValidationError.
  • 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, with StatusCode and Detail); Pain001GenerationRefusedException, derived from it, for a refused generate call, with the findings in Response; Pain001NoDocumentException for 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 for GET calls 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.0 only.
  • You need payment calls retried. The opt-in RetryPolicy covers GET calls only; the SDK never resends a POST (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


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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • 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