TailoredApps.Shared.Payments.Provider.CashBill¶
Integration with CashBill — a Polish online payment operator that handles bank transfers, cards and BLIK.
Installation¶
DI registration¶
using TailoredApps.Shared.Payments.Provider.CashBill;
builder.Services
.AddPayments()
.RegisterCashbillProvider();
Configuration appsettings.json¶
{
"Payments": {
"Providers": {
"Cashbill": {
"ShopId": "MY_SHOP_ID",
"ShopSecretPhrase": "my_secret_phrase",
"ServiceUrl": "https://pay.cashbill.eu",
"ReturnUrl": "https://myapp.com/payment/return",
"NegativeReturnUrl": "https://myapp.com/payment/failed"
}
}
}
}
| Option | Required | Description |
|---|---|---|
ShopId |
yes | Shop identifier in CashBill |
ShopSecretPhrase |
yes | Secret phrase that signs requests and verifies notifications |
ServiceUrl |
yes | CashBill REST API URL; there is no default. When the address has a path, end it with / - request addresses are resolved relative to it |
ReturnUrl |
no | Return URL after a successful payment. Not validated at startup, but RegisterPayment fails unless it is an absolute URL |
NegativeReturnUrl |
no | Return URL after a failed/cancelled payment |
Required options are checked when the host starts (OptionsValidationException); the others are not validated.
Supported channels¶
CashBill returns a dynamic list of channels fetched from the API for the given currency (PLN, EUR, USD etc.). The channels include bank transfer, cards, BLIK, e-wallets.
Webhook¶
CashBill sends a GET/POST notification with three query-string parameters: cmd, args (the payment id) and sign.
The provider has no option for the notification address. It reads the parameters from PaymentWebhookRequest.Query
(not from the body or the headers), checks that sign equals MD5(cmd + args + ShopSecretPhrase) and then reads the current
status of the payment from the CashBill API.
[AcceptVerbs("GET", "POST", Route = "webhooks/cashbill")]
public async Task<IActionResult> CashBillWebhook(CancellationToken cancellationToken)
{
var result = await _payments.HandleWebhookAsync("Cashbill", new PaymentWebhookRequest
{
HttpMethod = Request.Method,
Query = Request.Query.ToDictionary(q => q.Key, q => q.Value),
}, cancellationToken);
return result is PaymentWebhookRejected ? BadRequest() : Ok();
}
| Notification | Result |
|---|---|
| valid signature | PaymentWebhookProcessed with the status read from CashBill (Created, Processing, Finished or Rejected) |
args missing |
PaymentWebhookRejected (MalformedPayload) |
sign missing or wrong |
PaymentWebhookRejected (InvalidSignature) |
ShopSecretPhrase not configured |
PaymentWebhookRejected (NotConfigured) |
🔒 Security¶
- API calls go through
HttpClient- the named clientCashBill(CashbillHttpClient.HttpClientName) fromIHttpClientFactory, so the handlers, resilience and timeouts configured in the host apply. An answer outside 2xx throwsPaymentGatewayException(up to 2.0.1:WebException) - catchHttpRequestException. Failures are logged with the address but without the query string, which carries the request signature. - The notification signature is
MD5(cmd + args + ShopSecretPhrase), compared in constant time. BothHandleWebhookAsyncand the legacyTransactionStatusChangeverify it - an invalid signature yieldsPaymentWebhookRejected(InvalidSignature, message "Invalid signature.") / aRejectedresponse without polling the CashBill API. - The error message no longer contains the expected signature (it used to be an oracle for forging arbitrary notifications).
- Missing
ShopSecretPhrase→PaymentWebhookRejected(NotConfigured, message "Signature verification is not configured."). GetStatus(paymentId)rejects identifiers with special characters (PaymentIdentifier.EnsureSafe).- A webhook with a valid signature always gives
PaymentWebhookProcessedwith the status polled from CashBill - neverPaymentWebhookIgnored. CheckPayment.PaymentStatusbefore acting: it can still beCreatedorProcessing. - After creating a payment the provider rewrites its return address to
{ReturnUrl}/{paymentId}: the payer comes back toReturnUrlwith the payment id appended.
🤖 AI Agent Prompt¶
## CashBill Provider - instructions for an AI agent
Provider key: "Cashbill"
Configuration section: "Payments:Providers:Cashbill" (lowercase "b" in Cashbill!)
Required fields: ShopId, ShopSecretPhrase, ServiceUrl
Registration: builder.Services.AddPayments().RegisterCashbillProvider();
- The notification is read from the query string (cmd, args, sign): fill PaymentWebhookRequest.Query
- A webhook result is always PaymentWebhookProcessed with the polled status - check Payment.PaymentStatus
- Never return the webhook ErrorMessage to the caller; log it server-side
- Keep the shop secret in user-secrets/environment variables - never in the repository