Skip to content

Getting started

1. Run a server

The SDK calls pain001 serve, the REST API of the Python package pain001. Install it with its api extra and start it on loopback:

pip install 'pain001[api]==0.0.88'
pain001 serve --host 127.0.0.1 --port 8000

GET http://127.0.0.1:8000/api/v1/health answers {"status":"healthy",...} once it is up. For any server that is not on loopback, set PAIN001_API_KEY on the server and pass the same key to the client.

2. Add the package

dotnet add package Pain001.Sdk --version 0.0.88

Until the first release is on NuGet, reference the project from a clone instead:

<ItemGroup>
  <ProjectReference Include="path/to/pain001-sdk-dotnet/src/Pain001.Sdk/Pain001.Sdk.csproj" />
</ItemGroup>

The package targets net10.0 and has no dependency of its own.

3. Make a call

using Pain001.Sdk;

using var client = new Pain001Client(new Uri("http://127.0.0.1:8000"));

HealthResponse health = await client.HealthAsync();
Console.WriteLine($"pain001 {health.Version}: {health.Status}");

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)
{
    // The server refused the data; the findings are in refused.Response.
    Console.Error.WriteLine(refused.Message);
}

4. Configure it for production

var options = new Pain001ClientOptions
{
    BaseAddress = new Uri("https://pain001.internal.example"),
    ApiKey = Environment.GetEnvironmentVariable("PAIN001_API_KEY"),
    Timeout = TimeSpan.FromSeconds(10),
    Retry = new RetryPolicy(), // GET calls only; off when left null
};
using var client = new Pain001Client(httpClientFromYourFactory, 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; past it the call raises TimeoutException
Retry none A RetryPolicy for GET calls; a POST is never retried
TimeProvider TimeProvider.System The clock for retry waits

The client never changes an HttpClient you pass in and does not dispose it. Errors are described in ADR 0003, retries in ADR 0004.