Medusa.js

Integrer Cost+ med din Medusa.js v2-butikk ved hjelp av det offisielle costplus-medusa-tillegget

Integrer Cost+ som en betalingsleverandør i din Medusa.js v2-butikk. Det offisielle costplus-medusa-tillegget registrerer en separat Medusa-betalingsleverandør for hver Cost+-betalingsmetode, bruker flyten med hostet betalingsside, og verifiserer hver statusendring mot Cost+ API-et — fullt PCI DSS-kompatibelt.

Forutsetninger

Aktiv Cost+ forhandlerkonto
Medusa.js 2.14.2 eller nyere
Node.js 22
PostgreSQL-tilgang via Medusas DATABASE_URL
En offentlig HTTPS Medusa backend-URL (kreves for webhooks)
En butikkfront-utsjekking som videresender cart_id ved oppstart av betalingsøkten

Støttede betalingsmetoder

Visningsnavn i utsjekking	Medusa Provider Id	Cost+-identifikator
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`

Hver leverandør oppretter en Cost+-ordre for nøyaktig én betalingsmetode, slik at utsjekkingsalternativene i butikkfronten holder seg samkjørte med Cost+ sin hostede omdirigeringsflyt.

1. Installer tillegget

Installer pakken i ditt Medusa backend-prosjekt:

npm install costplus-medusa

Du kan også installere fra en tagget Git-utgivelse: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registrer tillegget og leverandøren

Legg til tillegget og betalingsleverandøren i din 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: {},
          },
        ],
      },
    },
  ],
})

Start Medusa-backend på nytt slik at det nye tillegget og leverandøren lastes inn.

3. Konfigurer i Admin

I Medusa Admin, åpne Cost+ (rute /app/costplus) og konfigurer:

API Key — din forhandler-API-nøkkel fra forhandlerportalen (Websites → ditt nettsted → Integration)
Checkout Expiry — tidsavbrudd i minutter (sendes til Cost+ som ISO-8601-varighet, f.eks. 5 → PT5M, standard er 5 minutter)
Manual Capture — valgfri, autoriser kortbetalinger uten umiddelbar uttrekking
Debug Logging — valgfri, logg API-forespørsler og svar for feilsøking

På samme Cost+ Admin-side aktiverer du betalingsmetodene du vil eksponere for hver region:

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

Aktiver kun betalingsmetodene du har blitt godkjent for og mottatt bekreftelse på.

Når du slår metoder av eller på på denne siden, oppdateres Medusas regionsbetalingsleverandør-koblinger for Cost+-leverandørene, slik at det vanlige Store API-endepunktet /store/payment-providers?region_id=... bare returnerer aktiverte Cost+-metoder. Hvis alle Cost+-metoder er deaktivert for en region, returnerer Store API ingen Cost+-leverandører for den regionen.

4. Integrasjon i butikkfront

Når du starter en Cost+-betalingsøkt, send Medusa cart_id i 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}`,
  },
})

Etter at økten er opprettet, omdiriger kunden til payment_session.data.costplus_payment_url.

Standard suksess-rute er /checkout/costplus/return?cart_id={cart_id} — den siden bør kalle Medusas complete-cart-endepunkt og deretter vise ordrebekreftelsessiden. Failure-URL-en bør returnere kunden til betalingstrinnet uten å fullføre handlekurven.

Retur- og webhook-håndtering verifiserer alltid Cost+-ordren med GET /orders/{id}/ før betalingstilstanden mappes tilbake til Medusa.

Hent betalingsmetoder fra Store API

Hent betalingsmetoder fra Medusas Store API i stedet for å hardkode Cost+-leverandør-ID-er i butikkfronten. Hvis butikkfronten cacher /store/payment-providers, bruk no-store eller invalider cachen etter metodeendringer i Admin, slik at deaktiverte metoder forsvinner umiddelbart fra utsjekken.

For en referanseimplementasjon, se examples/nextjs/costplus-return/ i costplus-medusa-repositoriet — en Next.js DTC starter-returside som kombinerer en klient-håndterer med en server action, slik at handlekurv-fullføring skjer utenfor sidegjengivelsen og omdirigerer pålitelig til /order/{id}/confirmed.

5. Webhooks

Tillegget registrerer automatisk et webhook-endepunkt på /hooks/payment/{identifier}_costplus. Medusa-backend-URL-en må være offentlig tilgjengelig over HTTPS slik at Cost+ kan levere asynkrone statusoppdateringer.

Hvis ordrer forblir ventende lenge etter den konfigurerte utløpstiden, peker det på et problem med webhook-levering eller returflyten heller enn selve utløpsinnstillingen.

6. Sikkerhet og lagring av innstillinger

API-nøkkelen krypteres før den lagres i Medusa-databasen. Sett COSTPLUS_SETTINGS_SECRET i produksjon:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Hvis COSTPLUS_SETTINGS_SECRET ikke er satt, faller tillegget tilbake til Medusas COOKIE_SECRET eller JWT_SECRET.

Sett COSTPLUS_API_KEY i miljøet for å låse API-nøkkelens kilde — når den er satt, vil ikke Admin-siden overskrive den. La den stå tom når forhandlerne skal administrere nøkkelen i Admin.

7. Test og lansering

Cost+-miljøet bestemmes av API-nøkkelen — en sandkasse-nettstedsnøkkel kjører i testmodus, en produksjonsnøkkel kjører i live-modus (ingen separat sandkasse-URL). Utfør noen testtransaksjoner for å verifisere vellykkede, avbrutte og utløpte flyter før du går live.

Støtte

Trenger du hjelp? Ta kontakt med supportteamet vårt på support@costplus.io.

Medusa.js

On this page