SilverDotPay SDK

Typed .NET client for the SilverDotPay payment gateway.

Install

dotnet add package SilverLabs.SilverDotPay.Sdk

The SilverLABS NuGet feed must be configured. In nuget.config:

<add key="silverlabs" value="https://nuget.silverlabs.uk/v3/index.json" />

Quick start

services.AddSilverDotPaySdk(opts =>
{
    opts.BaseAddress = "https://silverdotpay.silverlabs.uk";
    opts.Mode = SilverDotPayClientMode.ApiKey;
    opts.ApiKey = configuration["SilverDotPay:ApiKey"];
    opts.Timeout = TimeSpan.FromSeconds(30);
})
.AddPublicClient()      // ICurrenciesClient + exchange rates, no auth
.AddMerchantClient()    // orders, balances, withdrawals, webhooks
.AddAdminClient()       // applications, keys, secrets, escrow, settings
.AddCardClient();       // card rail: charge-saved, setup, saved cards (1.3.0)

Then inject any of:

• ISilverDotPayClient — narrow legacy surface (order create, get, escrow release/refund) — used by Crowding-style integrations.
• ISilverDotPayPublicClient — currencies, exchange rates. No auth.
• ISilverDotPayMerchantClient — orders, my balance, withdrawals, webhook config.
• ISilverDotPayAdminClient — applications, API keys, webhook secret rotation, balances, escrow, settings.
• ISilverDotPayCardClient — card rail: rail status, charge saved card, setup-mode capture, list/remove saved cards.

Auth modes

Pick one per HttpClient:

• SilverDotPayClientMode.ApiKey — sets X-API-Key header from opts.ApiKey. Used by service accounts and admin keys.
• SilverDotPayClientMode.PassportBearer — forwards a Passport SSO token from a pluggable ITokenSource. Used in ASP.NET Core hosts where the inbound user's token is propagated downstream.

Inbound webhook validation

services.AddSingleton<ISilverDotPayWebhookValidator>(sp =>
    new SilverDotPayWebhookValidator(secret: cfg["SilverDotPay:WebhookSecret"], logger));

Validator parses X-SilverDotPay-Signature: t=<unix>,v1=<hex>, recomputes HMAC-SHA256("<unix>.<raw body>", secret), and rejects if the timestamp falls outside a 5-minute replay window. Fails closed when no secret is configured.

See docs/WEBHOOKS.md in the silverdotpay repo for the wire format.

Card rail (1.3.0)

• Card checkout: CreateOrderAsync with Rail = SilverDotPayRail.Card, GBP Amount, BuyerIdentifier (tenant id), SuccessUrl, CancelUrl; redirect the buyer to CreateOrderResponse.PaymentUrl. The card is saved for renewals.
• payment_confirmed carries payment_method.ref — store it and pass it as PaymentMethodRef to ISilverDotPayCardClient.ChargeSavedAsync for renewals (optionally with BuyerIdentifier as an ownership check). Use a new ExternalOrderId per attempt; reuse it only to retry the same attempt (never double-charges).
• ChargeSavedResponse.Status is one of SilverDotPayChargeStatus. processing means the outcome is unknown: do not treat it as failed and do not start another attempt; reconcile via POST /api/orders/{id}/reconcile.
• payment_failed carries failure.reason (SilverDotPayFailureReason) and, for authentication_required, failure.action_url — send the customer there to authenticate.
• payment_method_saved (setup mode) has no order; key it on payment_method.buyer_identifier.
• A 503 (SilverDotPayException.StatusCode == 503) or GetCardRailStatusAsync().IsConfigured == false means cards are not configured for this application: hide the card option.

Versioning

SemVer. Major versions track breaking API contract changes on the silverdotpay backend.