Payment and Carrier Modules

pcffpayment/
  pcffpayment.php                      PaymentModule: hooks, options, order state, session table
  composer.json                        PSR-4 for PrestaShop\Module\Pcffpayment\
  config/services.yml                  registers the console command
  controllers/front/validation.php     offline method: creates the order
  controllers/front/redirect.php       external and embedded methods: records the payment session
  controllers/front/psp.php            stand-in for the provider's hosted page
  controllers/front/callback.php       signed notification: the only place that creates the order
  controllers/front/confirmation.php   where the customer's browser comes back to
  src/Controller/AbstractPaymentController.php   checks shared by the customer-facing controllers
  src/Service/Signature.php            HMAC computation and constant-time verification
  src/Command/TryAmountCommand.php     console diagnostic for validateOrder()
  views/templates/front/*.tpl          option texts and the stub page
  views/templates/hook/payment-return.tpl        text on the confirmation page

<?php

declare(strict_types=1);

use PrestaShop\Module\Pcffpayment\Service\Signature;
use PrestaShop\PrestaShop\Core\Payment\PaymentOption;

if (!defined('_PS_VERSION_')) {
    exit;
}

if (file_exists(__DIR__ . '/vendor/autoload.php')) {
    require_once __DIR__ . '/vendor/autoload.php';
}

class Pcffpayment extends PaymentModule
{
    public const CONFIG_SECRET = 'PCFFPAYMENT_SECRET';
    public const CONFIG_OS_PICKUP = 'PCFFPAYMENT_OS_PICKUP';

    public function __construct()
    {
        $this->name = 'pcffpayment';
        $this->tab = 'payments_gateways';
        $this->version = '1.0.0';
        $this->author = 'Pocket Coffee';
        $this->controllers = ['validation', 'redirect', 'psp', 'callback', 'confirmation'];
        $this->currencies = true;
        $this->currencies_mode = 'checkbox';
        $this->ps_versions_compliancy = ['min' => '9.0.0', 'max' => '9.99.99'];
        $this->bootstrap = true;

        parent::__construct();

        $this->displayName = $this->trans('Pocket Coffee payments', [], 'Modules.Pcffpayment.Admin');
        $this->description = $this->trans('Pay at pickup, pay through a hosted page, or enter a card in the checkout.', [], 'Modules.Pcffpayment.Admin');
    }

    public function isUsingNewTranslationSystem(): bool
    {
        return true;
    }

    public function install(): bool
    {
        // PaymentModule::install() also fills module_currency, module_country, module_carrier and,
        // through Module::install(), module_group for everything that exists right now
        if (!parent::install()
            || !$this->registerHook('paymentOptions')
            || !$this->registerHook('paymentReturn')
            || !$this->installOrderState()
            || !$this->installDatabase()) {
            return false;
        }

        // Shared secret of the payment provider; in production it comes from the provider's dashboard
        return Configuration::updateValue(self::CONFIG_SECRET, Tools::passwdGen(40));
    }

    public function uninstall(): bool
    {
        return Db::getInstance()->execute('DROP TABLE IF EXISTS `' . _DB_PREFIX_ . 'pcffpayment_session`')
            && Configuration::deleteByName(self::CONFIG_SECRET)
            && parent::uninstall();
    }

    private function installOrderState(): bool
    {
        if ((int) Configuration::get(self::CONFIG_OS_PICKUP) > 0) {
            return true;
        }

        $state = new OrderState();
        $state->name = [];
        foreach (Language::getLanguages(false) as $language) {
            $state->name[$language['id_lang']] = 'es' === $language['iso_code'] ? 'Pendiente de pago en tienda' : 'Awaiting payment at pickup';
        }
        $state->module_name = $this->name;
        $state->color = '#34209E';
        $state->send_email = false;
        $state->invoice = false;
        $state->logable = false;
        $state->paid = false;
        $state->unremovable = false;

        return $state->add() && Configuration::updateValue(self::CONFIG_OS_PICKUP, (int) $state->id);
    }

    private function installDatabase(): bool
    {
        return Db::getInstance()->execute(
            'CREATE TABLE IF NOT EXISTS `' . _DB_PREFIX_ . 'pcffpayment_session` (
                `id_pcffpayment_session` INT UNSIGNED NOT NULL AUTO_INCREMENT,
                `token` CHAR(32) NOT NULL,
                `id_cart` INT UNSIGNED NOT NULL,
                `amount` DECIMAL(20,6) NOT NULL,
                `id_currency` INT UNSIGNED NOT NULL,
                `date_add` DATETIME NOT NULL,
                PRIMARY KEY (`id_pcffpayment_session`),
                UNIQUE KEY `token` (`token`)
            ) ENGINE=' . _MYSQL_ENGINE_ . ' DEFAULT CHARSET=utf8mb4'
        );
    }

    /**
     * @param array{cart: Cart} $params
     *
     * @return PaymentOption[]
     */
    public function hookPaymentOptions(array $params): array
    {
        if (!$this->active || !$this->checkCurrency($params['cart'])) {
            return [];
        }

        $link = $this->context->link;

        // 1. Offline: the order is created right away and the customer pays in the shop
        $pickup = new PaymentOption();
        $pickup->setModuleName($this->name)
            ->setCallToActionText($this->trans('Pay at pickup in Madrid', [], 'Modules.Pcffpayment.Shop'))
            ->setAction($link->getModuleLink($this->name, 'validation', [], true))
            ->setAdditionalInformation($this->fetch('module:pcffpayment/views/templates/front/option-pickup.tpl'));

        // 2. External: the customer leaves the shop; the order exists only after the provider confirms
        $hosted = new PaymentOption();
        $hosted->setModuleName($this->name)
            ->setCallToActionText($this->trans('Pay by card on the PCFF Pay page', [], 'Modules.Pcffpayment.Shop'))
            ->setAction($link->getModuleLink($this->name, 'redirect', [], true))
            ->setInputs(['option' => ['name' => 'option', 'type' => 'hidden', 'value' => 'hosted']]);

        // 3. Embedded: a form shown inside the checkout (PrestaShop adds the submit button)
        $embedded = new PaymentOption();
        $embedded->setModuleName($this->name)
            ->setCallToActionText($this->trans('Pay with a card here', [], 'Modules.Pcffpayment.Shop'))
            ->setAction($link->getModuleLink($this->name, 'redirect', [], true))
            ->setForm($this->fetch('module:pcffpayment/views/templates/front/option-embedded.tpl'));

        return [$pickup, $hosted, $embedded];
    }

    /**
     * @param array{order: Order} $params
     */
    public function hookPaymentReturn(array $params): string
    {
        if (!$this->active || !isset($params['order']) || $params['order']->module !== $this->name) {
            return '';
        }

        $this->smarty->assign([
            'reference' => $params['order']->reference,
            'total' => $this->context->getCurrentLocale()->formatPrice($params['order']->getOrdersTotalPaid(), (new Currency((int) $params['order']->id_currency))->iso_code),
        ]);

        return $this->fetch('module:pcffpayment/views/templates/hook/payment-return.tpl');
    }

    public function checkCurrency(Cart $cart): bool
    {
        $currencyOrder = new Currency((int) $cart->id_currency);
        $allowed = $this->getCurrency((int) $cart->id_currency);

        if (is_array($allowed)) {
            foreach ($allowed as $currency) {
                if ($currencyOrder->id == $currency['id_currency']) {
                    return true;
                }
            }
        }

        return false;
    }

    public static function sign(string $payload): string
    {
        return Signature::compute($payload, (string) Configuration::get(self::CONFIG_SECRET));
    }
}

