OXEMO.Paynow.Sdk 1.0.3

Paynow .NET SDK

Nieoficjalne SDK dla bramki p�atniczej Paynow (API v3).

Biblioteka udost�pnia m.in.:

• tworzenie p�atno�ci (CreatePaymentAsync)
• sprawdzanie statusu (GetPaymentStatusAsync)
• pobieranie szczeg��w p�atno�ci (GetPaymentDetailsAsync)
• zwroty (CreateRefundAsync)
• obs�ug� tokenizacji (pobieranie zapisanych instrument�w, p�atno�� zapisan� kart�, usuwanie tokena)
• pobieranie klauzul RODO (GetDataProcessingNoticesAsync)

Wymagania

• netstandard2.1 (biblioteka) � do u�ycia w .NET 6/7/8 itp.
• Klucze z panelu Paynow: ApiKey oraz SignatureKey

Instalacja

dotnet add package OXEMO.Paynow.Sdk

Konfiguracja (DI) � ASP.NET Core (Razor Pages)

W Program.cs:

using Paynow.Sdk.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddPaynow(options =>
{
    options.ApiUrl = builder.Configuration["Paynow:ApiUrl"] ?? "https://api.sandbox.paynow.pl";
    options.ApiKey = builder.Configuration["Paynow:ApiKey"]!;
    options.SignatureKey = builder.Configuration["Paynow:SignatureKey"]!;
});

var app = builder.Build();
app.MapRazorPages();
app.Run();

Przyk�adowy appsettings.json:

{
  "Paynow": {
    "ApiUrl": "https://api.sandbox.paynow.pl",
    "ApiKey": "<apiKey>",
    "SignatureKey": "<signatureKey>"
  }
}

Uwaga: klucze trzymaj w zmiennych �rodowiskowych / User Secrets, a nie w repo.

Podstawowy flow p�atno�ci (redirect)

1) Utworzenie p�atno�ci

amount przekazywany jest w groszach (np. 100 = 1.00 PLN).

using Paynow.Sdk;
using Paynow.Sdk.Models;

public class CheckoutModel : PageModel
{
    private readonly IPaynowClient _paynow;

    public CheckoutModel(IPaynowClient paynow) => _paynow = paynow;

    public async Task<IActionResult> OnPostPayAsync(int amountPln, string email)
    {
        var externalId = Guid.NewGuid().ToString();
        var continueUrl = Url.PageLink("/Paynow/Return");

        var request = new PaymentRequest
        {
            Amount = amountPln * 100,
            ExternalId = externalId,
            Description = $"Zam�wienie {externalId}",
            ContinueUrl = continueUrl,
            Buyer = new Buyer
            {
                Email = email,
                Locale = "pl-PL"
            }
        };

        var response = await _paynow.CreatePaymentAsync(request);
        if (response?.RedirectUrl is null)
        {
            return BadRequest("Brak redirectUrl w odpowiedzi Paynow");
        }

        return Redirect(response.RedirectUrl);
    }
}

2) Obs�uga powrotu (continueUrl)

Paynow dokleja do continueUrl parametr paymentId.

using Paynow.Sdk;
using Paynow.Sdk.Models;

public class ReturnModel : PageModel
{
    private readonly IPaynowClient _paynow;
    public PaymentStatusResponse? Status { get; private set; }

    public ReturnModel(IPaynowClient paynow) => _paynow = paynow;

    public async Task OnGetAsync(string paymentId)
    {
        Status = await _paynow.GetPaymentStatusAsync(paymentId);
    }
}

Pobieranie szczeg��w p�atno�ci (payment details)

var details = await paynow.GetPaymentDetailsAsync(paymentId);
// details.PaymentMethodToken (je�li API zwraca)

Zwroty (Refund)

var refund = await paynow.CreateRefundAsync(paymentId, new RefundRequest
{
    Amount = 100, // grosze
    Reason = "Zwrot testowy"
});

