curl -X POST "{{BASE_URL}}/api/transactions" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "Sale",
    "cardData": {
      "cardNumber": "4111111111111111",
      "nameOnCard": "Jane Doe",
      "expirationMonth": 12,
      "expirationYear": 2030,
      "cvv": 123
    },
    "invoiceData": {
      "amounts": { "base": 10.00, "total": 10.00 }
    }
  }'

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };
http.DefaultRequestHeaders.Add("api-key", "{{API_KEY}}");

var response = await http.PostAsJsonAsync("/api/transactions", new
{
    transactionType = "Sale",
    cardData = new
    {
        cardNumber = "4111111111111111",
        nameOnCard = "Jane Doe",
        expirationMonth = 12,
        expirationYear = 2030,
        cvv = 123
    },
    invoiceData = new
    {
        amounts = new { @base = 10.00m, total = 10.00m }
    }
});

response.EnsureSuccessStatusCode();

var sale = await response.Content.ReadFromJsonAsync<JsonElement>();
var merchantId = sale.GetProperty("merchantId").GetString();

curl -X POST "{{BASE_URL}}/api/hostedpaymentpages" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "{{merchantId}}",
    "name": "Online checkout",
    "isActive": true,
    "allowCustomAmount": false,
    "successRedirectUrl": "https://example.test/thank-you"
  }'

var page = await http.PostAsJsonAsync("/api/hostedpaymentpages", new
{
    merchantId,
    name = "Online checkout",
    isActive = true,
    allowCustomAmount = false,
    successRedirectUrl = "https://example.test/thank-you"
});

page.EnsureSuccessStatusCode();

var created = await page.Content.ReadFromJsonAsync<JsonElement>();
var hostedPageId = created.GetProperty("id").GetString();

curl -X POST "{{BASE_URL}}/api/hostedpaymentpages/sessions" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "hostedPageId": "{{hostedPageId}}",
    "label": "Order 1042",
    "expirySeconds": 900
  }'

var session = await http.PostAsJsonAsync("/api/hostedpaymentpages/sessions", new
{
    hostedPageId,
    label = "Order 1042",
    expirySeconds = 900
});

session.EnsureSuccessStatusCode();

var opened = await session.Content.ReadFromJsonAsync<JsonElement>();
var sessionId = opened.GetProperty("sessionId").GetString();

curl "{{BASE_URL}}/api/hostedpaymentpages/sessions/{{sessionId}}/payment-link" \
  -H "api-key: {{API_KEY}}"

HTTP/1.1 303 See Other
Location: {{paymentLinkUrl}}

using System;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

namespace WinkPG.DeveloperPortal.Webhooks;

/// <summary>
/// Verifies the <c>X-WinkPG-Signature</c> header on an inbound webhook delivery.
/// Copy this into your receiver: it depends on nothing but the base class library.
/// </summary>
public static class WebhookSignatureVerification
{
    /// <summary>Prefix of the version 1 signature scheme.</summary>
    public const string SignaturePrefix = "v1=sha256:";

    /// <summary>
    /// Separator between signature entries. The header carries more than one entry while the
    /// endpoint's signing secret is being rotated.
    /// </summary>
    public const char SignatureSeparator = ',';

    /// <summary>Recommended clock-skew tolerance for the replay window.</summary>
    public static readonly TimeSpan DefaultTolerance = TimeSpan.FromMinutes(5);

    /// <summary>Smallest UNIX-epoch second <see cref="DateTimeOffset"/> can represent.</summary>
    private static readonly long MinUnixSeconds = DateTimeOffset.MinValue.ToUnixTimeSeconds();

    /// <summary>Largest UNIX-epoch second <see cref="DateTimeOffset"/> can represent.</summary>
    private static readonly long MaxUnixSeconds = DateTimeOffset.MaxValue.ToUnixTimeSeconds();

