NordAPI.Swish 1.0.5

NordAPI.Swish SDK

Production notice In-memory nonce store is for development only. In production you must use a persistent store (Redis/DB). Set SWISH_REDIS (or REDIS_URL / SWISH_REDIS_CONN). The sample fails fast in Production if none is set.

Licensing notice: NordAPI is an SDK. You need your own Swish/BankID production agreements and certificates. NordAPI does not provide them.

Official NordAPI SDK for Swish and upcoming BankID integrations.

🇸🇪 Swedish version: README.sv.md ✅ See also: Integration Checklist

A lightweight and secure .NET SDK for integrating Swish payments and refunds, with a focus on safe test and development workflows. Includes built-in HMAC signing, optional mTLS, and retry/rate limiting via HttpClientFactory. 💡 BankID SDK support is planned next — stay tuned for the NordAPI.BankID package.

Supported .NET versions: .NET 8 (LTS). Planned: .NET 10 (LTS) support.

📚 Table of Contents

• Requirements
• Installation
• Quickstart — Minimal Program.cs
• Usage Example: Creating a Payment
• Typical Swish Flow (high-level)
• Configuration — Environment Variables & User-Secrets
• mTLS (optional)
• Running Samples and Tests
• Webhook Smoke Test
• API Overview (Signatures & Models)
• Error Scenarios & Retry Policy
• Security Recommendations
• Contributing (PR/CI Requirements)
• Release & Versioning
• FAQ
• License

Requirements

• .NET 8+ (SDK and Runtime)
• Windows / macOS / Linux
• (Optional) Redis if you want distributed replay protection for webhooks

Installation

Install from NuGet:

dotnet add package NordAPI.Swish

Or via PackageReference in .csproj:

<ItemGroup>
  <PackageReference Include="NordAPI.Swish" />
</ItemGroup>

Tip: omit a fixed version to pull the latest stable. Pin a concrete version in production deployments.

Quickstart — Minimal Program.cs

This block is compilable as a full file in a new web project (dotnet new web). File: Program.cs

using System;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using NordAPI.Swish;
using NordAPI.Swish.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Register the Swish client using environment variables
// NOTE (Quickstart): uses simple dev fallbacks; in production, use secrets and remove fallbacks.
builder.Services.AddSwishClient(opts =>
{
    opts.BaseAddress = new Uri(Environment.GetEnvironmentVariable("SWISH_BASE_URL")
        ?? "https://example.invalid");
    opts.ApiKey = Environment.GetEnvironmentVariable("SWISH_API_KEY")
        ?? "dev-key";
    opts.Secret = Environment.GetEnvironmentVariable("SWISH_SECRET")
        ?? "dev-secret";
});

var app = builder.Build();

app.MapGet("/ping", async (ISwishClient swish) =>
{
    var result = await swish.PingAsync();
    return Results.Ok(new { ping = result });
});

app.Run();

Run:

dotnet new web -n SwishQuickStart
cd SwishQuickStart
dotnet add package NordAPI.Swish
# Replace Program.cs content
dotnet run

Usage Example: Creating a Payment

Replace payeeAlias with your Swish merchant number (MSISDN without “+”). Signatures and model names match the API Overview below.

using Microsoft.AspNetCore.Mvc;

// Minimal API endpoint that creates a payment using the SDK model
app.MapPost("/payments", async ([FromBody] CreatePaymentRequest input, ISwishClient swish, CancellationToken ct) =>
{
    // Tip: validate Amount/Currency/aliases before calling Swish
    var payment = await swish.CreatePaymentAsync(input, ct);
    return Results.Ok(payment);
});

Example request body

{
  "payerAlias": "46701234567",
  "payeeAlias": "1231181189",
  "amount": "100.00",
  "currency": "SEK",
  "message": "Test purchase",
  "callbackUrl": "https://yourdomain.test/webhook/swish"
}

curl

