Skip to content

Payments in Hyvä Checkout

Hyvä Checkout provides a payment integration framework for implementing any payment scenario, from simple redirect methods to complex PSP SDK integrations. A Hyvä Checkout payment integration handles the frontend user interaction and complements an existing Magento Payment Method that manages backend payment processing.

Key Differences from Luma Checkout

Understanding how payment responsibilities differ between Luma and Hyvä Checkout is essential for building integrations.

Aspect Luma Checkout Hyvä Checkout
Order placement Payment method places the order Place Order Service places the order
Payment step position Must be the final step Can be positioned on any step
Data collection timing Collected immediately before order Collected whenever payment step is visited
Implementation approach JavaScript-heavy (Knockout.js) Server-side preferred (Magewire)

Payment Method Position Flexibility

Because Hyvä Checkout separates order placement from payment method selection, merchants can configure additional steps after payment (e.g., order review, gift options). Payment integrations should not assume they're on the final checkout step.

What a Payment Integration Does

A Hyvä Checkout payment integration is responsible for:

  • Displaying payment UI - Rendering forms, buttons, or PSP-provided iframes when the payment method is selected
  • Gathering payment data - Collecting tokens, authorization codes, or other data required by the PSP
  • Communicating completion status - Returning Evaluation\Success when ready to proceed, or Evaluation\Blocking when waiting for customer action
  • Storing data for order placement - Passing payment tokens to the underlying Magento Payment Method

The actual payment capture happens via the Magento Payment Method, which can often be reused from existing Luma integrations.

Implementation Approaches

Hyvä Checkout supports three approaches for building payment integrations. Choose based on your PSP's requirements and developer preference.

PHP-Driven (Magewire)

Use server-side Magewire components for payment logic. The payment template renders UI, and Magewire handles state management and PSP communication.

Best for: Payment methods with server-side token generation, redirect flows, or minimal JavaScript requirements.

JavaScript-Driven (Frontend API)

Use the Frontend Payment API for payment methods requiring client-side SDK integration. Register a payment method handler that manages initialization, validation, and order placement.

Best for: PSP SDKs that must run in the browser, client-side tokenization, or complex JavaScript payment flows.

Frontend Payment API Changes in 1.3.6

Version 1.3.6 introduced a rewritten Frontend Payment API with improved developer experience. Payment methods using the new API require Hyvä Checkout 1.3.5 or higher. See the Frontend Payment API documentation for details.

Hybrid Approach

Combine Magewire components with Frontend API methods. Use Magewire for server communication and state, with JavaScript handling browser-specific tasks like SDK initialization.

Best for: Complex integrations requiring both server-side logic and client-side SDK interaction.

Automatic Payment Method Selection

When a customer selects a payment method in Hyvä Checkout, the method code is automatically stored on the quote. No additional code is needed to handle selection—the checkout manages this automatically.

The payment integration's responsibility is to gather additional data (tokens, authorization) and signal when that data is complete.

Reusing Existing Magento Payment Methods

If a Magento Payment Method already exists for your PSP (e.g., from a Luma integration), the backend PHP code for token validation, payment capture, and order processing can typically be reused. Only the frontend interaction layer needs to be built for Hyvä Checkout.

The Hyvä Checkout payment component gathers data and passes it to the existing Magento Payment Method, which then handles the actual payment processing through its standard interfaces.