TailoredApps.Shared.Payments.Provider.Tpay¶
Integracja z Tpay — polskim operatorem płatności online obsługującym szybkie przelewy, BLIK, karty i inne metody.
Instalacja¶
Rejestracja w DI¶
using TailoredApps.Shared.Payments.Provider.Tpay;
builder.Services
.AddPayments()
.RegisterTpayProvider();
Konfiguracja appsettings.json¶
{
"Payments": {
"Providers": {
"Tpay": {
"ClientId": "your-client-id",
"ClientSecret": "your-client-secret",
"MerchantId": "your-merchant-id",
"ServiceUrl": "https://api.tpay.com",
"ReturnUrl": "https://myapp.com/payment/return",
"NotifyUrl": "https://myapp.com/webhooks/tpay",
"SecurityCode": "your-security-code",
"JwsCertificateBaseUrl": "https://secure.tpay.com"
}
}
}
}
| Opcja | Wymagana | Opis |
|---|---|---|
ClientId |
tak | Identyfikator klienta OAuth2 |
ClientSecret |
tak | Sekret klienta OAuth2 |
MerchantId |
nie | Identyfikator sprzedawcy — wczytywany z konfiguracji, ale nieużywany przez providera |
ServiceUrl |
nie | URL API Tpay, domyślnie https://api.tpay.com (sandbox: https://openapi.sandbox.tpay.com). Dawny alias ApiUrl usunięto w 3.0: konfiguracja, która go jeszcze ustawia, zatrzymuje start hosta, zamiast po cichu przejść na produkcję |
ReturnUrl |
nie | URL powrotu po płatności (używany zarówno przy sukcesie, jak i przy błędzie) |
NotifyUrl |
nie | URL do powiadomień (webhook) |
SecurityCode |
tak | Kod bezpieczeństwa (kod weryfikujący powiadomienia z panelu Tpay) — sekret pola md5sum |
JwsCertificateBaseUrl |
nie | Adres, z którego Tpay udostępnia certyfikaty podpisu powiadomień. Domyślnie https://secure.tpay.com; sandbox: https://secure.sandbox.tpay.com. Musi być bezwzględnym adresem https |
JwsRootCertificatePem |
nie | Opcjonalnie: treść tpay-jws-root.pem (PEM). Gdy ustawiona, zaufanie jest przypięte do niej i plik nie jest pobierany |
Opcje wymagane są sprawdzane przy starcie hosta (OptionsValidationException), razem z formatem
JwsCertificateBaseUrl i JwsRootCertificatePem; pozostałe nie są walidowane.
Obsługiwane kanały¶
Provider zwraca stałą listę dla każdej waluty: blik (BLIK), card (karta płatnicza), bank (przelew online).
Autoryzacja¶
Provider pobiera token OAuth2 przez endpoint /oauth/auth przy każdym wywołaniu RegisterPayment i GetStatus. Token nie jest cache'owany.
Webhook¶
Tpay wysyła powiadomienie o transakcji metodą POST jako formularz application/x-www-form-urlencoded
(pola id, tr_id, tr_amount, tr_crc, tr_status, md5sum, …). Provider przyjmuje je dopiero po dwóch sprawdzeniach:
md5sum=md5(id + tr_id + tr_amount + tr_crc + SecurityCode)— dowodzi, że powiadomienie jest adresowane do tego sprzedawcy.- Nagłówek
X-JWS-Signature— podpis RS256 dokładnych bajtów body. Certyfikat podpisujący jest pobierany z adresux5uz nagłówka JWS (musi wskazywać naJwsCertificateBaseUrl) i musi łańcuchem prowadzić do certyfikatu głównego Tpay (/x509/tpay-jws-root.pem).
[HttpPost("webhooks/tpay")]
public async Task<IActionResult> TpayWebhook(CancellationToken cancellationToken)
{
// Podpis obejmuje dokładne bajty body - czytaj je surowe, nie przez [FromForm].
using var reader = new StreamReader(Request.Body, Encoding.UTF8);
var body = await reader.ReadToEndAsync(cancellationToken);
var result = await _payments.HandleWebhookAsync("Tpay", new PaymentWebhookRequest
{
Body = body,
ContentType = Request.ContentType,
Headers = Request.Headers.ToDictionary(h => h.Key, h => h.Value),
}, cancellationToken);
// Tpay ponawia powiadomienie, dopóki nie dostanie odpowiedzi 200 z treścią "TRUE".
return result is PaymentWebhookRejected
? BadRequest("FALSE")
: Content(TpayProvider.Acknowledgement, "text/plain");
}
tr_status |
Wynik |
|---|---|
TRUE, PAID |
PaymentWebhookProcessed, status Finished |
CHARGEBACK, FALSE |
PaymentWebhookProcessed, status Rejected |
| inna wartość / brak | PaymentWebhookIgnored (status Processing) |
PaymentUniqueId w wyniku to tr_crc, a gdy jest puste — tr_id (tytuł transakcji Tpay, TR-…). Identyfikator zwracany przez
RequestPayment nie występuje w powiadomieniu, dlatego przekaż własny numer zamówienia w PaymentRequest.AdditionalData:
provider wysyła go jako hiddenDescription, a Tpay odsyła w tr_crc.
🔒 Bezpieczeństwo¶
- Weryfikacja jest fail-closed: pusty
SecurityCode, brak lub niezgodnośćmd5sum, brak albo uszkodzonyX-JWS-Signature, algorytm inny niżRS256, certyfikat spoza łańcucha Tpay lub po terminie ważności →PaymentWebhookRejection.InvalidSignature. md5sumjest sprawdzane przed pobraniem jakiegokolwiek certyfikatu, więc żądanie bez znajomościSecurityCodenie wywołuje ruchu wychodzącego.- Adres
x5umusi mieć ten sam schemat, host i port coJwsCertificateBaseUrl(porównywany jest cały origin, nie prefiks tekstu —https://secure.tpay.com.example.netjest odrzucany). tpay-jws-root.pemto paczka: CA wystawiające certyfikat podpisu oraz samopodpisany root. Kotwicą zaufania jest wyłącznie certyfikat samopodpisany; magazyn certyfikatów systemu nie jest używany.JwsRootCertificatePempozwala przypiąć tę paczkę w konfiguracji.- Certyfikaty są przechowywane w pamięci przez godzinę (
ITpayServiceCallerjest singletonem). Gdy podpis nie zgadza się z certyfikatem z pamięci, certyfikaty są pobierane ponownie jeden raz — wymiana certyfikatu po stronie Tpay nie przerywa obsługi. - Sandbox podpisuje innym CA: ustaw
JwsCertificateBaseUrlnahttps://secure.sandbox.tpay.com. JwsCertificateBaseUrl(bezwzględny adres https) iJwsRootCertificatePemsą walidowane przy starcie hosta.- Zmiana niekompatybilna (2.0):
ITpayServiceCaller.VerifyNotification(body, signature)zastąpiono przezVerifyNotificationAsync(body, jwsSignature, cancellationToken); nagłówekX-Signaturenie jest już czytany. - Zakres weryfikacji: łańcuch sprawdzono na certyfikatach publikowanych przez Tpay (produkcja i sandbox), a podpis JWS i
md5sum— testami z własnym łańcuchem certyfikatów. Przed wdrożeniem wykonaj płatność testową w sandboxie Tpay.
🤖 AI Agent Prompt¶
## Tpay Provider — Instrukcja dla agenta AI
Provider key: "Tpay"
Sekcja konfiguracji: "Payments:Providers:Tpay"
Wymagane pola: ClientId, ClientSecret, SecurityCode
Autoryzacja: OAuth2 — automatyczna, token pobierany przy każdym wywołaniu (bez cache)
Sandbox: ServiceUrl = "https://openapi.sandbox.tpay.com"
Rejestracja: builder.Services.AddPayments().RegisterTpayProvider();
Webhook: POST application/x-www-form-urlencoded; weryfikacja md5sum + nagłówek X-JWS-Signature (RS256, łańcuch do roota Tpay)
Zasady:
- Przekaż do PaymentWebhookRequest.Body surowe body (nie [FromForm]) i wszystkie nagłówki żądania
- Odpowiedz HTTP 200 z treścią "TRUE" (TpayProvider.Acknowledgement); inaczej Tpay ponowi powiadomienie
- W PaymentRequest.AdditionalData podaj własny numer zamówienia — wróci jako PaymentUniqueId w wyniku webhooka (tr_crc)
- Sandbox: JwsCertificateBaseUrl = "https://secure.sandbox.tpay.com" oraz ServiceUrl sandboxa
- Nie wyłączaj weryfikacji ani nie zastępuj ITpayServiceCaller stubem zwracającym true