Tokenizacja kart (zapis karty + p�atno�� zapisan� kart�)

Poni�szy opis odpowiada fragmentowi dokumentacji Paynow o tokenizacji.

Zapis karty (tokenizacja podczas normalnej p�atno�ci)

Aby Paynow udost�pni� zapis karty i p�niej pokaza� zapisane instrumenty na paywallu, w buyer przeka�:

• Buyer.ExternalId � sta�y identyfikator kupuj�cego (np. ID u�ytkownika z Twojej bazy)
• Buyer.DeviceFingerprint � fingerprint urz�dzenia

var request = new PaymentRequest
{
    Amount = 10000,
    ExternalId = Guid.NewGuid().ToString(),
    Description = "P�atno�� za zam�wienie",
    Buyer = new Buyer
    {
        ExternalId = "c0940962-706e-4e23-822a-97810744f1c5",
        DeviceFingerprint = "<fingerprint>",
        Email = "jan.kowalski@melements.pl"
    }
};

var response = await paynow.CreatePaymentAsync(request);

Pobieranie zapisanych kart/instrument�w

SDK mapuje odpowied� GET /v3/payments/paymentmethods?externalBuyerId=....

using Paynow.Sdk.Models;

var methods = await paynow.GetSavedPaymentMethodsAsync(externalBuyerId);

var cards = methods?
    .FirstOrDefault(m => m.Type == "CARD")?
    .PaymentMethods
    .SelectMany(pm => pm.SavedInstruments ?? new List<SavedInstrument>())
    .ToList();

var firstActiveToken = cards?.FirstOrDefault(c => c.Status == "ACTIVE")?.Token;

Token zapisanej karty jest w SavedInstrument.Token.

P�atno�� zapisan� kart� (White Label)

Po wybraniu karty przez kupuj�cego wy�lij do Paynow:

• PaymentRequest.PaymentMethodId (np. 2002)
• PaymentRequest.PaymentMethodToken (token instrumentu)

var request = new PaymentRequest
{
    Amount = 45671,
    ExternalId = Guid.NewGuid().ToString(),
    Description = "P�atno�� zapisan� kart�",
    PaymentMethodId = "2002",
    PaymentMethodToken = firstActiveToken,
    Buyer = new Buyer
    {
        ExternalId = externalBuyerId,
        Email = email
    }
};

var response = await paynow.CreatePaymentAsync(request);
return Redirect(response!.RedirectUrl);

Uwaga: paymentMethodId w API jest liczb� � w SDK PaymentRequest.PaymentMethodId jest stringiem. Przekazuj warto�� w postaci tekstu, np. "2002".

Usuwanie zapisanej karty

await paynow.RemoveSavedPaymentMethodAsync(token, externalBuyerId);

Klauzule RODO (wymagane dla White Label)

var notices = await paynow.GetDataProcessingNoticesAsync("pl-PL");

Powiadomienia (webhook) i weryfikacja podpisu

Paynow wysy�a statusy na notification-url jako POST z nag��wkiem Signature.

Do weryfikacji podpisu u�yj VerifySignature(...).

using System.Text;

Request.EnableBuffering();
using var reader = new StreamReader(Request.Body, Encoding.UTF8, leaveOpen: true);
var body = await reader.ReadToEndAsync();
Request.Body.Position = 0;

var signature = Request.Headers["Signature"].ToString();

var ok = paynow.VerifySignature(
    signature,
    body,
    new Dictionary<string, string>()
);

if (!ok) return Unauthorized();

Model pomocniczy (opcjonalny) do deserializacji notyfikacji: Paynow.Sdk.Models.PaymentNotification.

Obs�uga b��d�w

W przypadku b��d�w API rzucany jest PaynowException.

try
{
    var status = await paynow.GetPaymentStatusAsync(paymentId);
}
catch (PaynowException ex)
{
    // ex.StatusCode
    // ex.Errors (lista szczeg��w)
}