{* views/templates/front/option-pickup.tpl *}
<p>{l s='Reserve your order now and pay when you collect it at our Madrid roastery.' d='Modules.Pcffpayment.Shop'}</p>

{* views/templates/front/option-embedded.tpl *}
<div class="pcffpayment-embedded">
  <label for="pcffpayment-card-holder">{l s='Card holder' d='Modules.Pcffpayment.Shop'}</label>
  <input type="text" id="pcffpayment-card-holder" name="card_holder" autocomplete="cc-name">
  <input type="hidden" name="option" value="embedded">
</div>

{* views/templates/hook/payment-return.tpl *}
<p class="pcffpayment-return">{l s='Thank you. Order %reference% for %total% was registered.' sprintf=['%reference%' => $reference, '%total%' => $total] d='Modules.Pcffpayment.Shop'}</p>

// Inside the payment module's own submit handler (smart button, hosted fields, redirect)
try {
  await window.ps_onepagecheckout.submitBeforePayment();
  // the customer, the address and the delivery method are saved; start the payment flow
  startMyPaymentFlow();
} catch (error) {
  // the single page is not there or the preconditions are not met: do not start the payment
}

// Widgets inside the payment section must be created again when the section is refreshed
prestashop.on('opcPaymentMethodsUpdated', () => {
  remountMyPaymentWidgets();
});

<?php

declare(strict_types=1);

if (!defined('_PS_VERSION_')) {
    exit;
}

