Medusa.js

Integroi Cost+ maksupalveluntarjoajaksi Medusa.js v2 -kauppaasi. Virallinen costplus-medusa-lisäosa rekisteröi erillisen Medusa-maksupalveluntarjoajan jokaiselle Cost+-maksutavalle, käyttää isännöidyn maksusivun kulkua ja varmentaa jokaisen tilan muutoksen Cost+ API:n kautta — täysin PCI DSS -yhteensopiva.

Edellytykset

• Aktiivinen Cost+-kauppiastili
• Medusa.js 2.14.2 tai uudempi
• Node.js 22
• PostgreSQL-yhteys Medusan DATABASE_URL-osoitteen kautta
• Julkinen HTTPS Medusa backend -URL (vaaditaan webhookeja varten)
• Storefront-kassa, joka välittää cart_id:n maksusessiota käynnistettäessä

Tuetut maksutavat

Jokainen palveluntarjoaja luo Cost+-tilauksen tasan yhdelle maksutavalle, joten storefrontin kassavalinnat pysyvät linjassa Cost+:n isännöidyn maksun uudelleenohjausvirran kanssa.

1. Asenna lisäosa

Asenna paketti Medusa backend -projektiisi:

npm install costplus-medusa

2. Rekisteröi lisäosa ja palveluntarjoaja

Lisää lisäosa ja maksupalveluntarjoaja medusa-config.ts-tiedostoosi:

import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  plugins: [
    {
      resolve: "costplus-medusa",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "costplus-medusa/providers/costplus",
            id: "costplus",
            options: {},
          },
        ],
      },
    },
  ],
})

Käynnistä Medusa backend uudelleen, jotta uusi lisäosa ja palveluntarjoaja latautuvat.

3. Määritä Adminissa

Avaa Medusa Adminissa Cost+ (reitti /app/costplus) ja määritä:

• API-avain — kauppias-API-avaimesi kauppiasportaalista (Websites → verkkosivustosi → Integration)
• Kassan vanhentuminen — aikakatkaisu minuutteina (lähetetään Cost+:lle ISO-8601-kestona, esim. 5 → PT5M, oletus on 5 minuuttia)
• Manuaalinen veloitus — valinnainen, valtuuttaa korttimaksut ilman välitöntä veloitusta
• Debug-lokitus — valinnainen, kirjaa API-pyynnöt ja -vastaukset vianmääritystä varten

Ota samalla Cost+ Admin -sivulla käyttöön ne maksutavat, jotka haluat näyttää kullekin alueelle:

• Cost+ Credit / Debit Card
• Cost+ Apple Pay
• Cost+ Google Pay
• Cost+ Vipps MobilePay

4. Storefront-integraatio

Kun käynnistät Cost+-maksusession, välitä Medusan cart_id data-kentässä:

await sdk.store.payment.initiatePaymentSession(paymentCollection.id, {
  provider_id: "pp_costplus-credit-card_costplus",
  data: {
    cart_id: cart.id,
    return_url: `${origin}/${countryCode}/checkout/costplus/return?cart_id=${cart.id}`,
    failure_url: `${origin}/${countryCode}/checkout?step=payment&costplus_cancelled=1&cart_id=${cart.id}`,
  },
})

Kun sessio on luotu, ohjaa ostaja osoitteeseen payment_session.data.costplus_payment_url.

Onnistumisen oletusreitti on /checkout/costplus/return?cart_id={cart_id} — kyseisen sivun tulisi kutsua Medusan complete-cart-endpointia ja sen jälkeen näyttää tilausvahvistussivu. Failure-URL:n tulisi palauttaa ostaja maksuvaiheeseen viemättä ostoskoria loppuun.

Maksutapojen listaaminen Store API:sta

Listaa maksutavat Medusan Store API:sta sen sijaan, että kovakoodaisit Cost+-palveluntarjoajien tunnukset storefronttiin. Jos storefront välimuistittaa /store/payment-providers-vastauksen, käytä no-store-asetusta tai mitätöi välimuisti Adminissa tehtyjen muutosten jälkeen, jotta poistetut maksutavat katoavat kassasta välittömästi.

5. Webhookit

Lisäosa rekisteröi automaattisesti webhook-endpointin osoitteeseen /hooks/payment/{identifier}_costplus. Medusa backendin URL:n on oltava julkisesti tavoitettavissa HTTPS:n kautta, jotta Cost+ voi toimittaa asynkronisia tilan päivityksiä.

Jos tilaukset pysyvät odottavina kauan määritetyn vanhentumisajan jälkeen, se viittaa webhookin toimitus- tai paluuvirtaongelmaan, ei itse vanhentumisasetukseen.

6. Tietoturva ja asetusten tallennus

API-avain salataan ennen tallennusta Medusa-tietokantaan. Aseta tuotannossa COSTPLUS_SETTINGS_SECRET:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Jos COSTPLUS_SETTINGS_SECRET-arvoa ei ole asetettu, lisäosa palaa Medusan COOKIE_SECRET- tai JWT_SECRET-arvoon.

7. Testaa ja julkaise

Cost+-ympäristö määräytyy API-avaimen perusteella — sandbox-verkkosivuston avain toimii testitilassa, tuotantoverkkosivuston avain toimii live-tilassa (ei erillistä sandbox-URL:ää). Tee muutamia testitapahtumia varmistaaksesi onnistuneet, peruutetut ja vanhentuneet kulut ennen julkaisua.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.