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. |