class Pcffcarrier extends CarrierModule
{
    /** Stable identifier of the carrier: id_reference does not change when the carrier is edited */
    public const CONFIG_REFERENCE = 'PCFFCARRIER_ID_REFERENCE';
    public const CONFIG_BASE_COST = 'PCFFCARRIER_BASE_COST';
    public const CONFIG_MAX_WEIGHT = 'PCFFCARRIER_MAX_WEIGHT';

    public function __construct()
    {
        $this->name = 'pcffcarrier';
        $this->tab = 'shipping_logistics';
        $this->version = '1.0.0';
        $this->author = 'Pocket Coffee';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = ['min' => '9.0.0', 'max' => '9.99.99'];

        parent::__construct();

        $this->displayName = $this->trans('Pocket Coffee roastery pickup', [], 'Modules.Pcffcarrier.Admin');
        $this->description = $this->trans('A carrier whose price is computed by the module.', [], 'Modules.Pcffcarrier.Admin');
    }

    public function isUsingNewTranslationSystem(): bool
    {
        return true;
    }

    public function install(): bool
    {
        return parent::install()
            && $this->registerHook('actionCarrierUpdate')
            && $this->registerHook('displayCarrierExtraContent')
            && $this->registerHook('actionValidateStepComplete')
            && $this->installDatabase()
            && Configuration::updateValue(self::CONFIG_BASE_COST, '3.50')
            && Configuration::updateValue(self::CONFIG_MAX_WEIGHT, '5')
            && $this->createCarrier();
    }

    public function uninstall(): bool
    {
        Db::getInstance()->execute('DROP TABLE IF EXISTS `' . _DB_PREFIX_ . 'pcffcarrier_pickup`');

        $carrier = Carrier::getCarrierByReference((int) Configuration::get(self::CONFIG_REFERENCE));
        if (Validate::isLoadedObject($carrier)) {
            // Carrier::delete() only flags the carrier as deleted when orders use it, so old orders keep their carrier
            $carrier->delete();
        }

        return Configuration::deleteByName(self::CONFIG_REFERENCE)
            && Configuration::deleteByName(self::CONFIG_BASE_COST)
            && Configuration::deleteByName(self::CONFIG_MAX_WEIGHT)
            && parent::uninstall();
    }

