TailoredApps.Shared.Payments.Provider.PayU¶
Integracja z PayU REST API v2.1 — wiodącym polskim operatorem płatności obsługującym BLIK, szybkie przelewy, karty i inne metody.
Instalacja¶
Rejestracja w DI¶
using TailoredApps.Shared.Payments.Provider.PayU;
builder.Services
.AddPayments()
.RegisterPayUProvider();
Konfiguracja appsettings.json¶
{
"Payments": {
"Providers": {
"PayU": {
"ClientId": "your-client-id",
"ClientSecret": "your-client-secret",
"PosId": "your-pos-id",
"SignatureKey": "your-signature-key",
"ServiceUrl": "https://secure.snd.payu.com",
"NotifyUrl": "https://myapp.com/webhooks/payu",
"ContinueUrl": "https://myapp.com/payment/return"
}
}
}
}
| Opcja | Wymagana | Opis |
|---|---|---|
ClientId |
tak | Identyfikator klienta OAuth |
ClientSecret |
tak | Sekret klienta OAuth |
PosId |
tak | Identyfikator punktu sprzedaży (merchantPosId) |
SignatureKey |
tak | Klucz do weryfikacji podpisu powiadomień (second key) |
ServiceUrl |
nie | URL API PayU. Wartością domyślną jest sandbox, https://secure.snd.payu.com — dla prawdziwych płatności ustaw adres produkcyjny |
NotifyUrl |
nie | URL do powiadomień o transakcjach (webhook) |
ContinueUrl |
nie | URL powrotu po płatności |
Opcje wymagane są sprawdzane przy starcie hosta (OptionsValidationException); pozostałe nie są walidowane.
Obsługiwane kanały¶
Lista jest stała w providerze:
| Waluta | Kanały |
|---|---|
| PLN | blik (BLIK), c (karta płatnicza), o (przelew online), ai (raty), ap (Apple Pay), jp (Google Pay) |
| Inne | c |
Autoryzacja¶
Provider pobiera token OAuth2 (client_credentials) przy każdym wywołaniu RegisterPayment i GetStatus. Token nie jest cache'owany.
Webhook¶
PayU wysyła powiadomienia POST z nagłówkiem OpenPayU-Signature (signature=...;algorithm=...). Provider liczy skrót z surowego body
i dopisanego SignatureKey algorytmem wskazanym w nagłówku — MD5, SHA-1 lub SHA-256 (MD5, gdy nagłówek go nie wskazuje) —
i porównuje wynik z signature.
[HttpPost("webhooks/payu")]
public async Task<IActionResult> PayUWebhook(CancellationToken cancellationToken)
{
// Podpis obejmuje dokładne bajty body - czytaj je surowe, nie przez [FromBody].
using var reader = new StreamReader(Request.Body, Encoding.UTF8);
var body = await reader.ReadToEndAsync(cancellationToken);
var result = await _payments.HandleWebhookAsync("PayU", new PaymentWebhookRequest
{
Body = body,
ContentType = Request.ContentType,
Headers = Request.Headers.ToDictionary(h => h.Key, h => h.Value),
}, cancellationToken);
return result is PaymentWebhookRejected ? BadRequest() : Ok();
}
order.status |
Wynik |
|---|---|
COMPLETED |
PaymentWebhookProcessed, status Finished |
CANCELED, REJECTED |
PaymentWebhookProcessed, status Rejected |
| inna wartość / brak | PaymentWebhookIgnored (status Processing) |
🔒 Bezpieczeństwo¶
- Zamówienia są tworzone przez nazwanego klienta HTTP
PayU.Orders(PayUServiceCaller.OrdersClientName), pozostałe wywołania przezPayU.RegisterPayUProvider()konfigurujePayU.Ordersbez podążania za przekierowaniami i bez ciasteczek: PayU odpowiada na zamówienie kodem 302, a identyfikator zamówienia jest w treści tej odpowiedzi. Jeśli konfigurujesz tego klienta samodzielnie, zostawAllowAutoRedirect = false— inaczej provider zgłosiInvalidOperationExceptionzamiast zgubić identyfikator. - Domyślny
ServiceUrlto sandbox PayU (https://secure.snd.payu.com) — adres produkcyjny ustaw jawnie. - Każde zamówienie jest wysyłane z
customerIp=127.0.0.1; adres płacącego nie jest przekazywany do PayU. - Pusty
SignatureKeylub braksignature=w nagłówkuOpenPayU-Signature→PaymentWebhookRejected(InvalidSignature), fail-closed; porównanie w stałym czasie. - Obsługiwane algorytmy:
MD5,SHA-1,SHA-256(zgodnie z ustawieniem POS w panelu PayU); inne wartościalgorithm=są odrzucane. Zalecany SHA-256. - Wynik webhooka niesie
PaymentUniqueId(order.orderId).
🤖 AI Agent Prompt¶
## PayU Provider — Instrukcja dla agenta AI
Provider key: "PayU"
Sekcja konfiguracji: "Payments:Providers:PayU"
Wymagane pola: ClientId, ClientSecret, PosId, SignatureKey
Autoryzacja: OAuth2 client_credentials — automatyczna, token pobierany przy każdym wywołaniu (bez cache)
Kwota w API: grosze (int) — biblioteka konwertuje automatycznie z decimal
Sandbox: ServiceUrl = "https://secure.snd.payu.com" (to wartość domyślna — adres produkcyjny ustaw jawnie)
Rejestracja: builder.Services.AddPayments().RegisterPayUProvider();
- Ustaw w panelu PayU algorytm SHA-256 dla podpisu powiadomień
- Webhook: przekaż surowe body (nie [FromBody]) i wszystkie nagłówki żądania; na wynik PaymentWebhookRejected odpowiedz statusem spoza 2xx