Payment Method Registration API for Hyvä Checkout
Since: 1.0.0
The hyvaCheckout.payment sub-namespace provides methods for registering and managing JavaScript-driven payment methods in Hyvä Checkout. Payment methods can be implemented in two ways: server-side using a Place Order Service (recommended), or client-side using this Frontend Payment API.
Version Compatibility
The Payment API was significantly improved in version 1.3.6. Payment methods using this enhanced API require Hyvä Checkout 1.3.5 or higher. Consider your target audience's upgrade path when choosing implementation approaches.
Recommended Approach
We encourage upgrading to the latest version for improved stability, performance, and security. However, not all merchants can upgrade immediately, so plan accordingly.
Examples
registerMethod
Registers a JavaScript-driven payment method with the checkout system. Since version 1.3.6, registered methods are automatically activated when selected—no manual activation required.
Since: 1.3.6
Parameters:
options(object) - Configuration object for the payment methodcode(string, required) - Unique identifier matching the Magento payment method codemethod(object, required) - Payment method implementation with optional override methods
Returns:
object- The registered payment method object
Available Method Overrides
All methods in the method object are optional. Each receives relevant context and can return Promises for async operations.
The following example demonstrates all available method overrides with inline documentation explaining each method's purpose and execution timing.
Complete payment method registration with all available overrides
<script>
(() => {
hyvaCheckout.payment.registerMethod({
// Payment method code must match Magento's payment method code exactly
code: 'my_payment_method',
method: {
/**
* Runs when the payment method is initialized or re-activated.
* Called when: method is selected, or user navigates to the payment step.
* Use for: SDK initialization, iframe loading, event listener setup.
*/
initialize: async function() {
console.log('Initializing payment method:', this.code);
},
/**
* Runs when the payment method is deactivated or cleaned up.
* Called when: switching to another payment method or checkout step.
* Use for: removing event listeners, clearing intervals, resetting state.
*/
uninitialize: async function() {
console.log('Cleaning up payment method:', this.code);
},
/**
* Validates the payment method before step progression.
* Registered automatically via hyvaCheckout.validation.
* NOTE: Does NOT run before placeOrder unless payment is on the final step.
* For pre-order validation, perform checks inside placeOrder instead.
*/
validate: async function() {
// Return false to prevent step progression
// Alert the customer using hyvaCheckout.messenger API on failure
return true;
},
/**
* Primary order placement handler.
* The fallback parameter contains the default server-side Place Order Service.
* Options: use fallback entirely, implement custom logic, or combine both.
*/
placeOrder: async function({ fallback }) {
console.log('Custom pre-order logic completed.');
// Call fallback() to use default Magewire-driven order placement
fallback();
},
/**
* Determines if order placement should proceed.
* Return false to prevent order placement and use custom getRedirectUrl.
* Note: A redirect always occurs—this controls which URL is used.
*/
canPlaceOrder: async function() {
return true;
},
/**
* Handles exceptions during order placement.
* Either handle the exception entirely (managing UX yourself),
* or call fallback() to use default error handling.
*/
handleException: async function({ exception, fallback }) {
console.error('Order placement failed:', exception);
fallback(); // Use default error handling
},
/**
* Determines if redirect should occur after order placement.
* Normally returns true. Return false only when quote hasn't
* converted to an order yet (rare edge case).
* WARNING: Returning false is not recommended as checkout components
* rely on the quote which becomes unavailable after order placement.
*/
canRedirect: async function() {
return true;
},
/**
* Returns the post-order redirect URL.
* Return: internal path (e.g., '/checkout/success') or
* full URL (e.g., 'https://payment-gateway.com/complete?order=123').
* The fallback parameter provides the default success page URL.
*/
getRedirectUrl: async function({ fallback }) {
return fallback();
}
}
});
})();
</script>
getActive
Returns the currently active payment method object that handles order placement, or null if no method is active.
Returns:
object- The active payment method objectnull- If no payment method is currently active
hasActive
Checks whether a payment method is currently active.
Returns:
boolean-trueif a payment method is active,falseotherwise
getDefaultMethod
Returns the default order placement handler, which is also provided as the fallback parameter in placeOrder. This default handler executes the core Place Order Service logic via Magewire on the server.
Since: 1.3.6
Returns:
object- The default method defined inhyvaCheckout.configat pathpayment.method_default
getByCode
Retrieves a registered payment method by its code.
Parameters:
code(string, required) - The payment method code to search for
Returns:
object- The registered payment method object if foundnull- If no method is registered for the given code
Deprecated Methods
The following methods are deprecated since version 1.3.6 and should not be used in new implementations.
activate
Deprecated: Since 1.3.6
Reason: Registration now handles activation automatically. The checkout system selects the appropriate registered method during order placement, eliminating potential conflicts from manual activation.
Since version 1.3.7, check __viaHcPaymentActivate = true on the method object to identify legacy JavaScript payment methods using this deprecated approach.
isVisibleInStep
Deprecated: Since 1.3.6
Reason: Hyvä Checkout's flexible architecture allows payment methods across multiple steps, making DOM visibility unreliable. Payment implementations should be data-driven rather than dependent on DOM element states.
Security Note: Payment methods operate differently and require different data protection approaches. We intentionally do not prescribe how or where sensitive data should be stored—this decision belongs to the developer. This implementation variety inherently enhances security by avoiding predictable patterns.
placeOrderViaJs
Deprecated: Since 1.3.6
Reason: Since version 1.3.6, all orders are placed via JavaScript. The active registered method handles placement (falling back to default if needed), eliminating the need to distinguish between JS-driven and server-driven methods.
isWireComponent
Deprecated: Since 1.3.6
Reason: While Magewire is the primary engine behind Hyvä Checkout, the API no longer prescribes specific implementation technologies. Developers choose their approach, with the option to fall back on default Magewire-driven implementation. The underlying technology is abstracted, allowing future architectural evolution without breaking existing integrations.