Payment Integration API for Hyvä Checkout

The Payment Integration API provides the structure for registering payment methods in Hyvä Checkout, configuring display properties like icons and subtitles, and implementing the EvaluationInterface to control checkout flow based on payment status.

Registering a Payment Method

Any payment method enabled in Magento system configuration automatically appears in the checkout payment step. However, payment methods requiring customer interaction (forms, redirects, or SDK integrations) must register a template block to display their UI when selected.

Layout XML Registration

Register payment method templates as children of the checkout.payment.methods block in layout/hyva_checkout_components.xml. The block alias (as attribute) must exactly match the payment method code.

Payment Method Block Registration

<!-- File: view/frontend/layout/hyva_checkout_components.xml -->

<referenceBlock name="checkout.payment.methods">
    <block name="checkout.payment.method.checkmo"
           as="checkmo"
           template="Hyva_Checkout::component/payment/method/checkmo.phtml"/>
</referenceBlock>

Block Alias Must Match Payment Method Code

The as="checkmo" attribute must exactly match the Magento payment method code. This enables Hyvä Checkout to associate the template with the correct payment method.

The template renders when the customer selects the payment method. Payment method display order is determined by the system configuration "Sort Order" values, not by block order in layout XML.

Accessing Payment Method Data in Templates

Inside the payment template, access the \Magento\Quote\Api\Data\PaymentMethodInterface instance via the block:

Accessing Payment Method in Template

<?php
/** @var \Magento\Quote\Api\Data\PaymentMethodInterface $method */
$method = $block->getData('method');

// Access payment method properties
$methodCode = $method->getCode();
$methodTitle = $method->getTitle();

For simple payment methods that only display information (like Check/Money Order), the template alone is sufficient. See the built-in example at hyva-themes/magento2-hyva-checkout/src/view/frontend/templates/component/payment/method/checkmo.phtml.

Payment Method Display Properties

Configure frontend display properties (icons, subtitles) using metadata block arguments. Metadata extends payment methods with frontend features without modifying the Magento payment method object.

Payment Method Icon

Display an icon next to the payment method title using SVG or image files.

SVG Icons

Load SVG icons from a Hyvä icon pack extension or from your module's view/frontend/web/svg folder.

Payment Method with SVG Icon

<referenceBlock name="checkout.payment.methods">
    <block name="checkout.payment.method.checkmo"
           as="checkmo"
           template="Hyva_Checkout::component/payment/method/checkmo.phtml">
        <arguments>
            <argument name="metadata" xsi:type="array">
                <item name="icon" xsi:type="array">
                    <!-- Icon path: icon-pack-name/icon-name or module svg path -->
                    <item name="svg" xsi:type="string">payment-icons/light/paypal</item>
                    <!-- Optional: SVG attributes -->
                    <item name="attributes" xsi:type="array">
                        <item name="fill" xsi:type="string">none</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>

Since: 1.0.5

Image Icons

Load images from your module's view/frontend/web/ directory using the src argument.

Payment Method with Image Icon

<referenceBlock name="checkout.payment.methods">
    <block name="checkout.payment.method.checkmo"
           as="checkmo"
           template="Hyva_Checkout::component/payment/method/checkmo.phtml">
        <arguments>
            <argument name="metadata" xsi:type="array">
                <item name="icon" xsi:type="array">
                    <!-- Image path processed by Magento asset repository -->
                    <item name="src" xsi:type="string">Magento_Payment::images/cc/vi.png</item>
                    <!-- Optional: HTML attributes for the img tag -->
                    <item name="attributes" xsi:type="array">
                        <item name="width" xsi:type="number">100</item>
                        <item name="loading" xsi:type="string">lazy</item>
                        <item name="alt" xsi:type="string" translate="true">VISA card icon</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>

Since: 1.1.22

Payment Method Subtitle

Display a subtitle below the payment method title. The subtitle can be a static string or a system configuration path.

Payment Method with Static Subtitle

<referenceBlock name="checkout.payment.methods">
    <referenceBlock name="checkout.payment.method.checkmo">
        <arguments>
            <argument name="metadata" xsi:type="array">
                <item name="subtitle" xsi:type="string">
                    Visa, Mastercard &amp; More
                </item>
            </argument>
        </arguments>
    </referenceBlock>
</referenceBlock>

Payment Method with Config-Based Subtitle

<argument name="metadata" xsi:type="array">
    <!-- Configuration path resolves to the stored value -->
    <item name="subtitle" xsi:type="string">payment/my-psp/my-awesome-subtitle</item>
</argument>

Implementing EvaluationInterface

Payment methods requiring customer interaction should implement EvaluationInterface to control checkout flow. The interface's evaluateCompletion() method returns evaluation results that enable or disable the "Proceed" or "Place Order" button.

Evaluation Result Types for Payments

Result Type	Button State	When to Use
Blocking	Disabled	Customer has not completed required payment action
Success	Enabled	Customer has provided all required payment data

EvaluationInterface Implementation

public function evaluateCompletion(EvaluationResultFactory $factory): EvaluationResultInterface
{
    // Return Success only when all required payment data is present
    return $this->isRequiredDataPresent()
        ? $factory->createSuccess()
        : $factory->createBlocking();
}

private function isRequiredDataPresent(): bool
{
    // Check for payment token, authorization, or other required data
    // ...
}

The evaluateCompletion() method is only called when the payment method is selected. Unselected payment methods do not affect checkout flow.

Frontend Payment Phases

The following tables illustrate typical payment flows from the customer's perspective, showing how Evaluation results control button states.

Redirect to PSP Flow

Step	Customer Action	Payment UI State	Button	Evaluation
1	Visits payment step	No method selected	Shows "Please select a payment method" error	-
2	Selects payment method	Displays redirect button(s)	Disabled	Blocking
3	Clicks PSP button	Transferred to PSP website	-	-
4	Completes PSP form	PSP sends token to Magento	-	-
5	Redirected to checkout	Shows "Payment Authorized" message	Enabled	Success

Iframe/Hosted Form Flow

Step	Customer Action	Payment UI State	Button	Evaluation
1	Visits payment step	No method selected	Shows "Please select a payment method" error	-
2	Selects payment method	PSP form displays in iframe	Disabled	Blocking
3	Enters payment data	Waiting for PSP token	Disabled	Blocking
4	Completes PSP form	Shows "Payment Authorized" message	Enabled	Success