Open-source eCommerce platform for C# and ASP.NET Core 10 with MongoDB. Build multi-store shops and multi-vendor marketplaces with B2B/B2C, REST API, plugins, Vue 3 and Docker.
Plugin — Payment Provider
Purpose
Create, modify, and review GrandNode payment plugins that implement IPaymentProvider.
When To Use
Use this skill when building a new payment method plugin, changing payment flow, adding capture/refund/void support, implementing a redirect gateway, or reviewing payment provider correctness and security.
When Not To Use
Do not use this skill for order processing business logic outside the payment flow, or for general plugin infrastructure; combine with plugin-module when foundational setup is needed.
Inputs Required
- Repository root.
- Payment method type: Standard (inline form) or Redirection (external gateway).
- Gateway or PSP API being integrated.
- Which operations must be supported: capture, refund, partial refund, void.
- Whether additional handling fees apply.
- Whether a custom checkout form step is required.
Instructions
Mandatory Rules
Provider Interface
- Implement
IPaymentProviderfromGrand.Business.Core.Interfaces.Checkout.Payments. This extendsIProviderwhich requiresConfigurationUrl,SystemName,FriendlyName,Priority,LimitedToStores, andLimitedToGroups. - Implement every member. For methods that are not supported, return a result with
result.AddError("Method not supported")rather than throwing. Required behavior per member:
| Member | Standard payment | Redirect payment |
|---|---|---|
InitPaymentTransaction() |
Return null (framework creates transaction) |
Return null |
ProcessPayment(tx) |
Set result.NewPaymentTransactionStatus (typically Pending) |
Return empty result; processing happens after redirect |
PostProcessPayment(tx) |
Usually empty (Task.CompletedTask) |
Usually empty |
PostRedirectPayment(tx) |
Return string.Empty |
Return the gateway redirect URL |
CanRePostRedirectPayment(tx) |
Return false |
Return true when the user can re-initiate |
ValidatePaymentForm(model) |
Validate custom form fields; return error list | Return empty list |
SavePaymentInfo(model) |
Save form data to PaymentTransaction fields; return updated tx or null |
Return null |
GetControllerRouteName() |
Route name of the storefront payment-info controller, or "" when SkipPaymentInfo |
Route name or "" |
PaymentMethodType |
PaymentMethodType.Standard |
PaymentMethodType.Redirection |
SkipPaymentInfo() |
Return true to skip the payment info step |
Usually false |
Description() |
Translatable description shown on checkout | Same |
LogoURL |
"/Plugins/{SystemName}/logo.jpg" |
Same |
Capture/Refund/Void/Cancel |
Implement if supported; return error result if not | Same |
SupportCapture/Refund/PartialRefund/Void |
Return true/false matching what is implemented |
Same |
GetAdditionalHandlingFee(cart) |
Return the calculated fee in the working currency | Same |
HidePaymentMethod(cart) |
Return true to suppress the method for this cart |
Same |
- Set
TransactionStatusviaresult.NewPaymentTransactionStatusinProcessPayment. Common values:TransactionStatus.Pending— order placed but not yet confirmed.TransactionStatus.Authorized— gateway authorized; capture is separate.TransactionStatus.Paid— payment fully captured immediately.
- Resolve
FriendlyNamethroughITranslationService.GetResource(Defaults.FriendlyName). - Set
LogoURLto"/Plugins/{SystemName}/logo.jpg".
Redirect Payment Flow
- When
PaymentMethodType == Redirection:PostRedirectPaymentreturns the URL; the checkout redirects the customer there. The gateway posts back to a return controller action in the plugin. - Implement a public storefront controller (
[Area("")]without[AuthorizeAdmin]) as the redirect return handler. The controller receives the gateway callback, updates thePaymentTransaction, and redirects to order confirmation. - Register the return controller route in
EndpointProvideror via a convention route inStartupApplication.Configure.
Operations: Capture, Refund, Void
- Implement
Capture,Refund, andVoidonly when the gateway supports them. Returnresult.AddError("Capture method not supported")for unsupported operations. - Return
SupportCapture() => trueonly whenCaptureis actually implemented; same for Refund, PartiallyRefund, and Void. Returningtruecauses the admin UI to show the corresponding action button. - In
CancelPayment, updatepaymentTransaction.TransactionStatus = TransactionStatus.Canceledand persist viaIPaymentTransactionService.UpdatePaymentTransaction.
Project Structure
- Use
Microsoft.NET.Sdk.Razoras SDK. - Set output path to
..\..\Web\Grand.Web\Plugins\{SystemName}\. - Mark all GrandNode project references
Private="false". - Include
logo.jpgwithCopyToOutputDirectory = Always.
Manifest, Defaults, Settings
- Define
[assembly: PluginInfo(...)]withGroup = "Payment methods". - Define
{Plugin}DefaultswithProviderSystemName,FriendlyName(resource key),ConfigurationUrl, and — for redirect plugins —ReturnHandlerRouteName. - Define
{Plugin}Settings : ISettingswith at minimumDisplayOrder,AdditionalFee,AdditionalFeePercentage, andSkipPaymentInfo. Add gateway-specific fields (API keys, endpoint URLs).
Startup and Install
- Register the provider:
services.AddScoped<IPaymentProvider, YourPaymentProvider>(); - In
Install(): save default settings, register localization keys. Callbase.Install()last. - In
Uninstall(): delete settings, remove resource keys. Callbase.Uninstall()last.
Admin Configuration
- Create an admin controller with
[AuthorizeAdmin],[Area("Admin")], and[PermissionAuthorize(PermissionSystemName.PaymentMethods)]. - Use
IAdminStoreService.GetActiveStore(),LoadSetting,SaveSetting,ClearCachefor store-scoped config.
Security Requirements
- Never log or store raw card numbers, CVVs, or full PANs. Store only tokens, last-4, and transaction IDs from the gateway.
- Never construct redirect return URLs from unvalidated query parameters; validate the gateway callback signature or token before updating the transaction.
- Store gateway API keys in settings via
ISettingService, not in source code or configuration files.
Recommendations
- Prefer
Payments.CashOnDeliveryas a template for Standard payment andPayments.StripeCheckoutfor Redirect payment. - Prefer returning
TransactionStatus.PendingfromProcessPaymentfor Standard methods unless the gateway confirms synchronously. - Prefer
GetAdditionalHandlingFeefor fixed or percentage fees; useIOrderCalculationService.GetShoppingCartSubTotalfor percentage-based calculation.
Key Contracts
ProcessPaymentResult
public bool Success { get; } // no errors
public List<string> Errors { get; }
public TransactionStatus NewPaymentTransactionStatus { get; set; } // default Pending
public double PaidAmount { get; set; }
result.AddError("message");
TransactionStatus enum (key values)
Pending = 0, Authorized = 10, PartialPaid = 15, Paid = 20,
PartiallyRefunded = 25, Refunded = 30, Voided = 40, Canceled = 50
PaymentMethodType enum
Standard = 1 // inline checkout form
Redirection = 2 // customer sent to external gateway
Other = 3
CapturePaymentResult / RefundPaymentResult / VoidPaymentResult
result.AddError("message");
result.CaptureTransactionId = "..."; // CapturePaymentResult only
result.NewPaymentStatus = TransactionStatus.Paid;
RefundPaymentRequest
PaymentTransaction PaymentTransaction { get; }
double AmountToRefund { get; }
bool IsPartialRefund { get; }
File Locations
| Concern | Path |
|---|---|
| IPaymentProvider | src/Business/Grand.Business.Core/Interfaces/Checkout/Payments/IPaymentProvider.cs |
| ProcessPaymentResult | src/Business/Grand.Business.Core/Utilities/Checkout/ProcessPaymentResult.cs |
| CapturePaymentResult | src/Business/Grand.Business.Core/Utilities/Checkout/CapturePaymentResult.cs |
| RefundPaymentResult / RefundPaymentRequest | src/Business/Grand.Business.Core/Utilities/Checkout/ |
| VoidPaymentResult | src/Business/Grand.Business.Core/Utilities/Checkout/VoidPaymentResult.cs |
| PaymentTransaction entity | src/Core/Grand.Domain/Payments/PaymentTransaction.cs |
| TransactionStatus enum | src/Core/Grand.Domain/Payments/TransactionStatus.cs |
| PaymentMethodType enum | src/Business/Grand.Business.Core/Enums/Checkout/PaymentMethodType.cs |
| IPaymentTransactionService | src/Business/Grand.Business.Core/Interfaces/Checkout/Payments/IPaymentTransactionService.cs |
| Example — Standard | src/Plugins/Payments.CashOnDelivery/ |
| Example — Redirect | src/Plugins/Payments.StripeCheckout/ |
| Example — Advanced | src/Plugins/Payments.BrainTree/ |
Validation Checklist
- All
IPaymentProviderandIProvidermembers implemented. - Methods that are not supported return
result.AddError(...)not throw. -
SupportCapture/Refund/PartialRefund/Voidmatch actual implementation. -
PaymentMethodTypeset correctly (Standard vs Redirection). - Redirect plugins have a return controller action that validates the gateway callback.
- No raw card data stored or logged.
- Gateway secrets stored via
ISettingService, not hardcoded. - Output path set to
Grand.Web/Plugins/{SystemName}/. -
Installsaves settings and resource keys;Uninstallcleans them up. - Admin controller uses
[PermissionAuthorize(PermissionSystemName.PaymentMethods)].
Examples
Example 1: Standard Payment (Invoice/COD)
Set PaymentMethodType.Standard. ProcessPayment returns TransactionStatus.Pending. PostRedirectPayment returns "". All capture/refund/void methods return an error result. SkipPaymentInfo driven from settings.
Example 2: Redirect Gateway (e.g., Stripe Checkout)
Set PaymentMethodType.Redirection. ProcessPayment returns an empty result. PostRedirectPayment calls the gateway SDK to create a session and returns the session URL. Implement a public return controller that verifies the webhook/callback and calls IPaymentTransactionService.UpdatePaymentTransaction.
Example 3: Authorize-and-Capture Gateway
Set PaymentMethodType.Standard. ProcessPayment calls the gateway authorize API and sets TransactionStatus.Authorized. Implement Capture to charge the authorization. Return SupportCapture() => true. Implement Void to cancel the authorization.