nopCommerce Dokumentace

Jak naprogramovat vlastní platební metodu

Platební metody jsou v nopCommerce implementovány jako pluginy. Než začnete programovat novou platební metodu, doporučujeme přečíst si článek Jak napsat plugin pro nopCommerce 5.00. Vysvětlí vám, jaké kroky jsou nutné k vytvoření pluginu.

Platební metoda je tedy ve skutečnosti běžný plugin, který implementuje rozhraní IPaymentMethod (jmenný prostor Nop.Services.Payments). Jak jste již jistě uhodli, rozhraní IPaymentMethod se používá k vytváření pluginů platebních metod. Obsahuje některé metody specifické pouze pro platební metody, například ProcessPaymentAsync() nebo GetAdditionalHandlingFeeAsync(). Přidejte tedy do solution nový projekt platebního pluginu (class library) a pojďme začít.

Controllery, view, modely

Nejprve je potřeba vytvořit controller. Tento controller je zodpovědný za odpovídání na požadavky zaslané webu ASP.NET MVC.

  1. Při implementaci nové platební metody by měl být tento controller odvozen od speciální abstraktní třídy BasePaymentController.

  2. Poté implementujte metody akcí Configure, které slouží ke konfiguraci pluginu (majitelem obchodu v administraci). Tato metoda a odpovídající view definují, jak majitel obchodu uvidí možnosti konfigurace v administraci (Systém → Konfigurace → Platební metody).

Veřejná view komponenta.GetPublicViewComponent

Poté musíte vytvořit view komponentu pro zobrazení pluginu ve veřejném obchodě. Tato view komponenta a odpovídající view definují, jak vaši zákazníci uvidí stránku s platebními informacemi během pokladny. Nejprve vytvořme třídu view komponenty. Měla by být umístěna ve složce /Components. Podívejte se, jak je to provedeno v pluginu PayPalCommerce:

public class PaymentInfoViewComponent : NopViewComponent
{
    public IViewComponentResult Invoke(string widgetZone, object additionalData)
    {
        return View("~/Plugins/Payments.PayPalCommerce/Views/Public/PaymentInfo.cshtml");
    }
}

Metoda Invoke vrací odpovídající view PaymentInfo ze složky /Views vašeho pluginu. Všimněte si, že jako základní třídu používáme naši vlastní třídu NopViewComponent namísto existující vestavěné ViewComponent.

Poté vytvořme view PaymentInfo, které zobrazuje platební informace. V něm pouze vykreslíme text oznamující, že zákazník bude přesměrován na platební stránku. V případě potřeby je však možné vytvořit i složitější view komponentu. Pokud například chcete na stránce s platebními informacemi shromažďovat informace o zákazníkovi, podívejte se, jak je to již provedeno v platebním pluginu PayPalDirect.

Zpracování platby

Nyní musíte vytvořit třídu, která implementuje rozhraní IPaymentMethod. Právě tato třída bude vykonávat veškerou skutečnou práci při komunikaci s vaší platební bránou. Když někdo vytvoří objednávku, zavolá se buď metoda ProcessPayment, nebo PostProcessPayment vaší třídy. Takto je definována třída CheckMoneyOrderPaymentProcessor (platební metoda CheckMoneyOrder):

public class CheckMoneyOrderPaymentProcessor : BasePlugin, IPaymentMethod

