Skip to content

Pain001Client

Namespace Pain001.Sdk.

A typed client for the pain001 REST API (pain001 serve).

Remarks

Every call is one HTTP request unless Pain001ClientOptions.Retry is set, and then only a GET is retried; request bodies are never logged, because they hold payment data. A status outside 2xx raises Pain001ApiException (a Pain001GenerationRefusedException, with the findings, when Pain001Client.GenerateAsync is refused), except from Pain001Client.RequestAsync, which returns it.

Methods

Pain001Client(HttpClient, Pain001ClientOptions)

Creates a client that sends its requests through http, which the caller owns and disposes. The client never changes the HttpClient's own settings.

Parameter Description
http The HTTP client to send requests with.
options The server address, API key and timeout.
Exception When
ArgumentException The base address is not absolute, or the timeout is not positive.

Pain001Client(Uri, String)

Creates a client with its own HttpClient, disposed with the client, and the default 30-second timeout.

Parameter Description
baseAddress The server's absolute base address.
apiKey The API key, or null.
Exception When
ArgumentException The base address is not absolute.

CheckAsync(String, String, String, CancellationToken)

Runs the validation ladder on an existing pain.001 or pain.008 document (POST /api/v1/check).

Parameter Description
xml The document as XML text.
scheme Scheme profiles to add, comma-separated, or null.
schematron A Schematron preset to add (sepa, fednow, cbpr), or null.
cancellationToken Cancels the request.

Returns: The verdict, the rungs that ran and every finding.

Exception When
Pain001ApiException The server answered outside 2xx, HTTP 422 when the document cannot be checked.

Dispose()

Disposes the HttpClient when this client created it; a caller's HttpClient is left alone.

FacesAsync(CancellationToken)

Lists the faces (GET /api/v1/faces).

Parameter Description
cancellationToken Cancels the request.

Returns: One entry per face, sorted by name.

Exception When
Pain001ApiException The server answered outside 2xx.

GenerateAsync(String, String, String, String, CancellationToken)

Generates the XML document from a payment file (POST /api/v1/ui/generate).

Parameter Description
content The file's text: CSV, JSON or JSON Lines.
filename The file name; only its suffix picks the parser.
messageType The message type, for example MessageTypes.Pain001V09.
scheme Scheme rulebooks to enforce, comma-separated, or null.
cancellationToken Cancels the request.

Returns: The generated XML and its suggested file name.

Exception When
Pain001GenerationRefusedException The server refused the data (HTTP 422 with success: false); its Pain001GenerationRefusedException.Response holds the findings.
Pain001ApiException The server answered outside 2xx for another reason, for example HTTP 422 for an unknown message type.
Pain001NoDocumentException The server answered 2xx without the XML (a server older than pain001 0.0.87, or a broken one).

HealthAsync(CancellationToken)

Checks the server is up (GET /api/v1/health).

Parameter Description
cancellationToken Cancels the request.

Returns: The server's status and version.

Exception When
Pain001ApiException The server answered outside 2xx.

ProjectFaceAsync(String, String, String, IReadOnlyDictionary<String,Object>, CancellationToken)

Projects a pain.001 document into a face (POST /api/v1/faces/{face}).

Parameter Description
face The face name, one of Pain001Client.FacesAsync.
xml The pain.001 document as XML text.
version The pain.001 edition, or null to detect it from the namespace.
bindings Side inputs the message does not carry, or null.
cancellationToken Cancels the request.

Returns: The payload and its loss report.

Exception When
Pain001ApiException The server answered outside 2xx, HTTP 404 for an unknown face, 422 when the face refuses the input.

RequestAsync(String, String, JsonNode, CancellationToken)

Sends one request and returns its status and parsed body, whatever the status. This is the low-level call the conformance kit runs through.

Parameter Description
method The HTTP method, for example GET.
path The path from the base address, starting with /, for example /api/v1/health.
body The JSON body, or null for none.
cancellationToken Cancels the request.

Returns: The status code and parsed body.

Exception When
ArgumentException The path does not start with /.

ValidateAsync(String, String, String, String, CancellationToken)

Validates a payment file without generating XML (POST /api/v1/ui/validate).

Parameter Description
content The file's text: CSV, JSON or JSON Lines.
filename The file name; only its suffix picks the parser.
messageType The message type, for example MessageTypes.Pain001V09.
scheme Scheme rulebooks to enforce, comma-separated, or null.
cancellationToken Cancels the request.

Returns: The row counts and every error.

Exception When
Pain001ApiException The server answered outside 2xx, for example HTTP 400 for a row it rejects.

All types