Medusa.js

Integreerige Cost+ makseteenuse pakkujana oma Medusa.js v2 poega. Ametlik plugin costplus-medusa registreerib eraldi Medusa makseteenuse pakkuja iga Cost+ makseviisi jaoks, kasutab hostitud makselehe voogu ja kontrollib iga olekumuutust Cost+ API kaudu — täielikult PCI DSS-iga ühilduv.

Eeldused

Aktiivne Cost+ kaupmehe konto
Medusa.js 2.14.2 või uuem
Node.js 22
PostgreSQL juurdepääs Medusa DATABASE_URL kaudu
Avalik HTTPS Medusa backendi URL (vajalik veebihaakide jaoks)
Esindusliku poe kassa, mis edastab cart_id makseseansi käivitamisel

Toetatud makseviisid

Kassa nimi	Medusa pakkuja ID	Cost+ identifikaator
Credit / Debit Card	`pp_costplus-credit-card_costplus`	`credit-card`
Apple Pay	`pp_costplus-apple-pay_costplus`	`apple-pay`
Google Pay	`pp_costplus-google-pay_costplus`	`google-pay`
Vipps MobilePay	`pp_costplus-vipps-mobilepay_costplus`	`vipps-mobilepay`

Iga pakkuja loob Cost+ tellimuse täpselt ühe makseviisi jaoks, nii et poe kassa valikud jäävad kooskõlla Cost+ hostitud makse ümbersuunamise vooga.

1. Paigaldage plugin

Paigaldage pakett oma Medusa backend projekti:

npm install costplus-medusa

Saate paigaldada ka tagiga Git väljalaskest: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registreerige plugin ja pakkuja

Lisage plugin ja makseteenuse pakkuja oma faili medusa-config.ts:

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: {},
          },
        ],
      },
    },
  ],
})

Taaskäivitage Medusa backend, et uus plugin ja pakkuja laaditaks.

3. Konfigureerige Adminis

Avage Medusa Adminis Cost+ (tee /app/costplus) ja konfigureerige:

API võti — teie kaupmehe API võti kaupmehe portaalist (Websites → teie veebileht → Integration)
Kassa aegumine — ajalõpp minutites (saadetakse Cost+ keskkonda ISO-8601 kestusena, nt 5 → PT5M, vaikimisi 5 minutit)
Käsitsi sisselugemine — valikuline, autoriseerib kaardimakseid ilma kohese sisselugemiseta
Debug logimine — valikuline, logib API päringud ja vastused tõrkeotsinguks

Samal Cost+ Admini lehel lubage makseviisid, mida soovite iga regiooni jaoks kuvada:

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

Aktiveerige ainult need makseviisid, mille jaoks olete saanud kinnituse.

Meetodite sisse-/väljalülitamine sellel lehel uuendab Medusa piirkonna makseteenusepakkujate linke Cost+ pakkujate jaoks, nii et standardne Store API lõpp-punkt /store/payment-providers?region_id=... tagastab ainult lubatud Cost+ meetodid. Kui kõik Cost+ meetodid on piirkonna jaoks keelatud, ei tagasta Store API selle piirkonna jaoks ühtegi Cost+ pakkujat.

4. Esindusliku poe integratsioon

Cost+ makseseansi käivitamisel edastage Medusa cart_id parameetris data:

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}`,
  },
})

Pärast seansi loomist suunake ostja aadressile payment_session.data.costplus_payment_url.

Vaikimisi õnnestumise tee on /checkout/costplus/return?cart_id={cart_id} — see leht peaks kutsuma Medusa complete-cart endpoint'i ja seejärel kuvama tellimuse kinnituse lehe. Failure URL peaks suunama ostja tagasi makseetapile, ilma ostukorvi lõpetamata.

Tagasipöördumise ja veebihaaki käsitlemine kontrollib alati Cost+ tellimust käsuga GET /orders/{id}/ enne makseoleku tagasi vastendamist Medusa keskkonda.

Maksemeetodite loendamine Store API-st

Loendage maksemeetodid Medusa Store API-st, mitte ärge kodeerige Cost+ pakkujate ID-sid otse oma poodi. Kui pood vahemustab /store/payment-providers, kasutage no-store või tühistage vahemälu pärast meetodite muudatusi Adminis, et keelatud meetodid kaoksid kassast kohe.

Näidisrealisatsiooni leiate kataloogist examples/nextjs/costplus-return/ costplus-medusa hoidlas — Next.js DTC starteri tagasipöördumislehekülg, mis ühendab kliendipoolse käitleja serveri toiminguga, nii et ostukorvi lõpetamine toimub väljaspool lehe renderdamist ja suunab usaldusväärselt aadressile /order/{id}/confirmed.

5. Veebihaagid

Plugin registreerib automaatselt veebihaagi endpoint'i aadressil /hooks/payment/{identifier}_costplus. Medusa backendi URL peab olema avalikult HTTPS-i kaudu kättesaadav, et Cost+ saaks edastada asünkroonseid olekuvärskendusi.

Kui tellimused jäävad ootele kaua pärast konfigureeritud aegumist, viitab see veebihaagi edastamise või tagasipöördumise voo probleemile, mitte aegumissättele endale.

6. Turvalisus ja seadete salvestamine

API võti krüpteeritakse enne Medusa andmebaasi salvestamist. Tootmiskeskkonnas määrake COSTPLUS_SETTINGS_SECRET:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Kui COSTPLUS_SETTINGS_SECRET pole määratud, kasutab plugin Medusa COOKIE_SECRET või JWT_SECRET varuks.

Määrake keskkonnas COSTPLUS_API_KEY, et lukustada API võtme allikas — kui see on määratud, ei kirjuta Admini leht seda üle. Jätke see tühjaks, kui kaupmehed peaksid võtit Adminis haldama.

7. Testimine ja käivitamine

Cost+ keskkond määratakse API võtme põhjal — sandbox veebilehe võti töötab testreºiimis, tootmise veebilehe võti töötab reaalreºiimis (eraldi sandbox URL-i pole). Enne reaalreºiimi minekut tehke mõned testtehingud, et kinnitada edukad, tühistatud ja aegunud vood.

Tugi

Vajate abi? Pöörduge meie tugimeeskonna poole aadressil support@costplus.io.

Medusa.js

On this page