Tässä ohjeessa asennat Viva Payments -maksutavan AI Commerceen ja teet Vivan puolella tarvittavat asetukset (API Access, Webhook sekä Websites/Apps). Kun nämä on tehty oikein, maksut vahvistuvat ja tilaukset muodostuvat verkkokauppaan myös maa-/domaikohtaisesti.

Mistä editoidaan

• AI Commerce Hallintapaneeli: Modules > Payment (maksutavan asennus ja perusasetukset, sekä Viva-avainten syöttö)
• Viva.com: Settings > API Access (Merchant ID, API Key, Client ID, Client Secret sekä Webhooks)
• Viva.com: Sales > Online Payments > Websites/Apps (domain-kohtaiset koodit ja palautus-URL:t)

1) Asenna Viva Payments -moduuli AI Commercessa

1. Avaa AI Commerce Hallintapaneeli ja siirry sivulle Modules > Payment.
2. Jos et näe Vivan maksutapoja asennettuna, paina Install Module.
3. Valitse haluttu Vivan maksutapa ja paina sen jälkeen uudestaan Install Module.
4. Kun asennus on valmis, avaa maksutavan asetukset konfigurointia varten.

2) Yhteiset tunnukset kaikille Viva-maksutavoille

Kaikki Vivan maksutavat käyttävät jaettuja arvoja kentille Merchant ID, API Key, Client ID ja Client Secret.

• Riittää, että asetat arvot ensimmäisen kerran yhdelle Viva-maksutavalle.
• Muut Vivan maksutavat voivat käyttää samoja arvoja.
• Jos et näe muissa Viva-maksutavoissa samoja tietoja, copy/pasteta samat arvot kaikkiin Vivan maksutapoihin.

3) Hae Merchant ID, API Key, Client ID ja Client Secret vivasta

1. Kirjaudu sisään viva.comiin (”kirjaudu sisään”) ja avaa Merchantin asetukset.
2. Siirry sivulle Settings > API Access.
3. Etsi ja kopioi seuraavat arvot:
   • Merchant ID
   • API Key
   • SmartShop Client ID (Vivan näkymässä tämä löytyy tyypillisesti Smart Checkout Credentials -kohdasta Client ID)
   • Client Secret (salaisuus, jonka saat Smart Checkout -/SmartShop-osiosta; tarvittaessa käytä toimintoa “Forgot your secret? Generate a new one.”)
4. Syötä arvot AI Commerceen maksutavan kenttiin:
   • Viva Walletin Merchant ID ← Merchant ID
   • API Key ← API Key
   • Client ID ← SmartShop/Smart Checkout Client ID
   • Client Secret ← Client Secret

Huomio maksutavan muista asetuksista

Tämä ohje ei käsittele muita maksutavan hallintaan liittyviä peruskonfiguraatioita. Näistä on erillinen ohjeartikkeli, jossa käydään läpi mm. maksutavan näkyvyys, nimeäminen, kuvaukset jne.

4) Määritä Webhook Viva.comissa

1. Kun olet sivulla Settings > API Access, vaihda välilehdeltä General välilehdelle Webhooks.
2. Luo uusi webhook (esim. “Create Webhook”) tai muokkaa olemassa olevaa webhookia painamalla listauksesta Edit.
3. Aseta webhookin URL kauppasi domainiin. Tähän riittää mikä tahansa verkkotunnus, jos sinulla on monta domainia.
4. Esimerkkipolku (käytä aina omaa domainiasi, älä käytä “sinun-kauppa.fi”):
   • https://OMA-DOMAINISI.fi/api/webhook/vivawallet

Miksi webhook tarvitaan?

• Tätä webhookia käytetään maksujen vahvistamiseen jälkikäteen.
• Tietyt maksut vahvistetaan jälkikäteen Vivan puolesta.
• Tilaus syntyy ensin tilassa ”odottaa maksua”.
• Kun maksu on prosessoitu, Viva tekee erillisen webhook-kutsun tähän polkuun.
• Näin Viva varmistaa, että maksu on onnistunut eikä kyseessä ole petos.
• Tätä asetusta ei aseteta mihinkään kaupassa erikseen, vaan se tulee Viva.comin Webhooks-asetuksista.

