What is configured in the VivaWallet installation

Implementing VivaWallet payments in AI Commerce Cloud consists of installing the payment module, adding shared VivaWallet IDs, defining a domain-specific VivaWallet Code value, and setting webhook and return addresses.

• Configure the domain you're testing first, and only roll out the payment method more broadly after successful payment and aborted payment tests.

The same VivaWallet IDs serve all VivaWallet payment methods installed in the store. VivaWallet Code is a common configuration key, the content of which is selected per domain. If the store has multiple domains, each of them needs its own Website/App line in the Viva service and a corresponding code in AI Commerce .

1. Install the necessary VivaWallet payment modules

VivaWallet payment modules are installed in the admin under Configurations > Payments . Select Install payment module , select the VivaWallet payment method you need from the list of known modules and confirm the installation with the Install module button. Open the settings of the installed module before enabling it at the checkout.

Options to install may include VivaWallet Payment Cards, VivaWallet Apple Pay, VivaWallet Google Pay, VivaWallet PayPal, and VivaWallet Klarna.

• Only install the options that are included in your contract and intended use.
• Changes made to the module settings are automatically saved via the settings editor, but the payment method must still be tested separately for each installed option.

2. Add shared VivaWallet IDs

VivaWallet payment methods use common identifiers: "VivaWallet Merchant ID", "VivaWallet API Key", "VivaWallet Client ID" and "VivaWallet Client Secret".

• Retrieve their current values from the Viva service under "Viva Settings > API Access" and enter them into the corresponding VivaWallet settings in AI Commerce .
• The client ID and API key are secrets, so they should not be written in instructions or support messages.

AI Commerce 's current Integrations view identifies the VivaWallet integration MODULE_PAYMENT_VIVAWALLET_CLIENT_ID and MODULE_PAYMENT_VIVAWALLET_CLIENT_SECRET keys.

• The merchant ID and API key are used to verify payment confirmation, so they must also be correct in the payment module settings.
• Check the characters without extra spaces and use the same Viva account values for all VivaWallet payment modules in the store.

3. Add the VivaWallet code to each domain

"VivaWallet Code" or MODULE_PAYMENT_VIVAWALLET_SOURCECODE is defined per domain. In Viva, open "Viva Sales > Online Payments > Websites/Apps", create a separate Website/App row for each domain and copy its code value. Add each code to the correct domain in AI Commerce 's "VivaWallet Code" setting.

AI Commerce reads the domain identifier indexed map from the setting and aborts the payment request if no code is found for the current domain. So do not copy the code for one domain to all rows. For each domain, check that the payment request uses the exact Viva Website/App target intended for that store.

4. Configure the VivaWallet webhook

The webhook address for VivaWallet payment confirmations is set to the store's own domain address https://OMA-DOMAINISI/api/webhook/vivawallet . Replace OMA-DOMAINISI with the store's actual HTTPS domain. The webhook receives VivaWallet verification and payment transactions so that the payment confirmation can be assigned to AI Commerce order.

Configure a webhook for the relevant Website/App item in the Viva service and ensure that the address is externally accessible via HTTPS. Use its own domain name for each environment; events in the test environment must not hit the webhook in the production store. Make a successful test payment and ensure that the order payment confirmation is updated before opening the payment method to customers.

5. Configure failure and success return addresses

The return address for a failed VivaWallet payment will be redirected back to the store's checkout. The checkout path for a Finnish-language store is usually /kassa , but always use the actual checkout path for that domain. Do not use the generic /api/checkout/callback/vivawallet address as the address for a successful payment.

A successful payment must be returned to the installed VivaWallet payment method's own checkout callback so that AI Commerce checks the return parameters, completes the order, and redirects the customer to the thank you page.

• The exact payment method-specific suffix of the return address depends on the installed module.
• Verify the current callback for each payment method from the local implementation and Viva service settings before production use.

6. Complete your payment method settings

The custom settings for the VivaWallet payment module are finalized after the common identifiers, source code and addresses. Check at least Payment region , Default order status , Payment Name , Payment Description and Payment Conditions . Choose values according to the store region, order processing and the text to be displayed to customers.

Also, ensure the module's usage mode, order, and any customer type, delivery method, or region restrictions before testing. The visible payment method name, description, and terms should be checked in each store language. Changes are automatically saved in the current payment module settings editor, so make changes in a controlled manner and check the saved value before moving to the next field.

Test VivaWallet before deploying

The VivaWallet installation is tested with each payment method and domain installed. Make a successful payment, abort one payment, and try the incorrect or missing domain-specific code in a test environment. Verify that the customer is returned to the correct checkout or thank you page, the webhook confirms the payment, and the order receives the specified default status.

Additionally, test the payment method's display name, description, terms, region and other restrictions, and Website/App targeting for different domains. If the payment remains open or bounces to the wrong address, keep the payment method disabled and check the IDs, VivaWallet Code , webhook, and payment method-specific callback before retesting.