Rozhraní IPaymentMethod má několik metod a vlastností, které je nutné implementovat.

  • ValidatePaymentFormAsync se používá ve veřejném obchodě k ověření vstupu zákazníka. Vrací seznam varování (například že zákazník nezadal jméno na platební kartě). Pokud vaše platební metoda nežádá po zákazníkovi zadání dalších informací, měla by ValidatePaymentFormAsync vrátit prázdný seznam:

    public Task<IList<string>> ValidatePaymentFormAsync(IFormCollection form)
    {
        return Task.FromResult<IList<string>>(new List<string>());
    }
    
  • Metoda GetPaymentInfoAsync se používá ve veřejném obchodě ke zpracování vstupu zákazníka, například informací o platební kartě. Tato metoda vrací objekt ProcessPaymentRequest se zpracovaným vstupem zákazníka (například informacemi o platební kartě). Pokud vaše platební metoda nežádá po zákazníkovi zadání dalších informací, vrátí GetPaymentInfoAsync prázdný objekt ProcessPaymentRequest:

    public Task<ProcessPaymentRequest> GetPaymentInfoAsync(IFormCollection form)
    {
        return Task.FromResult(new ProcessPaymentRequest());
    }
    
  • ProcessPaymentAsync. Tato metoda se vždy volá těsně předtím, než zákazník odešle objednávku. Použijte ji, když potřebujete zpracovat platbu před uložením objednávky do databáze. Například stržení (capture) nebo autorizaci platby kartou. Obvykle se tato metoda používá, když zákazník není k dokončení platby přesměrován na web třetí strany a všechny platby se zpracovávají na vašem webu (například PayPalCommerce).

    public Task<ProcessPaymentResult> ProcessPaymentAsync(ProcessPaymentRequest processPaymentRequest)
    {
        return Task.FromResult(new ProcessPaymentResult());
    }
    
  • PostProcessPaymentAsync. Tato metoda se volá hned poté, co zákazník odešle objednávku. Obvykle se používá, když potřebujete zákazníka k dokončení platby přesměrovat na web třetí strany (například PayPal Standard).

  • HidePaymentMethodAsync. Sem můžete vložit libovolnou logiku. Například skrýt tuto platební metodu, pokud jsou všechny produkty v košíku stahovatelné. Nebo skrýt tuto platební metodu, pokud je aktuální zákazník z určité země.

  • GetAdditionalHandlingFeeAsync. Můžete vrátit libovolné dodatečné manipulační poplatky, které budou přičteny k celkové částce objednávky.

  • CaptureAsync. Některé platební brány umožňují platby nejprve autorizovat a teprve poté strhnout. Majitelé obchodů tak mohou před provedením platby zkontrolovat podrobnosti objednávky. V takovém případě platbu pouze autorizujete v metodě ProcessPaymentAsync nebo PostProcessPaymentAsync (popsáno výše) a poté ji jen strhnete. V tomto případě bude na stránce podrobností objednávky v administraci viditelné tlačítko Strhnout (Capture). Upozorňujeme, že objednávka by již měla být autorizována a vlastnost SupportCapture by měla vracet true.

  • RefundAsync. Tato metoda umožňuje provést refundaci. V tomto případě bude na stránce podrobností objednávky v administraci viditelné tlačítko Refundovat (Refund). Upozorňujeme, že objednávka by měla být zaplacena a vlastnost SupportRefund nebo SupportPartiallyRefund by měla vracet true.

  • VoidAsync. Tato metoda umožňuje zrušit autorizovanou, ale dosud nestrženou platbu. V tomto případě bude na stránce podrobností objednávky v administraci viditelné tlačítko Zrušit platbu (Void). Upozorňujeme, že objednávka by měla být autorizována a vlastnost SupportVoid by měla vracet true.

  • ProcessRecurringPaymentAsync. Tuto metodu použijte ke zpracování opakovaných plateb.

  • CancelRecurringPaymentAsync. Tuto metodu použijte ke zrušení opakovaných plateb.

  • CanRePostProcessPaymentAsync. Obvykle se tato metoda používá, když zákazníka k dokončení platby přesměrovává na web třetí strany. Pokud platba u třetí strany selže, umožní tato možnost zákazníkům pokusit se o zaplacení objednávky později, aniž by museli vytvářet novou objednávku. Aby byla tato funkce povolena, měla by CanRePostProcessPaymentAsync vracet true.

  • GetConfigurationPageUrl. Jak si pamatujete, v předchozím kroku jsme vytvořili controller. Tato metoda by měla vracet URL jeho metody Configure. Například:

    public override string GetConfigurationPageUrl()
    {
        return $"{_webHelper.GetStoreLocation()}Admin/PaymentCheckMoneyOrder/Configure";
    }
    
  • GetPaymentMethodDescriptionAsync. Tato metoda získá popis platební metody, který se zobrazí na stránkách pokladny ve veřejném obchodě.

    public async Task<string> GetPaymentMethodDescriptionAsync()
    {
        return await _localizationService.GetResourceAsync("Plugins.Payment.CheckMoneyOrderPaymentMethodDescription");
    }
    
  • SupportCapture, SupportPartiallyRefund, SupportRefund, SupportVoid. Tyto vlastnosti udávají, zda jsou podporovány příslušné metody platební metody.

  • RecurringPaymentType. Tato vlastnost udává, zda jsou podporovány opakované platby.

  • PaymentMethodType. Tato vlastnost udává typ platební metody. V současné době existují tři typy. Standard používají platební metody, kdy zákazník není přesměrován na web třetí strany. Redirection se používá, když je zákazník přesměrován na web třetí strany. A Button je podobný platebním metodám Redirection. Jediný rozdíl spočívá v tom, že se zobrazuje jako tlačítko na stránce nákupního košíku (například Google Checkout).

  • SkipPaymentInfo. Udává, zda se má pro tento plugin zobrazovat stránka s platebními informacemi.

Závěr

Doufáme, že vám to pomůže začít s přidáváním nové platební metody.