Winglet.Payment.Client 0.1.0

Winglet.Payment.Client

Winglet.Payment.Client is the service-owned typed client for the Payment source API. It uses the shared Winglet.Client infrastructure for endpoint configuration, service authentication, tenant/global token scope, canonical errors, correlation and resilience.

Install Winglet.Payment.Client together with the matching Winglet.Payment.Contracts package. The client depends on the released Winglet.Client package; applications do not need a second transport client.

Registration

services.AddWingletPaymentClient(configuration);

Configure the endpoint as:

Winglet:Clients:Payment:BaseUrl

The value must be an absolute HTTP or HTTPS URI without credentials.

Scope

The client exposes only the Payment source API:

• POST /api/v1/payments
• GET /api/v1/payments/{paymentId}
• POST /api/v1/payments/{paymentId}/cancel

It does not expose payment sessions, provider callbacks, FakeProvider controls, operations, reconciliation, provider configuration, source event receivers, refunds or Checkout concepts.

Authentication and tenant scope

All operations require ServiceOnly authentication. The caller cannot select OnBehalfOf mode. A call context with a non-null TenantId requests the Tenant scope; a context without a tenant requests the Global scope. Source identity comes from the service token and is never included in a request body.

var created = await paymentClient.CreatePaymentAsync(
    new CreatePaymentRequest(
        SourceOperationId: "checkout-order-42",
        Amount: 19.95m,
        Currency: "EUR",
        Profile: "default"),
    new PaymentClientCallContext(tenantId: "tenant-7"),
    cancellationToken);

sourceOperationId and cancellation operationId belong to the caller. The client never generates or changes them, including when the caller retries an operation.

Contracts and errors

All three source operations use Winglet.Payment.Contracts.PaymentResponse. The contracts package contains only the stable source wire records and enums; it does not expose Payment server entities, provider configuration or state-machine methods. Money uses decimal and references retain non-unique semantics.

Canonical remote Problem Details are surfaced as Winglet.Client's WingletRemoteApiException. Transport and malformed-success responses use WingletTransportException and WingletProtocolException. The client does not create a Payment-specific exception hierarchy.

Retry and cancellation

GET uses Winglet.Client's bounded safe-method retry. POST operations are not blindly retried by default. A caller may retry a failed create or cancellation with the exact same request and operation identifier because server-side idempotency owns those guarantees. Caller CancellationToken is passed through HTTP send and response deserialization.

Payment session tokens are returned when the server supplies one, but the client does not store, cache, log or use them for session operations.