Payment Integration API

Register a payment method

Any payment method that is enabled for a store in the system configuration will be listed in the payment step.
This only makes sense for payment methods that do not need to collect any information from the customer.
All others will need to provide some form of user interaction beyond simply being selectable.

Layout XML

To display content when the payment method is selected, a block for the payment method needs to be declared as a child of the checkout.payment.methods block in the layout/hyva_checkout_components.xml file.

For example:

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

The block alias (as="...") has to match the payment method code

The name of the payment block in layout XML and the template name are not required to follow a specific convention, but we suggest you follow the example above.

The order of payment methods is defined by the system configuration "Sort Order" values, not by the order of the child blocks in layout XML.

The template will be shown on the page when the payment method is selected.

In the template, the instance of \Magento\Quote\Api\Data\PaymentMethodInterface for the payment method is available from $block->getData('method').

If the template only needs to display information, then this is all you need.
An example of this kind of simple payment method is the built-in payment method Check / Money Order.
The template can be found at hyva-themes/magento2-hyva-checkout/src/view/frontend/templates/component/payment/method/checkmo.phtml.

Additional display properties

Common frontend display properties such as a payment provider logo or a subtitle can be added to payment methods as metadata.
Metadata allows payment methods to be expanded with frontend features without the need to modify the Magento payment method object.

Metadata is added to a payment method by specifying block arguments for the method in layout XML.

Currently, supported metadata types are icons and subtitles. More may be added in the future.

Metadata is a specific feature of Hyva Checkout that is currently limited to payment methods, but will soon be implemented for shipping methods as well.

Payment Method Icon

To display an icon for a specific payment method, an argument with the name icon and the type array has to be added to the metadata array argument. The icon path is then specified in an svg child array item.
Icons can be loaded from a Hyvä icon pack extension, or they can be svg files that are added in the payment integration modules view/frontend/web/svg folder.

Additional attributes can be specified if needed.

For example:

<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">
                    <item name="svg" xsi:type="string">payment-icons/light/paypal</item>
                    <!-- optional attributes, specify as needed -->
                    <item name="attributes" xsi:type="array">
                        <item name="fill" xsi:type="string">none</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>

Payment Subtitle

A payment method may display a subtitle below the method title.

This can be accomplished by specifying a subtitle item on the block metadata array. For example:

<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>
    </block>
</referenceBlock>

If the subtitle value refers to a Magento system configuration setting, it will be displayed as the subtitle.

For example:

<argument name="metadata" xsi:type="array">
    <!-- Specifying a configuration path to the subtitle -->
    <item name="subtitle" xsi:type="string">payment/my-psp/my-awesome-subtitle</item>
</argument>

Payment integration API

Without further customization, all this will do is ensure the method code will be set on the quote payment instance, and the \Hyva\Checkout\Magewire\Main::placeOrder method is called when the Place Order button is clicked.

The main purpose of a Magewire payment component is to gather the required payment information from the customer and pass them to the selected payment method on the quote item.
Sensitive payment information is not collected directly, but rather with the help of a Payment Service Provider.

Usually, a payment method template will either render an iframe showing a form provided by the PSP, or it will show a button that will take the customer to the payment provider's website.

After a customer completes the necessary steps on the PSP website, the payment method template might change and render a confirmation message instead of the form or button.

If the Magewire payment component implements the \Hyva\Checkout\Model\Magewire\Component\EvaluationInterface it should return an Evaluation\Blocking instance if the customer has not yet completed the process with the PSP.
Otherwise, if the visitor has provided all information to the PSP, it should return an Evaluation\Success instance.

public function evaluateCompletion(EvaluationResultFactory $factory): EvaluationResultInterface
{
    // If this payment method is selected, only return a Success if all required data is present
    return $this->isRequiredDataPresent()
        ? $factory->createSuccess()
        : $factory->createBlocking();
}

private function isRequiredDataPresent(): bool {...}

A payment components evaluateCompletion method will only be called when that payment method is selected by the customer.

This ensures the "Place Order" or "Proceed to next step" button is disabled until a payment method has all the information it requires.

Frontend payment phases

The following examples describe the payment process from a customers point of view and how it is enabled by the returned Evaluation Result types.

Example: Redirect to PSP during payment method integration

Step	Customer action	State	"Proceed" or "Place Order" button	Evaluation result
1	Visits payment step.	No payment method selected.	Clicking the button shows a "Please select a payment method" error message.	-
2	Selects payment method.	Payment method displays button(s) to redirect to PSP website.	Disabled	`Blocking`
3	Clicks PSP button.	Is transferred to the PSP website.	-	-
4	Provides payment data and submits form on PSP website.	When complete the PSP transfers the payment result token to Magento.	-	-
5	Is redirected back to payment step of Hyvä Checkout.	PSP buttons are replaced with "Payment Authorized" message.	Clicking the button takes the customer to the next checkout step or starts order placement.	`Success`

Example: PHP iframe method integration

Step	Customer action	State	"Proceed" or "Place Order" button	Evaluation result
1	Visits payment step.	No payment method selected.	Clicking the button shows a "Please select a payment method" error message.	-
2	Selects payment method.	Payment method displays PSP form in iframe.	Disabled	`Blocking`
3	Provides payment data.	Waits for payment token from PSP.	Disabled	`Blocking`
4	Completes PSP form.	PSP iframe is replaced with "Payment Authorized" message.	Clicking the button takes the customer to the next checkout step or starts order placement.	`Success`