5) Lisää Websites/Apps-rivit jokaiselle domainille

1. Siirry Viva.comissa välilehdelle Sales.
2. Avaa Online Payments ja sen alta Websites/Apps.
3. Tarvitset jokaiselle verkkotunnukselle oman rivin, eli jokaiselle eri domainille tulee oma koodi ja domainin nimi.
4. Jos verkkotunnuksia ei ole vielä luotu, paina Add Website/App.
5. Kun domain on lisätty, näet listauksessa domainin rivillä luodun Code-arvon (esim. 1111).
6. Tämä koodi syötetään AI Commerce Hallintapaneelissa maksutavan kenttään Vivawallet Code.
7. Koodi voi olla esimerkiksi 111 tai 2222 (käytännössä 3–4 numeroa; kuvien esimerkeissä koodi on neljä numeroa).

6) Täytä “Edit Payment Source: Website/Mobile App” -kentät

Kun klikkaat domain-rivin Code-numeroa (esim. 1111) Websites/Apps-listassa, avautuu muokkausnäkymä “Edit Payment Source: Website/Mobile App”. Täytä kentät näin (domain-kohtaisesti):

• Source Name: kaupan verkkotunnus (esim. oma-kauppa.pro)
• Domain Name: sama verkkotunnus kuin Source Name -kentässä (suositus: käytä samaa nimeä molemmissa)
• Protocol: valitse HTTPS
• Integration method: valitse Redirection/Native Checkout v2 (eli “Redirection kautta Native Checkout version 2”)
• Company Logo: lisää oma logo, jotta asiakkaat näkevät teidän logon maksamisen aikana (ohjeen mukainen tiedosto: Transparent PNG, up to 100 Kb)
• Success URL: domainin jälkeen polku api/checkout/callback/vivawallet
  • Esimerkki: https://OMA-DOMAINISI.fi/api/checkout/callback/vivawallet
• Failure URL: pelkkä checkout
  • Esimerkki: https://OMA-DOMAINISI.fi/checkout
• Advanced Configuration: ruksaa kaikki suostumukset (mm. julkinen domain, privacy & data security policy, toimitus- ja palautusehdot, asiakaspalvelun yhteystiedot, viva.com-logo maksunäkymissä)
• Tallenna painamalla Update

Tärkeä huomio muokkaamisesta

• Viva.com voi vaatia muutoksille hyväksynnän, ja muokkaus voi väliaikaisesti tehdä source-rivin inaktiiviseksi.
• Varmista, että Websites/Apps-rivisi on lopuksi kunnossa ja aktiivinen (Status: Active), jotta maksut toimivat kyseisellä domainilla.

7) Miksi Vivan tilaus ei muodostu kauppaan?

• Kun Websites/Apps-asetus tehdään ja Success URL on oikein, asiakkaat ohjataan maksun jälkeen oikeaan paluuosoitteeseen ja tilaus pääsee muodostumaan.
• Mikäli tätä ei tehdä, tilaukset kyseisessä maa-/domain-ympäristössä eivät muodostu verkkokauppaan.

Yhteenveto

Asenna Viva Payments AI Commercessa, syötä Merchant ID, API Key, Client ID ja Client Secret, määritä Webhooks-URL sekä luo jokaiselle domainille oma Websites/Apps-rivi ja koodi. Lopuksi varmista, että Success URL ja Failure URL on kirjoitettu täsmälleen oikein ja että domainin source on aktiivinen.

Avainsanat

• Viva Payments
• Viva Wallet
• AI Commerce
• Modules > Payment
• Settings > API Access
• Merchant ID
• API Key
• Webhooks
• Websites/Apps
• Vivawallet Code