curl -v -X POST http://localhost:5000/payments \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-raw '{
    "payerAlias": "46701234567",
    "payeeAlias": "1231181189",
    "amount": "100.00",
    "currency": "SEK",
    "message": "Test purchase",
    "callbackUrl": "https://yourdomain.test/webhook/swish"
  }'

In production, the flow is asynchronous: Swish will notify your backend via the webhook (callbackUrl). See the smoke test for signature details.

Typical Swish Flow (high-level)

1) Client (web/app)
        |
        v
2) Your Backend
        |
        v
3) Swish API
        |
        v
4) User approves payment in Swish app
        |
        v
5) Swish sends callback (payment result)
        |
        v
6) Your Webhook endpoint
        |
        v
   Update order status / notify client

• Your backend creates the payment via CreatePaymentAsync.
• The end-user approves in the Swish app.
• Swish POSTs the result to your webhook (callbackUrl). Your webhook must verify HMAC (X-Swish-Signature) as Base64 HMAC-SHA256 of "<ts>\n<nonce>\n<body>" (UTF-8).

Configuration — Environment Variables & User-Secrets

Set with User-Secrets (example):

dotnet user-secrets init
dotnet user-secrets set "SWISH_API_KEY" "dev-key"
dotnet user-secrets set "SWISH_SECRET" "dev-secret"
dotnet user-secrets set "SWISH_BASE_URL" "https://example.invalid"

🔒 Never commit secrets or certificates. Use environment variables, User-Secrets, or a vault (e.g., Azure Key Vault).

mTLS (optional)

Enable client certificate (PFX):

$env:SWISH_PFX_PATH = "C:\certs\swish-client.pfx"
$env:SWISH_PFX_PASSWORD = "secret-password"

Behavior

• No certificate → fallback without mTLS.
• Debug: relaxed server certificate validation (local only).
• Release: strict certificate chain (no “allow invalid chain”).

Running Samples and Tests

# Build the repository
dotnet restore
dotnet build

# Run the sample web app
dotnet run --project .\samples\SwishSample.Web\SwishSample.Web.csproj --urls http://localhost:5000

# Run tests
dotnet test

Webhook Smoke Test

Start the sample server in one terminal:

$env:SWISH_WEBHOOK_SECRET = "dev_secret"
dotnet run --project .\samples\SwishSample.Web\SwishSample.Web.csproj --urls http://localhost:5000

Run the smoke test in another terminal:

.\scripts\smoke-webhook.ps1 -Secret dev_secret -Url http://localhost:5000/webhook/swish

For quick manual testing you can also POST the webhook using curl (bash/macOS/Linux). Signature spec: HMAC-SHA256 over the canonical string "<timestamp>\n<nonce>\n<body>", using SWISH_WEBHOOK_SECRET. Encode as Base64.

🧩 Note: Sign the exact UTF‑8 bytes of the compact JSON body (Content-Type: application/json; charset=utf-8). Any whitespace or prettifying will break signature verification.

Required request headers

Example webhook payload

{
  "event": "payment_received",
  "paymentId": "pay_123456",
  "amount": "100.00",
  "currency": "SEK",
  "payer": { "phone": "46701234567" },
  "metadata": { "orderId": "order_987" }
}

curl smoke test (bash / macOS / Linux)

# 1) Prepare values
ts="$(date +%s)"
nonce="$(uuidgen)"
body='{"event":"payment_received","paymentId":"pay_123456","amount":"100.00","currency":"SEK","payer":{"phone":"46701234567"},"metadata":{"orderId":"order_987"}}'

# 2) Compute canonical and Base64 signature (uses SWISH_WEBHOOK_SECRET)
canonical="$(printf "%s\n%s\n%s" "$ts" "$nonce" "$body")"
sig="$(printf "%s" "$canonical" | openssl dgst -sha256 -hmac "${SWISH_WEBHOOK_SECRET:-dev_secret}" -binary | openssl base64)"

# 3) Send
curl -v -X POST "http://localhost:5000/webhook/swish" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Swish-Timestamp: $ts" \
  -H "X-Swish-Nonce: $nonce" \
  -H "X-Swish-Signature: $sig" \
  --data-raw "$body"