    private function installDatabase(): bool
    {
        return Db::getInstance()->execute(
            'CREATE TABLE IF NOT EXISTS `' . _DB_PREFIX_ . 'pcffcarrier_pickup` (
                `id_cart` INT UNSIGNED NOT NULL,
                `pickup_day` VARCHAR(16) NOT NULL,
                PRIMARY KEY (`id_cart`)
            ) ENGINE=' . _MYSQL_ENGINE_ . ' DEFAULT CHARSET=utf8mb4'
        );
    }

    private function createCarrier(): bool
    {
        $carrier = new Carrier();
        $carrier->name = 'PCFF Roastery pickup';
        $carrier->active = true;
        $carrier->deleted = false;
        $carrier->is_free = false;
        $carrier->is_module = true;
        $carrier->shipping_external = true;
        $carrier->external_module_name = $this->name;
        // The checkout only lists carrier modules that need a range (is_module = 0 OR need_range = 1):
        // the range supplies the base price, getOrderShippingCost() adjusts it
        $carrier->need_range = true;
        $carrier->shipping_method = Carrier::SHIPPING_METHOD_WEIGHT;
        $carrier->shipping_handling = false;
        // 1 = deactivate the carrier when the cart is outside every range
        $carrier->range_behavior = 1;
        $carrier->max_weight = (float) Configuration::get(self::CONFIG_MAX_WEIGHT);
        $carrier->grade = 9;
        $carrier->url = '';
        $carrier->delay = [];
        foreach (Language::getLanguages(false) as $language) {
            $carrier->delay[$language['id_lang']] = 'es' === $language['iso_code'] ? 'Recogida en el tostadero' : 'Collect at the roastery';
        }

        if (!$carrier->add()) {
            return false;
        }

        // add() sets id_reference in the database only: reload the object to read it
        $carrier = new Carrier((int) $carrier->id);

        // The new carrier must be reachable by every customer group and deliverable to the Pocket Coffee zones
        $carrier->setGroups(array_column(Group::getGroups((int) Context::getContext()->language->id), 'id_group'));

        // One weight range (0 to 5 kg) with the base price in each zone
        $range = new RangeWeight();
        $range->id_carrier = (int) $carrier->id;
        $range->delimiter1 = 0;
        $range->delimiter2 = (float) Configuration::get(self::CONFIG_MAX_WEIGHT);
        $range->add();
        $prices = [];
        foreach ([9, 10] as $idZone) {
            $carrier->addZone($idZone);
            $prices[] = [
                'id_range_weight' => (int) $range->id,
                'id_range_price' => false,
                'id_carrier' => (int) $carrier->id,
                'id_zone' => $idZone,
                'price' => (float) Configuration::get(self::CONFIG_BASE_COST),
            ];
        }
        $carrier->addDeliveryPrice($prices);
        // Payment modules only offer themselves for carriers listed in module_carrier
        foreach (Module::getPaymentModules() as $paymentModule) {
            Db::getInstance()->insert('module_carrier', [
                'id_module' => (int) $paymentModule['id_module'],
                'id_shop' => (int) $this->context->shop->id,
                'id_reference' => (int) $carrier->id_reference,
            ], false, true, Db::INSERT_IGNORE);
        }

        return Configuration::updateValue(self::CONFIG_REFERENCE, (int) $carrier->id_reference);
    }

    /**
     * Called by the core for a carrier that uses ranges. $shipping_cost is the price found in the range.
     * Return the price tax excluded, or false when the carrier cannot deliver this cart.
     *
     * @param Cart $params
     * @param float $shipping_cost
     *
     * @return float|false
     */
    public function getOrderShippingCost($params, $shipping_cost)
    {
        $weight = (float) $params->getTotalWeight();
        if ($weight > (float) Configuration::get(self::CONFIG_MAX_WEIGHT)) {
            return false;
        }

        // Range price plus 0.60 for every started kilogram above the first one
        $extraKilos = max(0, (int) ceil($weight) - 1);

        return (float) $shipping_cost + 0.60 * $extraKilos;
    }

    /**
     * Only called for a carrier created without ranges (need_range = 0); the 9.2 checkout never lists such a carrier.
     *
     * @param Cart $params
     *
     * @return float|false
     */
    public function getOrderShippingCostExternal($params)
    {
        return $this->getOrderShippingCost($params, (float) Configuration::get(self::CONFIG_BASE_COST));
    }

    /**
     * An edited carrier is a copy with a new id_carrier: this hook receives both ids.
     * The module stores id_reference, so it has nothing to migrate, but it records the change.
     *
     * @param array{id_carrier: int, carrier: Carrier} $params
     */
    public function hookActionCarrierUpdate(array $params): void
    {
        if ((int) $params['carrier']->id_reference === (int) Configuration::get(self::CONFIG_REFERENCE)) {
            PrestaShopLogger::addLog(
                sprintf('pcffcarrier: carrier %d was replaced by %d', (int) $params['id_carrier'], (int) $params['carrier']->id),
                1,
                null,
                'Carrier',
                (int) $params['carrier']->id,
                true
            );
        }
    }

    /**
     * Extra HTML shown under the carrier in the delivery step.
     *
     * @param array{carrier: array{id: int|string}} $params
     */
    public function hookDisplayCarrierExtraContent(array $params): string
    {
        $current = Carrier::getCarrierByReference((int) Configuration::get(self::CONFIG_REFERENCE));
        if (!Validate::isLoadedObject($current) || (int) $params['carrier']['id'] !== (int) $current->id) {
            return '';
        }

        return $this->fetch('module:pcffcarrier/views/templates/hook/extra-content.tpl');
    }

    /**
     * Runs when the customer confirms the delivery step with a module carrier selected. Setting
     * $params['completed'] to false keeps the checkout on the delivery step.
     *
     * @param array{step_name: string, request_params: array, completed: bool} $params
     */
    public function hookActionValidateStepComplete(array &$params): void
    {
        if ('delivery' !== $params['step_name']) {
            return;
        }

        $day = (string) ($params['request_params']['pcff_pickup_day'] ?? '');
        if (!in_array($day, ['tuesday', 'wednesday', 'thursday', 'friday', 'saturday'], true)) {
            $params['completed'] = false;

            return;
        }

        Db::getInstance()->insert(
            'pcffcarrier_pickup',
            ['id_cart' => (int) $this->context->cart->id, 'pickup_day' => pSQL($day)],
            false,
            true,
            Db::REPLACE
        );
    }
}

{* views/templates/hook/extra-content.tpl *}
<p class="pcffcarrier-extra">{l s='Collect your order at Calle de Alcalá 1, Madrid, Tuesday to Saturday from 10:00 to 14:00.' d='Modules.Pcffcarrier.Shop'}</p>
<fieldset class="pcffcarrier-days">
  <legend>{l s='Pickup day' d='Modules.Pcffcarrier.Shop'}</legend>
  {foreach from=['tuesday', 'wednesday', 'thursday', 'friday', 'saturday'] item=day}
    <label><input type="radio" name="pcff_pickup_day" value="{$day}" required> {$day|capitalize}</label>
  {/foreach}
</fieldset>