Payment
We've significantly improved the way JS-driven payment methods are built since version 1.3.6. When developing a payment method, you'll need to consider using this enhanced version of the API, bearing in mind that this will require developers to use at least 1.3.5 or higher, which means they'll need to upgrade their entire checkout. Please take this into consideration when you start development. We always encourage our customers to upgrade to the latest version to benefit from ongoing improvements in stability, performance, and security. However, this isn't always feasible, and you can't assume everyone will have upgraded.
Since: 1.0.0
Payment methods in Hyvä Checkout can be handled in two ways: either through PHP using a Place Order Service (which we recommend), or by using our frontend Payment API, which has undergone a refactor since version released in 1.3.6.
Examples
registerMethod
Since version 1.3.6, you can register a method without worrying about activation, as we've already handled that for you. Registering a method requires
a code and an object containing optional methods which will override the defaults.
Since: 1.3.6
Parameters:
options(object) - Configuration object for the payment methodcode(string, required) - Unique identifier for the payment methodmethod(object, required) - Payment method implementation with optional override methods
Returns:
object- The registered payment method object
The example below shows all available methods, but as mentioned, they're all optional. Some will receive a fallback function, which is the default system order placement method and can be used if needed.
<script>
(() => {
hyvaCheckout.payment.registerMethod({
// Code needs to be identical to the payment method code.
code: 'hyva',
method: {
/*
* Runs each time the payment method is initialized. This occurs either when the method is activated
* or when you navigate from a different step to the step where the payment method is loaded.
* Bear this in mind when running code during initialization.
*/
initialize: async function() {
console.log('Initializing payment method', this.code);
},
/*
* Runs each time the payment method is deactivated or cleaned up. This occurs when switching to a
* different payment method or checkout step. Use this to remove event listeners, clear intervals, reset state,
* or perform any necessary cleanup to prevent memory leaks.
*/
uninitialize: async function() {
console.log('Un-initializing payment method', this.code);
},
/*
* Validation is automatically registered as native validation via `hyvaCheckout.validation`.
* Here we simulate a validation callback using a timeout within a Promise to replicate an external API call.
* Please remember, this doesn't run before placing the order, except when your payment method sits on the
* last step (which you can never be certain of).
*
* When you want to validate anything before placing the order, you should do this within the placeOrder method.
*/
validate: async function() {
console.log('Hyvä Payment: validation simulation started.');
return new Promise(resolve => setTimeout(() => {
console.log('Hyvä Payment: validation simulation stopped.');
// When return false, make sure you alert the customer
// using for instance, the hyvaCheckout.messenger API.
resolve(true)
}, 2000));
},
/*
* This is the primary place order handler, which can either fall back to the core's place order handler
* (which runs through the server via a Place Order Service), or can be fully bespoke, giving you complete control.
*
* A combination of both approaches is also possible if you need to run specific logic before placing the order.
*/
placeOrder: async function({ fallback }) {
console.log('My custom place order method ran successfully. Continuing using the fallback...');
fallback();
},
/*
* Returns either true or false, letting the order placement handler know whether the order is allowed to be placed. This can
* be done by first fetching an external or internal API to check specifics before proceeding.
*
* Please bear in mind, a redirect will always occur. This only tells the order handler to use
* the URL from your custom getRedirectUrl, which may still fall back to the given fallback.
*/
canPlaceOrder: async function() {...}
/*
* Will receive the exception as soon as something goes wrong during order placement.
*
* Either you fully handle the exception, taking responsibility for the UX, or you can use the
* fallback to rely on our default handling without having to worry about it,
* whilst still being able to perform custom logic.
*/
handleException: async function({ exception, fallback }) {...}
/*
* Normally, this should always return true. The only exception would be when the quote has not yet
* been converted into an order object. This is a rare situation, but it can happen.
*
* If set to false, you are still responsible for what happens next, since the checkout has already placed the order,
* meaning the main component can no longer render components that were relying on the quote,
* which is no longer available. Returning false is therefore not recommended.
*/
canRedirect: async function() {...}
/*
* Returns a string with either an internal URL starting with a forward slash, or a fully-fledged
* https:// prefixed URL including a domain and optional query parameters.
*/
getRedirectUrl: async function({ fallback }) {...}
}
});
})();
</script>
getActive
Returns the object that is currently being used to handle the placement of the order.
Returns:
objectnull- If no method is active.
hasActive
Returns either true or false depending on whether a method is active.
Returns:
boolean
getDefaultMethod
Returns the default order placement object, which also serves as the fallback provided to the placeOrder method in payment method object.
This default handler executes our core Place Order Service logic via the server.
Since: 1.3.6
Returns:
object- The default method defined within thehyvaCheckout.configusing pathpayment.method_default.
getByCode
Returns the registered payment method that matches the specified code, or null if no matching method exists.
Deprecated: Since 1.3.6
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
activate
Deprecated: Since 1.3.6
Reason for Deprecation: Rather than hijacking the checkout or leaving method activation to external systems (which could lead to conflicts), we've abstracted activation into a simple registration process. This makes the system aware of available methods, allowing it to automatically select the appropriate method when handling order placement.
isVisibleInStep
Deprecated: Since 1.3.6
Reason for Deprecation: Due to Hyvä Checkout's flexible architecture, payment methods can be positioned across multiple checkout steps, making reliance on DOM element visibility unreliable. Payment method implementations should be data-driven rather than dependent on DOM element states (such as field values).
Security Philosophy: Every payment method operates differently, and data protection should always be the highest priority.
Therefore, we don't dictate how or where sensitive data should be stored - we leave this decision to the developer, giving you complete freedom to choose whatever solution works best for you, provided it remains secure.
This variety in implementation approaches inherently enhances security by avoiding predictable patterns.
placeOrderViaJs
Deprecated: Since 1.3.6
Reason for Deprecation: Since version 1.3.6, all orders are placed via JavaScript, meaning either the custom active method object is used (which can fall back to the default), or the default JavaScript-driven logic runs.
Therefore, we no longer need to determine whether your method requires special handling. Everything is treated uniformly,
simplifying the implementation and eliminating confusion about when to return true or false.
isWireComponent
Deprecated since: 1.3.6
Reason for Deprecation: Since Magewire is the primary engine behind Hyvä Checkout, utilising it where possible is considered best practice. However, since version 1.3.6, we don't prescribe specific implementation methods or technologies.
This decision is entirely left to the payment method developer, with the option to fall back on our default Magewire-driven implementation. Even this default technology choice is abstracted away, allowing us to evolve the underlying architecture in future without requiring changes to existing integrations.