    /// <summary>
    /// Returns true when <paramref name="signatureHeader"/> is a valid signature over
    /// <paramref name="rawBody"/> for the destination's <paramref name="secretKey"/>, and the
    /// delivery is inside the replay window.
    /// </summary>
    /// <remarks>
    /// The header can carry more than one signature, separated by commas, while the endpoint's secret
    /// is being rotated: one entry per secret the platform is currently signing with, the outgoing
    /// one first. Verification succeeds when <em>any</em> entry matches your secret, which is what
    /// lets you keep verifying with the secret you hold while you switch to the new one. A header
    /// with a single entry is the ordinary case and takes the same path.
    /// </remarks>
    /// <param name="signatureHeader">The <c>X-WinkPG-Signature</c> header value.</param>
    /// <param name="timestampHeader">The <c>X-WinkPG-Timestamp</c> header value, UNIX epoch seconds.</param>
    /// <param name="rawBody">The request body exactly as received. Never re-serialize it first.</param>
    /// <param name="secretKey">The destination's shared secret.</param>
    /// <param name="now">The current time. Pass your clock so this stays testable.</param>
    /// <param name="tolerance">Replay window; defaults to five minutes either side.</param>
    public static bool IsValid(
        string? signatureHeader,
        string? timestampHeader,
        byte[] rawBody,
        string secretKey,
        DateTimeOffset now,
        TimeSpan? tolerance = null)
    {
        if (rawBody is null || string.IsNullOrEmpty(secretKey) || timestampHeader is null)
        {
            return false;
        }

        if (!IsInsideReplayWindow(timestampHeader, now, tolerance))
        {
            return false;
        }

        if (signatureHeader is null)
        {
            return false;
        }

        var expected = ComputeSignature(secretKey, timestampHeader, rawBody);

        // Every entry is checked, and the result is accumulated rather than returned early, so the
        // work done does not depend on which entry matched or on how many were present. Returning as
        // soon as one verifies would leak the position of your secret in the header through timing,
        // which during a rotation is the difference between "this receiver still holds the outgoing
        // secret" and "it has cut over".
        var matched = false;

        foreach (var entry in signatureHeader.Split(SignatureSeparator))
        {
            matched |= EntryMatches(entry.Trim(), expected);
        }

        return matched;
    }

    /// <summary>
    /// Whether one <c>v1=sha256:&lt;hex&gt;</c> entry equals <paramref name="expected"/>.
    /// </summary>
    /// <remarks>
    /// The version prefix is checked before the digest is parsed, so an entry from a future scheme is
    /// skipped rather than misread as this one. A malformed entry is a non-match, never an exception:
    /// this runs before anything has been authenticated, so a header that could make it throw would
    /// let anyone turn a bad request into a 500.
    /// </remarks>
    private static bool EntryMatches(string entry, byte[] expected)
    {
        if (!entry.StartsWith(SignaturePrefix, StringComparison.Ordinal))
        {
            return false;
        }

        byte[] received;
        try
        {
            received = Convert.FromHexString(entry[SignaturePrefix.Length..]);
        }
        catch (FormatException)
        {
            return false;
        }

        // Constant-time compare. A byte-by-byte compare leaks, through timing, how much of a guessed
        // signature was correct, which is enough to forge one.
        return CryptographicOperations.FixedTimeEquals(received, expected);
    }

    /// <summary>
    /// Computes the expected signature: HMAC-SHA256 over the bytes of
    /// <c>"{timestamp}.{body}"</c>, keyed with the destination secret.
    /// </summary>
    public static byte[] ComputeSignature(string secretKey, string timestamp, byte[] rawBody)
    {
        var prefix = Encoding.UTF8.GetBytes(timestamp + ".");
        var input = new byte[prefix.Length + rawBody.Length];
        prefix.CopyTo(input, 0);
        rawBody.CopyTo(input, prefix.Length);

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));
        return hmac.ComputeHash(input);
    }

    /// <summary>
    /// Whether the delivery's timestamp is inside the replay window. A missing, unparsable or
    /// out-of-range timestamp fails: the timestamp is part of the signed input, so a delivery without
    /// a usable one cannot have been signed by us.
    /// </summary>
    /// <remarks>
    /// Every rejection is a <c>false</c>, never an exception. A receiver reads this header before it
    /// has authenticated anything, so a value that made it throw would let anyone turn a malformed
    /// header into a 500, and a stream of them into an outage.
    /// </remarks>
    public static bool IsInsideReplayWindow(string? timestampHeader, DateTimeOffset now, TimeSpan? tolerance = null)
    {
        if (!long.TryParse(timestampHeader, NumberStyles.Integer, CultureInfo.InvariantCulture, out var seconds))
        {
            return false;
        }

        // Parsing as a long is not enough: FromUnixTimeSeconds throws outside the representable
        // range, and "1" followed by twenty digits parses fine.
        if (seconds < MinUnixSeconds || seconds > MaxUnixSeconds)
        {
            return false;
        }

        var sent = DateTimeOffset.FromUnixTimeSeconds(seconds);
        var skew = now - sent;
        if (skew < TimeSpan.Zero)
        {
            skew = -skew;
        }

        return skew <= (tolerance ?? DefaultTolerance);
    }
}

curl "{{BASE_URL}}/api/transactions/{{transactionId}}" \
  -H "api-key: {{API_KEY}}"