✅ Expected (HTTP 200)

{"received": true}

❌ Expected on replay (HTTP 409)

{"reason": "replay detected (nonce seen before)"}

In production: set SWISH_REDIS (aliases REDIS_URL and SWISH_REDIS_CONN are accepted). Without Redis, an in-memory store is used (suitable for local development).

API Overview (Signatures & Models)

The types below illustrate the expected surface. Names/namespaces should match the library you reference.

public interface ISwishClient
{
    Task<string> PingAsync(CancellationToken ct = default);

    Task<CreatePaymentResponse> CreatePaymentAsync(CreatePaymentRequest request, CancellationToken ct = default);
    Task<CreatePaymentResponse> GetPaymentStatusAsync(string paymentId, CancellationToken ct = default);

    Task<CreateRefundResponse> CreateRefundAsync(CreateRefundRequest request, CancellationToken ct = default);
    Task<CreateRefundResponse> GetRefundStatusAsync(string refundId, CancellationToken ct = default);
}

public sealed record CreatePaymentRequest(
    string PayerAlias,
    string PayeeAlias,
    string Amount,
    string Currency,
    string Message,
    string CallbackUrl
);

public sealed record CreatePaymentResponse(
    string Id,
    string Status,
    string? ErrorCode = null,
    string? ErrorMessage = null
);

public sealed record CreateRefundRequest(
    string OriginalPaymentReference,
    string Amount,
    string Currency,
    string Message,
    string CallbackUrl
);

public sealed record CreateRefundResponse(
    string Id,
    string Status,
    string? ErrorCode = null,
    string? ErrorMessage = null
);

Error Scenarios & Retry Policy

The SDK registers a named HttpClient "Swish" with:

• Timeout: 30 seconds
• Retry: up to 3 attempts (exponential backoff + jitter) on 408, 429, 5xx, HttpRequestException, TaskCanceledException (timeout).

Enable/extend:

services.AddSwishHttpClient(); // registers "Swish" (timeout + retry + mTLS if env vars exist)
services.AddHttpClient("Swish")
        .AddHttpMessageHandler(_ => new MyCustomHandler()); // outside SDK retry-pipeline

Common responses:

• 400 Bad Request → validation error (check required fields).
• 401 Unauthorized → invalid SWISH_API_KEY/SWISH_SECRET or missing headers.
• 429 Too Many Requests → follow retry policy/backoff.
• 5xx → transient; retry automatically triggered by pipeline.

Security Recommendations

• Use User-Secrets / Key Vault for secrets — never hardcode in code or commit to the repo.
• mTLS “allow invalid chain” must only be used locally (Debug). In production, enforce a valid chain.
• Webhook secret (SWISH_WEBHOOK_SECRET) should be rotated regularly and stored securely (e.g., Key Vault).

Contributing (PR/CI Requirements)

1. Create a feature branch from main.
2. Verify locally: dotnet build, dotnet test, and webhook smoke test if modified.
3. Ensure README examples compile (Quickstart must be copy-paste runnable).
4. Open PR with description + checklist. CI must pass:
   • Build & tests green
   • (Optional) Lint/format
5. Code review → squash/merge.

Release & Versioning

• SemVer: MAJOR.MINOR.PATCH
• CI publish is gated; tag the repo (e.g., v1.0.0) to publish to NuGet.
• The README in the package (PackageReadmeFile) is shown on NuGet.

Install a specific version:

dotnet add package NordAPI.Swish --version 1.2.3

FAQ

401 in tests — Check SWISH_API_KEY/SWISH_SECRET and ensure your clock is synchronized. Replay always denied — Change nonce between calls and clear in-memory/Redis. Check SWISH_REDIS. mTLS error in production — Validate SWISH_PFX_PATH + SWISH_PFX_PASSWORD and the certificate chain.

License

MIT License. Security contact: security@nordapi.com.

Last updated: November 2025