Medusa.js

Integrer Cost+ med din Medusa.js v2-butik ved hjælp af det officielle costplus-medusa plugin

Integrer Cost+ som betalingsudbyder i din Medusa.js v2-butik. Det officielle costplus-medusa-plugin registrerer en separat Medusa-betalingsudbyder for hver Cost+-betalingsmetode, bruger Hosted Payment Page-flowet og verificerer hver statusændring mod Cost+ API'et — fuldt PCI DSS-kompatibelt.

Forudsætninger

Aktiv Cost+-forhandlerkonto
Medusa.js 2.14.2 eller nyere
Node.js 22
PostgreSQL-adgang via Medusas DATABASE_URL
En offentlig HTTPS Medusa backend-URL (krævet for webhooks)
Et storefront-checkout, der videregiver cart_id, når betalingssessionen initieres

Understøttede betalingsmetoder

Checkout-navn	Medusa-udbyder-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 udbyder opretter en Cost+-ordre for præcis én betalingsmetode, så storefront-checkout-mulighederne forbliver på linje med Cost+'s hosted payment-omdirigeringsflow.

1. Installer pluginet

Installer pakken i dit Medusa backend-projekt:

npm install costplus-medusa

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

2. Registrer pluginet og udbyderen

Tilføj pluginet og betalingsudbyderen til 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: {},
          },
        ],
      },
    },
  ],
})

Genstart Medusa-backenden, så det nye plugin og udbyderen indlæses.

3. Konfigurer i Admin

I Medusa Admin, åbn Cost+ (sti /app/costplus) og konfigurer:

API Key — din forhandler-API-nøgle fra forhandlerportalen (Websites → dit website → Integration)
Checkout-udløb — timeout i minutter (sendt til Cost+ som ISO-8601-varighed, fx 5 → PT5M, standard er 5 minutter)
Manuel opkrævning — valgfri, autoriser kortbetalinger uden øjeblikkelig opkrævning
Debug-logning — valgfri, logger API-anmodninger og -svar til fejlsøgning

På den samme Cost+ Admin-side aktiverer du de betalingsmetoder, du vil eksponere for hver region:

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

Aktiver kun de betalingsmetoder, du er godkendt til og har modtaget bekræftelse for.

Når du slår metoder til eller fra på denne side, opdateres Medusas regionale betalingsudbyder-links for Cost+-udbydere, så det almindelige Store API-endepunkt /store/payment-providers?region_id=... kun returnerer de aktiverede Cost+-metoder. Hvis alle Cost+-metoder er deaktiveret for en region, returnerer Store API ingen Cost+-udbydere for den region.

4. Storefront-integration

Når du initierer en Cost+-betalingssession, skal du videregive 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}`,
  },
})

Efter sessionen er oprettet, omdiriger kunden til payment_session.data.costplus_payment_url.

Standardsuccessens rute er /checkout/costplus/return?cart_id={cart_id} — den side bør kalde Medusas complete-cart-endpoint og derefter vise ordrebekræftelsessiden. Failure-URL'en skal returnere kunden til betalingstrinnet uden at fuldføre kurven.

Håndtering af retur og webhook verificerer altid Cost+-ordren med GET /orders/{id}/, før betalingstilstanden mappes tilbage til Medusa.

Hent betalingsmetoder fra Store API

Hent betalingsmetoder fra Medusas Store API i stedet for at hardcode Cost+-udbyder-id'er i din storefront. Hvis din storefront cacher /store/payment-providers, så brug no-store eller invalider cachen efter metodeændringer i Admin, så deaktiverede metoder forsvinder med det samme fra checkout.

Se en referenceimplementering i examples/nextjs/costplus-return/ i costplus-medusa-repositoryet — en Next.js DTC starter-returside, der kombinerer en klient-handler med en server action, så cart completion sker uden for sideopretningen og pålideligt omdirigerer til /order/{id}/confirmed.

5. Webhooks

Pluginet registrerer automatisk et webhook-endpoint på /hooks/payment/{identifier}_costplus. Medusa backend-URL'en skal være offentligt tilgængelig over HTTPS, så Cost+ kan levere asynkrone statusopdateringer.

Hvis ordrer forbliver afventende længe efter den konfigurerede udløbstid, peger det på et webhook-leverings- eller retur-flow-problem snarere end selve udløbsindstillingen.

6. Sikkerhed og lagring af indstillinger

API-nøglen krypteres, før den gemmes i Medusa-databasen. Sæt COSTPLUS_SETTINGS_SECRET i produktion:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Hvis COSTPLUS_SETTINGS_SECRET ikke er sat, falder pluginet tilbage til Medusas COOKIE_SECRET eller JWT_SECRET.

Sæt COSTPLUS_API_KEY i miljøet for at låse API-nøglekilden — når den er sat, vil Admin-siden ikke overskrive den. Lad den være tom, når forhandlerne skal administrere nøglen i Admin.

7. Test og lancering

Cost+-miljøet bestemmes af API-nøglen — en sandbox-website-nøgle kører i testtilstand, en produktions-website-nøgle kører i live-tilstand (ingen separat sandbox-URL). Foretag et par testtransaktioner for at verificere succesfulde, annullerede og udløbne flows, før du går live.

Support

Brug for hjælp? Kontakt vores supportteam på support@costplus.io.

Medusa.js

On this page