Medusa.js

Integrera Cost+ med din Medusa.js v2-butik via det officiella costplus-medusa-pluginet

Integrera Cost+ som betalningsleverantör i din Medusa.js v2-butik. Det officiella costplus-medusa-pluginet registrerar en separat Medusa-betalningsleverantör för varje Cost+-betalningsmetod, använder Hosted Payment Page-flödet och verifierar varje statusändring mot Cost+ API:et — fullt PCI DSS-kompatibelt.

Förutsättningar

Aktivt Cost+-handelskonto
Medusa.js 2.14.2 eller senare
Node.js 22
PostgreSQL-åtkomst via Medusas DATABASE_URL
En offentlig HTTPS-URL till Medusa-backend (krävs för webhooks)
En storefront-kassa som skickar med cart_id när betalningssessionen initieras

Betalningsmetoder som stöds

Kassanamn	Medusa Provider Id	Cost+-identifierare
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`

Varje leverantör skapar en Cost+-order för exakt en betalningsmetod, så att kassaalternativen i storefronten förblir i linje med Cost+ Hosted Payment-omdirigeringsflödet.

1. Installera pluginet

Installera paketet i ditt Medusa-backendprojekt:

npm install costplus-medusa

Du kan även installera från en taggad Git-release: npm install git+ssh://git@github.com:NoPayn/costplus-medusa.git#vX.Y.Z

2. Registrera pluginet och leverantören

Lägg till pluginet och betalningsleverantö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: {},
          },
        ],
      },
    },
  ],
})

Starta om Medusa-backenden så att det nya pluginet och leverantören laddas.

3. Konfigurera i Admin

I Medusa Admin, öppna Cost+ (rutten /app/costplus) och konfigurera:

API Key — din handlar-API-nyckel från handlarportalen (Websites → din webbplats → Integration)
Checkout Expiry — timeout i minuter (skickas till Cost+ som ISO-8601-varaktighet, t.ex. 5 → PT5M, standard är 5 minuter)
Manual Capture — valfritt, auktorisera kortbetalningar utan omedelbar capture
Debug Logging — valfritt, logga API-förfrågningar och svar för felsökning

På samma Cost+ Admin-sida aktiverar du de betalningsmetoder du vill exponera för varje region:

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

Aktivera bara de betalningsmetoder du har blivit godkänd för och fått bekräftelse på.

Att slå på eller av metoder på den här sidan uppdaterar Medusas regionala betalningsleverantörslänkar för Cost+-leverantörer, så att standardendpoint Store API /store/payment-providers?region_id=... bara returnerar de aktiverade Cost+-metoderna. Om alla Cost+-metoder är inaktiverade för en region returnerar Store API inga Cost+-leverantörer för den regionen.

4. Storefront-integration

När du initierar en Cost+-betalningssession, skicka med 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}`,
  },
})

När sessionen har skapats, omdirigera kunden till payment_session.data.costplus_payment_url.

Standard-success-rutten är /checkout/costplus/return?cart_id={cart_id} — den sidan ska anropa Medusas complete-cart-endpoint och därefter visa orderbekräftelsesidan. Failure-URL:en ska skicka tillbaka kunden till betalningssteget utan att slutföra varukorgen.

Retur- och webhookhantering verifierar alltid Cost+-ordern med GET /orders/{id}/ innan betalningstillståndet mappas tillbaka till Medusa.

Hämta betalningsmetoder från Store API

Hämta betalningsmetoder från Medusas Store API i stället för att hårdkoda Cost+-leverantörs-ID:n i din storefront. Om storefronten cachar /store/payment-providers, använd no-store eller ogiltigförklara cachen efter metodändringar i Admin, så att inaktiverade metoder försvinner direkt från kassan.

För en referensimplementation, se examples/nextjs/costplus-return/ i costplus-medusa-repot — en återvändo-sida för Next.js DTC-starter som kombinerar en klient-hanterare med en server action, så att kundvagnens slutförande sker utanför sidrendering och tillförlitligt omdirigerar till /order/{id}/confirmed.

5. Webhooks

Pluginet registrerar automatiskt en webhook-endpoint på /hooks/payment/{identifier}_costplus. Medusa-backendens URL måste vara publikt nåbar via HTTPS så att Cost+ kan leverera asynkrona statusuppdateringar.

Om order förblir i väntande tillstånd långt efter den konfigurerade utgångstiden tyder det på ett problem med webhook-leverans eller returflödet snarare än med själva utgångsinställningen.

6. Säkerhet och lagring av inställningar

API-nyckeln krypteras innan den lagras i Medusa-databasen. Sätt COSTPLUS_SETTINGS_SECRET i produktion:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Om COSTPLUS_SETTINGS_SECRET inte är satt faller pluginet tillbaka på Medusas COOKIE_SECRET eller JWT_SECRET.

Sätt COSTPLUS_API_KEY i miljön för att låsa API-nyckelns källa — när den är satt skriver Admin-sidan inte över den. Lämna den tom när handlare ska hantera nyckeln i Admin.

7. Testa och lansera

Cost+-miljön bestäms av API-nyckeln — en sandbox-webbplatsnyckel körs i testläge, en produktionsnyckel körs i live-läge (ingen separat sandbox-URL). Genomför några testtransaktioner för att verifiera lyckade, avbrutna och utgångna flöden innan du går live.

Support

Behöver du hjälp? Kontakta vårt supportteam på support@costplus.io.

Medusa.js

On this page